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

1. Strategically place approval jobs at critical points in your workflow rather than between every job
2. Be mindful of the 15-day workspace expiration when designing workflows with approval jobs and persisted workspaces
3. Regularly review and clean up workflows with long-standing approval jobs to prevent accumulation of stale workflows
4. Consider implementing automated notifications for approval jobs to ensure timely reviews
5. 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.

Additional Resources

• Who Canceled my Approval Job?
• Time-Limit for Approval/Hold Job
• "You don't have permission to approve this job"