Overview
Approval jobs (also known as hold jobs) are a powerful feature in CircleCI that allow you to implement manual gatekeeping in your workflows. This article explains important limitations and considerations when using approval jobs.
Time Limitations for Approval Jobs
While there is no explicit limit on the number of approval jobs you can have in your workflows, there are important time constraints to be aware of:
90-Day Approval Window
Approval/hold jobs have a 90-day limit on when they can be approved
After 90 days, workflows will remain on hold until they reach the 90-day mark, at which point they are automatically canceled
If a job has been on hold for more than 90 days, it cannot be canceled via the API or UI
In these cases, you must contact CircleCI Support to request cancellation of the related workflows
15-Day Workspace Persistence
If the job after an approval job utilizes a persisted workspace, there is a 15-day limit before the workspace expires
While the approval job can still be approved for up to 90 days, the persisted workspace will no longer be available after 15 days
Any subsequent jobs that depend on the workspace will fail if run after this 15-day period
For additional details on these time limits, please refer to our Support article: Time Limit for Approval/Hold Jobs
Workflow Considerations
Job Dependencies and Sequencing
Jobs are run concurrently by default in CircleCI
You must explicitly require any dependencies by their job name if you need jobs to run sequentially
For approval jobs to function properly as gatekeepers, ensure that dependent jobs properly reference the approval job
Performance Impact
Having a large number of approval jobs may not be the most efficient setup for your CI/CD pipeline
Multiple jobs in the approval state could potentially slow down your workflows, especially when manual approval is required for each one
Consider consolidating approval points where logical in your workflow to reduce manual overhead
Best Practices
Strategically place approval jobs at critical points in your workflow rather than between every job
Be mindful of the 15-day workspace expiration when designing workflows with approval jobs and persisted workspaces
Regularly review and clean up workflows with long-standing approval jobs to prevent accumulation of stale workflows
Consider implementing automated notifications for approval jobs to ensure timely reviews
Document your approval process to ensure team members understand when and why to approve jobs
By understanding these limitations and following best practices, you can effectively use approval jobs while maintaining efficient workflows.