Skip to main content
Mapagam

Implementing Approval Jobs

1. Creating Manual Approval Jobs

Property Description Example
approval Defines a manual approval job in the workflow approval: true
type Must be manual for approval jobs type: manual
requires Job(s) that must complete before approval job runs requires: [build]

Example: Approval Job Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
  approve-deploy:
    type: manual
    requires:
      - build
    steps:
      - run: echo "Deploying to production"
workflows:
  deploy:
    jobs:
      - build
      - approve-deploy
Note: Approval jobs must be explicitly approved in the CircleCI UI before they proceed.

2. Sequencing with Approval

Property Description Values Notes
approval Approval job configuration true Enables approval workflow for job
requires Jobs that must complete before approval job runs job-name Can specify multiple jobs with array
context Context to use for approval job context-name Optional, defaults to project context

Example: Approval Job Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run: npm test

  approve-deploy:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run: npm run deploy
    approval: true
    requires:
      - build

workflows:
  version: 2
  deploy:
    jobs:
      - build
      - approve-deploy:
          requires:
            - build
Note: Approval jobs are useful for manual gatekeeping in deployment workflows.
Warning: Approval jobs block the workflow until manually approved in CircleCI UI.

3. Approving via Dashboard

CircleCI allows you to approve or reject jobs directly from the web dashboard. This is particularly useful for workflows that require manual approval before deployment or other critical actions.

Step Description Action
1 Navigate to the CircleCI project dashboard. Visit your project's page in the CircleCI web interface.
2 Locate the workflow with approval jobs. Find the workflow that includes a job requiring manual approval.
3 Click on the approval job. Select the job that requires approval to view its details.
4 Review job details. Check logs, artifacts, and any relevant information before approving or rejecting.
5 Approve or reject the job. Click the "Approve" or "Reject" button as appropriate.
Note: Approval jobs are typically used in deployment workflows where a human needs to confirm that the build is ready for production.

Example: Approval Job Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
  deploy:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm run deploy
workflows:
  version: 2
  deploy-workflow:
    jobs:
      - build
      - deploy:
          requires:
            - build
          context: deployment-context

4. Approving via API

CircleCI allows you to approve workflows programmatically using the CircleCI API. This is useful for automating approval processes or integrating with external systems.

Endpoint Method Description
/approval-request POST Approve or reject a workflow approval request

Example: Approving a Workflow via API

curl -X POST https://circleci.com/api/v2/workflow/<workflow-id>/approve \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Circle-Token: <your-api-token>' \
  -d '{ "status": "approved" }'
Note: You must have the appropriate permissions to approve workflows in CircleCI.
Warning: Ensure that your API token has the necessary scope to approve workflows.

5. Using Approval for Deployments

Approval jobs in CircleCI allow you to require manual approval before deploying to production or other sensitive environments. This ensures that deployments are intentional and reviewed by the appropriate team members.

Field Description Example
approval Indicates that the job requires manual approval before running. true
requires Specifies which jobs must complete successfully before this job can run. [build, test]

Example: Approval Job Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
  test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm test
  deploy:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm run deploy
    approval: true
    requires:
      - build
      - test

workflows:
  version: 2
  deploy_workflow:
    jobs:
      - build
      - test
      - deploy
Note: Approval jobs are particularly useful in CI/CD pipelines where you want to enforce a manual check before deploying to production or other sensitive environments.

6. Restricting Approval Permissions

Permission Type Description Configuration Notes
approval.job Specifies the job that requires approval 'build-and-deploy' Must match a job name in the config
approvals List of users or teams who can approve [{user: 'john.doe'}, {team: 'dev-team'}] Supports user and team-based approvals
required Whether approval is mandatory true Defaults to false if not specified

Example: Restricting Approval Permissions

jobs:
  build-and-deploy:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test

  deploy:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm run build
      - run: npm run deploy

workflows:
  version: 2
  deploy-workflow:
    jobs:
      - build-and-deploy
      - deploy:
          requires:
            - build-and-deploy
          approval:
            job: deploy
            approvals:
              - user: john.doe
              - team: dev-team
Note: Approval jobs can only be used in workflows with a version of 2 or higher.
Warning: If no approvals are specified, any member of the project can approve.

7. Implementing Multi-Stage Approvals

Example: Configuring Multi-Stage Approval Workflow

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test

  approval-job-1:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: echo "First approval stage"
      - hold:
          type: approval
          approval-job-name: approval-job-1

  approval-job-2:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: echo "Second approval stage"
      - hold:
          type: approval
          approval-job-name: approval-job-2

workflows:
  version: 2
  multi-stage-approval:
    jobs:
      - build
      - approval-job-1:
          requires:
            - build
      - approval-job-2:
          requires:
            - approval-job-1
Property Description Values Notes
hold Pauses workflow execution until approval { type: approval, approval-job-name: <job-name> } Used to implement manual approval steps
approval-job-name Name of the job that requires approval String Must match a defined job name in the config
Note: Approval jobs can be used to enforce manual checks in CI/CD pipelines before proceeding to next stages.

8. Setting Up Approval Notifications

Notification Type Configuration Notes
email email Sends notification to configured email addresses
slack slack Sends notification to Slack channel or user
webhook webhook Sends notification to a custom URL endpoint

Example: Slack Notification Configuration

approval:
  slack:
    channel: "#ci-notifications"
    message: "Approval required for build {{build_num}} on {{branch}}"

Example: Email Notification Configuration

approval:
  email:
    recipients:
      - "dev-team@example.com"
      - "ops@example.com"
Note: Approval notifications can be customized with templates to include build details, branch names, and user information.

9. Handling Approval Timeouts

Property Values Description
approval_timeout 30m Timeout duration for approval jobs. Default is 30 minutes.
timeout_unit minutes Time unit for approval timeout. Options: seconds, minutes, hours.

Example: Setting Approval Timeout

jobs:
  approve-deploy:
    type: approval
    timeout: 45
    timeout_unit: minutes

workflows:
  deploy-workflow:
    jobs:
      - approve-deploy
Note: If an approval job does not receive a response within the specified timeout, it will be marked as failed.

10. Canceling Waiting Approvals

When an approval job is waiting for manual approval, you can cancel the job before it is approved or rejected. Canceling an approval job stops the workflow and prevents any further steps from running.

Method Description Notes
Cancel Approval Job Cancel a waiting approval job via the CircleCI UI or API. Useful for stopping workflows that are no longer needed or when changes are made to the job configuration.

Example: Canceling Approval Job via API

curl -X POST https://circleci.com/api/v2/workflow/<workflow-id>/cancel \
  -H "Accept: application/json" \
  -H "Circle-Token: <your-api-token>"
Note: Approval jobs can only be canceled if they are in a "waiting" state. Once approved or rejected, the job cannot be canceled.

Was this article helpful?

Related Cheat Sheets