Skip to content
Crow CI

Approval gates

Crow supports two distinct approval mechanisms:

  1. Pipeline-level approval: gates an entire pipeline before any workflow runs. Configured per repo via Approval requirements.
  2. Workflow-level approval gates: gates a single workflow in the middle of a pipeline. Configured per workflow in .crow.yml.

This page is about the second.

See approval in the workflow syntax reference for the schema.

  1. The pipeline starts and runs all upstream workflows normally.
  2. When a gated workflow’s upstream dependencies all finish successfully, the workflow goes to the blocked state. No agent slot is held while it waits.
  3. An authorized user approves or declines via the UI or CLI. If neither happens, the timeout sweeper declines it automatically after the gate’s configured timeout.
  4. On approve, the gated workflow runs.
  5. On decline (or timeout), the gated workflow is marked declined, all of its downstream workflows are marked skipped, and the pipeline finishes with a top-level declined status.

While a workflow waits at the gate, the overall pipeline status is blocked, not success: the pipeline is not done. After a decline or timeout it rolls up to declined. The status precedence is killed > declined > failure > blocked > running > success, so a single blocked workflow surfaces as a blocked pipeline even when every other workflow has finished.

Canceling a pipeline closes its gates. A workflow that waits at a gate is marked skipped with the rest of the pipeline and can no longer be approved or declined. The same happens when a newer pipeline cancels an older one, as the repository setting that cancels previous pipelines does: approve the gate before the next push to the branch, or approve the gate of the newer pipeline. A pull request pipeline that waits for approval is also canceled once a newer commit, an approval of a newer pipeline or the end of the pull request makes it obsolete: see Superseded approval requests.

Crow gates at the workflow level, not the step level. You cannot put approval: on an individual step: the schema only accepts it at the top level of a workflow. A workflow is all-or-nothing once it starts. The gate comes before a workflow’s steps, never between them.

To gate a single step, split it into its own workflow. Put the free-running steps in one workflow, and put the steps you want behind the gate in a second workflow that depends_on the first and carries the approval block.

.crow/01-ci.yaml runs unguarded:

steps:
  - name: build
    image: golang:1.24
    commands:
      - go build ./...
  - name: test
    image: golang:1.24
    commands:
      - go test ./...
  - name: lint
    image: golang:1.24
    commands:
      - golangci-lint run

.crow/02-deploy.yaml waits for 01-ci and gates the deploy behind approval:

depends_on:
  - 01-ci
approval:
  required: true
  approvers:
    users:
      - alice
  timeout: 24h
steps:
  - name: deploy
    image: deploy-tool:latest
    commands:
      - ./deploy.sh production

For a checkpoint in the middle of a sequence (approve after step A, before step B), split again into more workflows chained with depends_on. Each gate is a per-workflow boundary, so every extra checkpoint is one more workflow.

A workflow that uses a workflow template is approved like every other workflow, at the pipeline level and at a gate.

Crow resolves templates when the pipeline is created, before it waits for approval. The Config tab of the waiting pipeline therefore shows the approver the template that was pinned, with its repository, ref and commit, and the workflow expanded from it. Approving runs that template: the stored copy is used, and the forge is not asked again. The expanded workflow is built again at approval and can differ from the one shown where a value changed in the meantime, such as ${CI_PREV_PIPELINE_STATUS} or a mapped secret.

If a pinned template is no longer shared with the repository, the approval is refused and the pipeline or the workflow stays blocked. It can be approved once the template is shared again.

A template can set approval itself. Only one side can: an approval in the workflow file and in its template is an error.

A pipeline that waits for approval waits as a whole, with the required workflows its organization assigned to the repository. Their status on the forge is pending until the pipeline is approved, and a failure once it is declined. Approving runs them at the revisions that were recorded when the pipeline was created.

Open the pipeline view. Gated workflows show an “Approval required” panel with Approve and Decline buttons. Add an optional reason for the audit trail.

The navbar pending-approvals indicator also surfaces workflow gates you can approve, across all your repos.

crow pipeline workflow approve <repo> <pipeline-number> <workflow-name> [--reason "..."]
crow pipeline workflow decline <repo> <pipeline-number> <workflow-name> [--reason "..."]

See pipeline workflow in the CLI reference.

Three environment variables control gate behaviour:

  • CROW_APPROVAL_GATE_TIMEOUT_DEFAULT (default 24h): applied when YAML omits timeout.
  • CROW_APPROVAL_GATE_TIMEOUT_MAX (default 168h, 7d): hard cap. YAML with a longer timeout fails lint.
  • CROW_APPROVAL_GATE_SWEEP_INTERVAL (default 30s, minimum 5s): how often the timeout sweeper runs.

See Approval gates in the server configuration reference for details.

Pipeline-level Workflow-level
Configured in Repo settings .crow.yml per workflow
Triggered by Forge events (for example, PR from fork) approval.required: true
Approvers Anyone with push perm Configurable list + push perm fallback
Granularity Entire pipeline before anything runs Single workflow mid-pipeline