How to Trigger CircleCI Pipelines Selectively Using an Approval Job

Overview

It's useful to trigger a pipeline when a pull request (PR) is opened, but not all jobs need to run immediately. For example, you may want a manual approval step before continuing to deployment or expensive testing.

This guide shows how to add an approval job at the start of a workflow that must be approved before any other jobs proceed. GitHub OAuth connected organisations can additionally restrict who can approve it by using restricted contexts.

Example

Here’s a basic setup in .circleci/config.yml:

version: 2.1

workflows:
  version: 2
  pr_workflow:
    jobs:
      - hold:
          type: approval
          context: restricted-context
      - build:
          requires:
            - hold

jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: echo "Running build job"

Explanation

• The hold job is a manual approval job using type: approval.
• The context: restricted-context is applied to the approval job to control who can approve it, based on GitHub security group membership.
• The context does not require any environment variables. It is used purely to enforce access control.
• After approval, downstream jobs such as build run automatically.

This approach gives teams control over which pipelines proceed, especially useful for jobs involving deployments or sensitive systems.

Summary

• Add an approval job to gate execution of later jobs.
• Apply a restricted context to limit who can approve.
• Note: the context can be empty—no environment variables are required.

This method helps you reduce compute costs, enforce review policies, and protect sensitive pipeline steps.

Related Information

• CircleCI: Approval Jobs
• CircleCI: Restricted Contexts
• GitHub OAuth Integration for CircleCI

Back to Top