# Test an approval gate before a release

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/test-a-release-approval-gate/)

Check which account can approve a test release and whether that approval lets the next job run in CircleCI, Buildkite, Jenkins or GitLab CI/CD.

## Before you start

- Use a test pipeline and a final job that writes a harmless message or test artifact. Leave production credentials and destinations out of the pipeline.
- Arrange for an allowed approver and a regular account outside the approver group. Ask a pipeline or project administrator to verify the settings.

## Data and access

- **Shared or checked**. The pipeline tool records the approver’s identity and checks the configured gate before running the next job.
- **Check separately**. The job’s artifacts, credentials and publisher are separate. Check what reaches the package or deployment destination.

## Who does what

- **Pipeline administrator**. Configures the gate and keeps access to restore the test settings. Checks which administrator permissions can override the gate.
- **Requester**. Starts a test run for a known revision with a harmless output.
- **Reviewer**. Acts on the gate using an eligible account. The excluded account tests whether the gate or downstream permission actually stops the run.
- **Job or deployment operator**. Checks the downstream result. In GitLab, an eligible operator must start the deployment after required approvals.

## Compare approval rules

- [CircleCI](https://keysigner.io/integrations/guides/test-a-release-approval-gate/#step-1). A new context starts open to organization members. Attach the group-restricted context to the job after the approval. A project member outside the group can approve the hold, but the downstream job should reject access.
- [Buildkite](https://keysigner.io/integrations/guides/test-a-release-approval-gate/#step-2). Pipeline writers can unblock a plain block step. Set allowed_teams to require team membership, even for pipeline writers. If the next job has explicit dependencies, include the block in that list.
- [Jenkins](https://keysigner.io/integrations/guides/test-a-release-approval-gate/#step-3). Set submitter to restrict who can proceed. Administrators can still respond and users with Job/Cancel can abort. To bound the wait, wrap input in a timeout and check that expiry stops the action.
- [GitLab CI](https://keysigner.io/integrations/guides/test-a-release-approval-gate/#step-4). On Premium or Ultimate, set the reviewer group and count on the protected environment. The person who triggers the pipeline cannot approve by default. After all required approvals, an eligible operator must start the job.

## 1. CircleCI

For a GitHub-type organization with security groups, add an approval job and make the test job depend on it. Attach the group-restricted context to the test job. A project member outside the group can click Approve, but the downstream job should show Unauthorized. Use a separate run to check an allowed approver.

**Check.** The downstream job reports Unauthorized after the out-of-group approval. In the separate allowed run, it reaches the test output.

## 2. Buildkite

Add a block step with allowed_teams for the approver when using team permissions. If the test job declares depends_on, include the block step explicitly. Check that someone outside the listed teams cannot unblock it and that the test job runs when the intended team member does.

**Check.** The block remains in place for the out-of-team account. The intended team member unblocks it and the dependent job starts.

## 3. Jenkins

Add a Pipeline input before the test action and set submitter to the intended user or group. Jenkins administrators can respond regardless of this setting, so test with an account that has no administrator access. Users with Job/Cancel can abort the input.

**Check.** The test log stops at the input for the out-of-scope user and reaches the next stage when an allowed submitter responds.

## 4. GitLab CI/CD

On Premium or Ultimate, set approval rules on a protected test environment and point the deployment job at it. Check Allowed to deploy separately from the approvers. Once the required approvals are in, an eligible user must still start the deployment job.

**Check.** The deployment waits for the required approvals. Record the separate start by a user who is allowed to deploy.

## 5. Compare the two runs

Record the pipeline run, revision, approving account, gate result and downstream job result. Check that the test artifact or message appears only on the run that passed the intended controls.

**Check.** Only the allowed run produces the test output. Tie each outcome to the same test action and its exact revision.

## Check your result

Find one run that stopped at the gate or downstream permission check, and one that reached the test output. Keep the provider's status for both runs.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### The gate was approved but the next job did not run

Read the downstream job status and dependencies. Check the context membership in CircleCI, the block dependency in Buildkite, the allowed submitter in Jenkins or who can start the approved deployment in GitLab.

## Tools in this guide

- [CircleCI](https://keysigner.io/integrations/circleci/)
- [Buildkite](https://keysigner.io/integrations/buildkite/)
- [Jenkins](https://keysigner.io/integrations/jenkins/)
  - [Configure a manual pipeline approval](https://www.jenkins.io/doc/pipeline/steps/pipeline-input-step/)
- [GitLab CI](https://keysigner.io/integrations/gitlab-ci/)

## Setup instructions

- [Check CircleCI approvals and restricted contexts](https://circleci.com/docs/guides/security/contexts/)
- [Control who can unblock a Buildkite step](https://buildkite.com/docs/pipelines/configure/step-types/block-step)
- [Set allowed submitters on a Jenkins Pipeline input](https://www.jenkins.io/doc/pipeline/steps/pipeline-input-step/#input-wait-for-interactive-input)
- [Set a time limit on a Jenkins input](https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/#timeout-enforce-time-limit)
- [Set GitLab deployment approvals](https://docs.gitlab.com/ci/environments/deployment_approvals/)
- [Check who can merge the source change](https://keysigner.io/integrations/guides/check-code-merge-approvals/#compare-approval-rules)
- [Walk through a test rollout](https://keysigner.io/integrations/rollout-checklist/)
- [Compare approval history and provider outcomes](https://keysigner.io/integrations/approval-history/)
- [Set up a sign-in code for Buildkite](https://keysigner.io/integrations/guides/set-up-developer-account-sign-in-codes/)
- [Set up a CircleCI sign-in code](https://keysigner.io/integrations/guides/set-up-circleci-and-sailpoint-sign-in-codes/)
- [Test a Jenkins sign-in code](https://keysigner.io/integrations/guides/test-a-jenkins-sign-in-code/)
- [Test a GitLab maintainer sign-in code](https://keysigner.io/integrations/guides/set-up-registry-and-pipeline-sign-in-codes/)

[More guides for this task](https://keysigner.io/integrations/tasks/review-code-and-releases/)
