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.1workflows:
version: 2
pr_workflow:
jobs:
- hold:
type: approval
context: restricted-context
- build:
requires:
- holdjobs:
build:
docker:
- image: cimg/base:stable
steps:
- checkout
- run: echo "Running build job"Explanation
The
holdjob is a manual approval job usingtype: approval.The
context: restricted-contextis 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
buildrun automatically.
This approach gives teams control over which pipelines proceed, especially useful for jobs involving deployments or sensitive systems.
Summary
Add an
approvaljob to gate execution of later jobs.Apply a
restricted contextto 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.