Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
chore: add comprehensive documentation for CI/CD actions (#17702)
boojacka59142d98dcd
diff --git a/frontend/.prettierignore b/frontend/.prettierignoreindex 937dd8b9d7..7eb738396d 100644--- a/frontend/.prettierignore+++ b/frontend/.prettierignore@@ -2,6 +2,7 @@**/*.yaml**/*.yml**/*.json+**/*.mdsrc/assetssrc/shims-3rd-party.d.tsdiff --git a/frontend/src/components/Plan/components/HeaderSection/Actions/ACTIONS.md b/frontend/src/components/Plan/components/HeaderSection/Actions/ACTIONS.mdnew file mode 100644index 0000000000..46e053a7f7--- /dev/null+++ b/frontend/src/components/Plan/components/HeaderSection/Actions/ACTIONS.md@@ -0,0 +1,261 @@+# Plan Header Actions Documentation++This document describes all available actions in the Plan Header section, including visibility rules, permissions, and disabled states.++## Overview++Actions are displayed in the Plan Header based on the current state of the plan, issue, and rollout. Actions are divided into:++- **Primary Actions**: Displayed as prominent buttons (usually blue or green)+- **Secondary Actions**: Displayed in the dropdown menu (three-dot menu)++## Action Types++### Plan Actions++#### `ISSUE_CREATE` (Primary)+**Label**: "Ready for review"++**Description**: Creates an issue from the plan and initiates the approval workflow.++**Visibility**:+- Plan has no issue attached (`plan.issue === ""`)+- Plan has no rollout attached (`plan.rollout === ""`)+- Plan is in ACTIVE state+- User has `bb.issues.create` permission++**Disabled When**:+- Any spec has an empty statement+- Plan checks are currently running+- Plan checks failed and SQL review is enforced (`project.enforceSqlReview`)++**Disabled Tooltip**:+- "Missing statement"+- "Plan checks are running"+- "Some task checks didn't pass" (when SQL review enforced)++---++#### `PLAN_CLOSE` (Secondary)+**Label**: "Close"++**Description**: Closes (archives) the plan.++**Visibility**:+- Plan has no issue attached (`plan.issue === ""`)+- Plan has no rollout attached (`plan.rollout === ""`)+- Plan is in ACTIVE state+- User is the plan creator OR has `bb.plans.update` permission++---++#### `PLAN_REOPEN` (Primary)+**Label**: "Reopen"++**Description**: Reopens a closed (archived) plan.++**Visibility**:+- Plan has no issue attached (`plan.issue === ""`)+- Plan has no rollout attached (`plan.rollout === ""`)+- Plan is in DELETED state+- User is the plan creator OR has `bb.plans.update` permission++---++### Issue Review Actions++#### `ISSUE_REVIEW_APPROVE` (Primary)+**Label**: "Approve"++**Description**: Approves the current approval step.++**Visibility**:+- Issue exists and is OPEN+- Issue approval status is PENDING or REJECTED (not yet approved)+- User is in the current approval step's candidate list++**Notes**:+- When issue has been rejected, only APPROVE action is shown (no REJECT)+- Approval flow is determined by the approval template roles++---++#### `ISSUE_REVIEW_REJECT` (Secondary)+**Label**: "Send back"++**Description**: Rejects the current approval step and sends the issue back.++**Visibility**:+- Issue exists and is OPEN+- Issue approval status is PENDING (not yet approved)+- Issue has NOT been rejected yet+- User is in the current approval step's candidate list++---++#### `ISSUE_REVIEW_RE_REQUEST` (Primary)+**Label**: "Re-request review"++**Description**: Re-requests approval after the issue was rejected.++**Visibility**:+- Issue exists and is OPEN+- Issue has been rejected (at least one approver has REJECTED status)+- User is the issue creator++---++### Issue Status Actions++#### `ISSUE_STATUS_RESOLVE` (Primary)+**Label**: "Resolve"++**Description**: Marks the issue as resolved (DONE).++**Visibility**:+- Issue exists and is OPEN+- Issue approval status is APPROVED or SKIPPED+- All tasks in the rollout are finished (DONE or SKIPPED)+- User has `bb.issues.update` permission++---++#### `ISSUE_STATUS_CLOSE` (Secondary)+**Label**: "Close"++**Description**: Closes the issue without resolving it (CANCELED).++**Visibility**:+- Issue exists and is OPEN+- User has `bb.issues.update` permission++---++#### `ISSUE_STATUS_REOPEN` (Primary)+**Label**: "Reopen"++**Description**: Reopens a closed or resolved issue.++**Visibility**:+- Issue exists and is CANCELED or DONE+- User has `bb.issues.update` permission++---++### Rollout Actions++#### `ROLLOUT_START` (Primary)+**Label**:+- "Export" (for export data issues)+- "Rollout" (for other issues)++**Description**: Starts or retries tasks in the rollout.++**Visibility**:+- Issue exists and is OPEN+- Issue approval status is APPROVED or SKIPPED+- Rollout has at least one DATABASE_CREATE or DATABASE_EXPORT task+- At least one task is in NOT_STARTED, FAILED, or CANCELED status+- **Permission**:+ - For DATABASE_EXPORT issues: User must be the issue creator+ - For other issues: User must have `bb.taskRuns.create` permission OR match roles in environment rollout policy++**Notes**:+- For DATABASE_EXPORT issues, only the creator can export data (security restriction)+- For other issues, the two-tier permission check applies:+ 1. Users with `bb.taskRuns.create` permission can always rollout+ 2. OR users with matching roles in the environment rollout policy can rollout++---++#### `ROLLOUT_CANCEL` (Secondary)+**Label**: "Cancel"++**Description**: Cancels running or pending tasks.++**Visibility**:+- Issue exists and is OPEN+- Issue approval status is APPROVED or SKIPPED+- At least one task is in PENDING or RUNNING status+- **Permission**: Same as ROLLOUT_START++---++## Global Disabled States++All actions are disabled when:+- Editor is in editing mode (`editorState.isEditing === true`)+- **Tooltip**: "Save changes before continuing"++---++## Action Priority Order++When multiple actions are available, they are prioritized as follows:++### Primary Actions (first match wins):+1. `ISSUE_CREATE` - Create issue from plan+2. `PLAN_REOPEN` - Reopen deleted plan+3. `ISSUE_STATUS_REOPEN` - Reopen closed/done issue+4. `ISSUE_REVIEW_APPROVE` - Approve current step+5. `ISSUE_REVIEW_RE_REQUEST` - Re-request review after rejection+6. `ISSUE_STATUS_RESOLVE` - Resolve completed issue+7. `ROLLOUT_START` - Start/retry tasks++### Secondary Actions (all matching actions shown):+1. `ISSUE_REVIEW_REJECT` - Reject current approval step+2. `ROLLOUT_CANCEL` - Cancel running tasks+3. `ISSUE_STATUS_CLOSE` - Close issue+4. `PLAN_CLOSE` - Close plan++---++## Permission Summary++### Plan Permissions+- `bb.plans.update`: Close or reopen plans+- `bb.issues.create`: Create issues from plans++### Issue Permissions+- `bb.issues.update`: Close, reopen, or resolve issues++### Rollout Permissions+- `bb.taskRuns.create`: Run rollout tasks (for non-export issues)+- **Issue creator**: Run export tasks (for DATABASE_EXPORT issues)+- **Environment rollout policy roles**: Run tasks based on role matching++### Approval Permissions+- **Approval template roles**: Approve or reject based on current approval step++---++## Special Cases++### Plan Actions Without Issue/Rollout+Plan actions (PLAN_CLOSE, PLAN_REOPEN, ISSUE_CREATE) are only available when:+- No issue is attached to the plan+- No rollout is attached to the plan++**Rationale**: Once an issue or rollout is created, the plan enters a workflow state where plan-level actions are no longer appropriate. Users should interact with the issue/rollout instead.++### Export Data Issues+- Export button is labeled "Export" instead of "Rollout"+- Only the issue creator can start the export (security restriction)+- Export button shows only when approval is APPROVED or SKIPPED (not during review)++### Environment Rollout Policy+When a user lacks `bb.taskRuns.create` permission, the system checks the environment rollout policy:+1. Gets the database's effective environment+2. Checks if a rollout policy exists for that environment+3. If no policy exists: Allow rollout (no restrictions)+4. If policy exists: Check if user has any of the required roles in the policy++This allows fine-grained control over who can rollout tasks in specific environments.++---++## Implementation Files++- **Actions.vue**: Main action logic and visibility rules (frontend/src/components/Plan/components/HeaderSection/Actions/Actions.vue)+- **UnifiedActionGroup.vue**: Action button rendering (frontend/src/components/Plan/components/HeaderSection/Actions/unified/UnifiedActionGroup.vue)+- **taskPermissions.ts**: Rollout permission checks (frontend/src/components/Plan/components/RolloutView/taskPermissions.ts)diff --git a/frontend/src/components/Plan/components/HeaderSection/Actions/Actions.vue b/frontend/src/components/Plan/components/HeaderSection/Actions/Actions.vueindex 202b4a3966..977bafc804 100644--- a/frontend/src/components/Plan/components/HeaderSection/Actions/Actions.vue+++ b/frontend/src/components/Plan/components/HeaderSection/Actions/Actions.vue@@ -163,52 +163,45 @@ const availableActions = computed(() => {return actions;}- // Check if user can close the plan- const canClosePlan =- plan.value.state === State.ACTIVE &&- (currentUserEmail === extractUserId(plan.value.creator || "") ||- hasProjectPermissionV2(project.value, "bb.plans.update"));-- if (canClosePlan) {- actions.push("PLAN_CLOSE");- }-- // Check if user can reopen the plan- const canReopenPlan =- plan.value.state === State.DELETED &&- currentUserEmail === extractUserId(plan.value.creator || "") &&+ const canUpdatePlan =+ currentUserEmail === extractUserId(plan.value.creator || "") ||hasProjectPermissionV2(project.value, "bb.plans.update");- if (canReopenPlan) {- actions.push("PLAN_REOPEN");+ // Check if user can reopen the plan+ if (plan.value.state === State.DELETED) {+ if (canUpdatePlan) {+ actions.push("PLAN_REOPEN");+ }return actions; // For deleted plans, only show reopen action}- const canCreateIssue =- plan.value.state === State.ACTIVE &&- currentUserEmail === extractUserId(plan.value.creator || "") &&- hasProjectPermissionV2(project.value, "bb.issues.create");+ // Check if user can close the plan+ if (canUpdatePlan) {+ actions.push("PLAN_CLOSE");+ }- if (canCreateIssue) {+ // Check if user can create an issue+ if (hasProjectPermissionV2(project.value, "bb.issues.create")) {actions.push("ISSUE_CREATE");}+return actions;}const issueValue = issue?.value;// Should not reach here.if (!issueValue) return actions;+ const issueCreator = extractUserId(issueValue.creator);const isCanceled = issueValue.status === IssueStatus.CANCELED;const isDone = issueValue.status === IssueStatus.DONE;+ const canUpdateIssue = hasProjectPermissionV2(+ project.value,+ "bb.issues.update"+ );// If issue is canceled, check for re-open actionif (isCanceled) {- const issueCreator = extractUserId(issueValue.creator);- const canReopen =- currentUserEmail === issueCreator &&- hasProjectPermissionV2(project.value, "bb.issues.update");-- if (canReopen) {+ if (canUpdateIssue) {actions.push("ISSUE_STATUS_REOPEN");}return actions;@@ -216,26 +209,17 @@ const availableActions = computed(() => {// If issue is done, check for reopen actionif (isDone) {- const issueCreator = extractUserId(issueValue.creator);- const canReopen =- currentUserEmail === issueCreator &&- hasProjectPermissionV2(project.value, "bb.issues.update");-- if (canReopen) {+ if (canUpdateIssue) {actions.push("ISSUE_STATUS_REOPEN");}return actions;}// Check for review actions- const rolloutReady =+ const issueApproved =issueValue.approvalStatus === Issue_ApprovalStatus.APPROVED ||issueValue.approvalStatus === Issue_ApprovalStatus.SKIPPED;- if (- issueValue.approvalStatus !== Issue_ApprovalStatus.CHECKING &&- !rolloutReady- ) {- const issueCreator = extractUserId(issueValue.creator);+ if (!issueApproved) {const { approvers, approvalTemplate } = issueValue;// Check if issue has been rejected@@ -263,10 +247,11 @@ const availableActions = computed(() => {currentRole);if (isUserIncludedInList(currentUserEmail, candidates)) {- if (hasRejection) {- actions.push("ISSUE_REVIEW_APPROVE");- } else {- actions.push("ISSUE_REVIEW_APPROVE", "ISSUE_REVIEW_REJECT");+ actions.push("ISSUE_REVIEW_APPROVE");++ // Only show REJECT if no one has rejected yet.+ if (!hasRejection) {+ actions.push("ISSUE_REVIEW_REJECT");}}}@@ -274,11 +259,6 @@ const availableActions = computed(() => {}}- // Check for resolve and close actions- const canUpdateIssue =- currentUserEmail === extractUserId(issueValue.creator) &&- hasProjectPermissionV2(project.value, "bb.issues.update");-if (canUpdateIssue) {// Check if issue can be resolved (all tasks must be finished)if (rollout.value) {@@ -287,8 +267,7 @@ const availableActions = computed(() => {.every((task) =>[Task_Status.DONE, Task_Status.SKIPPED].includes(task.status));-- if (allTasksFinished && rolloutReady) {+ if (allTasksFinished && issueApproved) {actions.push("ISSUE_STATUS_RESOLVE");}}@@ -296,11 +275,18 @@ const availableActions = computed(() => {actions.push("ISSUE_STATUS_CLOSE");}- // Check for rollout actions when rollout exists and has database creation tasks- if (- rollout.value &&- issueValue.approvalStatus !== Issue_ApprovalStatus.CHECKING- ) {+ // Check for rollout actions when rollout has database creation/export tasks+ // Only allow rollout actions when approval is ready (APPROVED or SKIPPED)+ // For database change tasks, we'll handle in other places+ if (rollout.value && issueApproved) {+ // Check if there are any database creation or export tasks+ const hasDatabaseCreateOrExportTasks = rollout.value.stages.some((stage) =>+ stage.tasks.some(+ (task) =>+ task.type === Task_Type.DATABASE_CREATE ||+ task.type === Task_Type.DATABASE_EXPORT+ )+ );// Different permission checks based on issue type// For export data issues: only the creator can run tasks// For other issues: need bb.taskRuns.create permission@@ -309,43 +295,31 @@ const availableActions = computed(() => {? currentUserEmail === extractUserId(issueValue.creator): hasProjectPermissionV2(project.value, "bb.taskRuns.create");- if (canRunTasks) {- const hasDatabaseCreateOrExportTasks = rollout.value.stages.some(- (stage) =>- stage.tasks.some(- (task) =>- task.type === Task_Type.DATABASE_CREATE ||- task.type === Task_Type.DATABASE_EXPORT- )- );-- if (hasDatabaseCreateOrExportTasks) {- // Show ROLLOUT_START if there are actionable database creation tasks- // This includes both normal rollout and force rollout scenarios- const hasStartableTasks = rollout.value.stages- .flatMap((stage) => stage.tasks)- .some((task) =>- [- Task_Status.NOT_STARTED,- Task_Status.FAILED,- Task_Status.CANCELED,- ].includes(task.status)- );-- if (hasStartableTasks) {- actions.push("ROLLOUT_START");- }+ if (hasDatabaseCreateOrExportTasks && canRunTasks) {+ // Show ROLLOUT_START if there are actionable database creation/export tasks+ // This includes both normal rollout and force rollout scenarios+ const hasStartableTasks = rollout.value.stages+ .flatMap((stage) => stage.tasks)+ .some((task) =>+ [+ Task_Status.NOT_STARTED,+ Task_Status.FAILED,+ Task_Status.CANCELED,+ ].includes(task.status)+ );+ if (hasStartableTasks) {+ actions.push("ROLLOUT_START");+ }- // Check for cancel action on running/pending tasks- const runningTask = rollout.value.stages- .flatMap((stage) => stage.tasks)- .find((task) =>- [Task_Status.PENDING, Task_Status.RUNNING].includes(task.status)- );+ // Check for cancel action on running/pending tasks+ const runningTask = rollout.value.stages+ .flatMap((stage) => stage.tasks)+ .find((task) =>+ [Task_Status.PENDING, Task_Status.RUNNING].includes(task.status)+ );- if (runningTask) {- actions.push("ROLLOUT_CANCEL");- }+ if (runningTask) {+ actions.push("ROLLOUT_CANCEL");}}}@@ -361,12 +335,6 @@ const primaryAction = computed((): ActionConfig | undefined => {// Check if all specs have valid statements (not empty)const hasValidSpecs = !plan.value.specs.some((spec) => isSpecEmpty(spec));- // Check permissions- const hasPermission = hasProjectPermissionV2(- project.value,- "bb.issues.create"- );-// Check plan check status and policy restrictionsconst planChecksFailed =planCheckSummaryStatus.value === PlanCheckRun_Result_Status.ERROR;@@ -378,9 +346,6 @@ const primaryAction = computed((): ActionConfig | undefined => {if (!hasValidSpecs) {errors.push("Missing statement");}- if (!hasPermission) {- errors.push(t("common.missing-required-permission"));- }if (hasRunningChecks) {errors.push("Plan checks are running");}@@ -392,13 +357,10 @@ const primaryAction = computed((): ActionConfig | undefined => {);}- const isDisabled = errors.length > 0;- const description = isDisabled ? errors.join(", ") : undefined;-return {action: "ISSUE_CREATE",- disabled: isDisabled,- description,+ disabled: errors.length > 0,+ description: errors.length > 0 ? errors.join(", ") : undefined,};}@@ -513,29 +475,28 @@ const getIssueTypeFromPlan = (planValue: Plan): Issue_Type => {};const doCreateIssue = async () => {- const issueType = getIssueTypeFromPlan(plan.value);-- const request = create(CreateIssueRequestSchema, {+ const createIssueRequest = create(CreateIssueRequestSchema, {parent: project.value.name,issue: create(IssueSchema, {creator: `users/${currentUser.value.email}`,labels: [], // No labels for direct creationplan: plan.value.name,status: IssueStatus.OPEN,- type: issueType,+ type: getIssueTypeFromPlan(plan.value),rollout: "",}),});- const createdIssue = await issueServiceClientConnect.createIssue(request);-- // Then create the rollout from the plan.- const rolloutRequest = create(CreateRolloutRequestSchema, {+ const createRolloutRequest = create(CreateRolloutRequestSchema, {parent: project.value.name,rollout: {plan: plan.value.name,},});- await rolloutServiceClientConnect.createRollout(rolloutRequest);++ const [createdIssue] = await Promise.all([+ issueServiceClientConnect.createIssue(createIssueRequest),+ rolloutServiceClientConnect.createRollout(createRolloutRequest),+ ]);// Emit status changed to refresh the UIevents.emit("status-changed", { eager: true });diff --git a/frontend/src/components/Plan/components/HeaderSection/Actions/unified/UnifiedActionGroup.vue b/frontend/src/components/Plan/components/HeaderSection/Actions/unified/UnifiedActionGroup.vueindex 3b04f5255a..9dfb0a2285 100644--- a/frontend/src/components/Plan/components/HeaderSection/Actions/unified/UnifiedActionGroup.vue+++ b/frontend/src/components/Plan/components/HeaderSection/Actions/unified/UnifiedActionGroup.vue@@ -46,6 +46,7 @@ import { DropdownItemWithErrorList } from "@/components/IssueV1/components/commoimport { useCurrentUserV1, extractUserId } from "@/store";import { IssueStatus } from "@/types/proto-es/v1/issue_service_pb";import {+ Task_Status,Task_Type,TaskRun_ExportArchiveStatus,TaskRun_Status,@@ -80,16 +81,6 @@ const isExportPlan = computed(() => {});const shouldShowExportDownload = computed(() => {- const exportTasks =- rollout.value?.stages- .flatMap((stage) => stage.tasks)- .filter((task) => {- return task.type === Task_Type.DATABASE_EXPORT;- }) || [];-- // Must have export data tasks- if (exportTasks.length === 0) return false;-// Must have an issueif (!issue?.value) return false;@@ -103,6 +94,25 @@ const shouldShowExportDownload = computed(() => {return false;}+ const exportTasks =+ rollout.value?.stages+ .flatMap((stage) => stage.tasks)+ .filter((task) => {+ return task.type === Task_Type.DATABASE_EXPORT;+ }) || [];++ // Must have export data tasks+ if (exportTasks.length === 0) return false;++ // Check if all export tasks have done or skipped status+ if (+ !exportTasks.every((task) =>+ [Task_Status.DONE, Task_Status.SKIPPED].includes(task.status)+ )+ ) {+ return false;+ }+// Get latest task run for each export taskconst exportTaskRuns = exportTasks.map((task) => {@@ -125,8 +135,8 @@ const shouldShowExportDownload = computed(() => {exportTaskRuns.some((taskRun) =>taskRun.status !== TaskRun_Status.DONE ||- (taskRun.exportArchiveStatus !== TaskRun_ExportArchiveStatus.READY &&- taskRun.exportArchiveStatus !== TaskRun_ExportArchiveStatus.EXPORTED)+ taskRun.exportArchiveStatus ===+ TaskRun_ExportArchiveStatus.EXPORT_ARCHIVE_STATUS_UNSPECIFIED)) {return false;diff --git a/frontend/src/components/Plan/components/RolloutView/StageCard.vue b/frontend/src/components/Plan/components/RolloutView/StageCard.vueindex 3483963b55..6f37f6578a 100644--- a/frontend/src/components/Plan/components/RolloutView/StageCard.vue+++ b/frontend/src/components/Plan/components/RolloutView/StageCard.vue@@ -42,7 +42,7 @@:is-created="isCreated":runable-tasks="runableTasks":can-run-tasks="canRunTasks"- :can-create-rollout="canCreateRollout"+ :can-create-rollout="canRunTasks"@run-tasks="handleRunAllTasks"@create-rollout="createRolloutToStage"/>@@ -163,7 +163,7 @@:is-created="isCreated":runable-tasks="runableTasks":can-run-tasks="canRunTasks"- :can-create-rollout="canCreateRollout"+ :can-create-rollout="canRunTasks"@run-tasks="handleRunAllTasks"@create-rollout="createRolloutToStage"/>@@ -297,10 +297,6 @@ const canRunTasks = computed(() => {return canRolloutTasks(filteredTasks.value);});-const canCreateRollout = computed(() => {- return canRunTasks.value;-});-const stageStatus = computed(() => {// Create a temporary stage object with filtered tasks for status calculationconst stageWithFilteredTasks = {diff --git a/frontend/src/components/Plan/logic/initialize/index.ts b/frontend/src/components/Plan/logic/initialize/index.tsindex 678330cd35..593fdb3dd4 100644--- a/frontend/src/components/Plan/logic/initialize/index.ts+++ b/frontend/src/components/Plan/logic/initialize/index.ts@@ -15,12 +15,7 @@ import type { Plan, PlanCheckRun } from "@/types/proto-es/v1/plan_service_pb";import { GetRolloutRequestSchema } from "@/types/proto-es/v1/rollout_service_pb";import type { Rollout, TaskRun } from "@/types/proto-es/v1/rollout_service_pb";import { emptyPlan } from "@/types/v1/issue/plan";-import {- extractIssueUID,- extractPlanUID,- extractRolloutUID,- issueV1Slug,-} from "@/utils";+import { issueV1Slug } from "@/utils";import { createPlanSkeleton } from "./create";export * from "./create";@@ -200,30 +195,6 @@ export function useInitializePlan(return;}const url = route.fullPath;-- // Check if we're navigating between tabs of the same plan/issue/rollout- // If data is already loaded, skip the refetch entirely to prevent flickering- const currentPlanName = plan.value.name;- const currentPlanUid = extractPlanUID(currentPlanName);-- const isTabNavigation =- currentPlanName &&- (uid === currentPlanUid || // Direct plan tab navigation- (uid.startsWith("issue:") &&- plan.value.issue &&- uid.substring(6) === extractIssueUID(plan.value.issue)) || // Issue tab navigation- (uid.startsWith("rollout:") &&- plan.value.rollout &&- uid.substring(8) === extractRolloutUID(plan.value.rollout))); // Rollout tab navigation-- // If we're just switching tabs within the same plan/issue/rollout, skip refetch- if (isTabNavigation) {- // Mark as not initializing to ensure UI is ready- isInitializing.value = false;- return;- }-- // Otherwise, perform the full fetch with loading stateisInitializing.value = true;try {