# Release gate in CI

> Call the AI CodeOps release gate from GitHub Actions, GitLab CI, Bitbucket Pipelines, Forgejo or Gitea, fail the job on a deny, and make it a required check.

Source: https://aicodeops.dev/docs/release-gate-ci

The release gate answers one question for your pipeline: may this pull request ship? Your CI sends the pull request URL to `POST /api/release/check` with a workspace API key. AI CodeOps looks at every session that touched the change and answers `allowed: true` or `allowed: false`, with reasons such as failing tests, an open high or critical finding, a review that didn't finish, or a repository build that didn't pass. It also denies a session that changed code and has no test result with counts, unless the project has **Don't run tests for this project** turned on. These are the same rules as the [quality gates](https://aicodeops.dev/docs/quality-gates) in the console.

AI CodeOps opens its pull requests from branches named `codeops/run-<id>`. The gate denies a change that no AI CodeOps session touched, so the jobs below only ask about those branches. Your other checks still run on every pull request.

## Create an API key

1. In the console, open **Configure → API Keys** and create a key. The secret starts with `sk-` and is shown once.
2. Store it in your CI system's secret store under the name `AICODEOPS_API_KEY`. Don't put it in the repository.

| CI system                 | Where the secret goes                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------- |
| GitHub Actions            | The repository's **Settings → Secrets and variables → Actions**, as a repository secret |
| GitLab CI                 | **Settings → CI/CD → Variables**, masked                                                |
| Bitbucket Pipelines       | **Repository settings → Repository variables**, with **Secured** ticked                 |
| Forgejo and Gitea Actions | The repository's **Settings → Actions → Secrets**                                       |

On GitLab, leave **Protect variable** off unless your `codeops/*` branches are protected. A protected variable is only given to pipelines on protected branches, so the job would get an empty key.

The key acts as the member who created it and needs the `workspace:read` permission. Where your plan includes key scoping, an admin can limit the key to the release gate check. More on keys is under [Workspace API keys](https://aicodeops.dev/docs/api#workspace-api-keys).

The jobs below call `https://console.aicodeops.dev`. Use the host you open the console on. The **Release gate** page in the console, under **Review & Gate**, shows the GitHub Actions and GitLab CI jobs with your address filled in and a **Copy** button.

## Add the job

Each job sends the pull request URL, prints the summary and the reasons, and fails unless the answer is `allowed: true`. The endpoint answers `200` for a deny too, so the job reads the field, not the status code. `curl --fail` turns a bad key, a rate limit or an outage into a failed job.

### GitHub Actions

Save this as `.github/workflows/aicodeops-release-gate.yml`:

```yaml
name: AI CodeOps release gate
on:
  pull_request:

permissions:
  contents: read

jobs:
  release-gate:
    name: AI CodeOps release gate
    # AI CodeOps opens its pull requests from codeops/run-<id> branches.
    if: startsWith(github.head_ref, 'codeops/run-')
    runs-on: ubuntu-latest
    steps:
      - name: Ask the release gate
        env:
          AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
          AICODEOPS_URL: https://console.aicodeops.dev
          PR_URL: ${{ github.event.pull_request.html_url }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          body=$(jq -n --arg pr "$PR_URL" --arg sha "$HEAD_SHA" '{pullRequestURL: $pr, commitSHA: $sha}')
          response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
            -H "Authorization: Bearer $AICODEOPS_API_KEY" \
            -H "Content-Type: application/json" \
            -d "$body") || { echo "::error::Release check unavailable: failing closed"; exit 1; }
          echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
          if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
            echo "::error::AI CodeOps release gate denied this change"
            exit 1
          fi
```

It sends the pull request URL and its head commit. A session matches on either one.

### GitLab CI

Add this job to `.gitlab-ci.yml`:

```yaml
aicodeops-release-gate:
  image: alpine:3.20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    AICODEOPS_URL: https://console.aicodeops.dev
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      case "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" in
        codeops/run-*) ;;
        *) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
      esac
      body=$(jq -n --arg pr "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID" '{pullRequestURL: $pr}')
      response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
        -H "Authorization: Bearer $AICODEOPS_API_KEY" \
        -H "Content-Type: application/json" \
        -d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
      echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
      if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
        echo "AI CodeOps release gate denied this change"
        exit 1
      fi
```

The job runs in merge request pipelines. On a branch AI CodeOps didn't open it passes without asking, so the pipeline still reports a result.

### Bitbucket Pipelines

Add this to `bitbucket-pipelines.yml`. The `codeops/**` pattern limits the step to pull requests from AI CodeOps branches:

```yaml
pipelines:
  pull-requests:
    "codeops/**":
      - step:
          name: AI CodeOps release gate
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq
            - |
              AICODEOPS_URL="https://console.aicodeops.dev"
              body=$(jq -n --arg pr "https://bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pull-requests/$BITBUCKET_PR_ID" '{pullRequestURL: $pr}')
              response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
                -H "Authorization: Bearer $AICODEOPS_API_KEY" \
                -H "Content-Type: application/json" \
                -d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
              echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
              if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
                echo "AI CodeOps release gate denied this change"
                exit 1
              fi
```

### Forgejo and Gitea Actions

Save this as `.forgejo/workflows/aicodeops-release-gate.yml` on Forgejo, or `.gitea/workflows/aicodeops-release-gate.yml` on Gitea. Set `runs-on` to a label one of your runners has:

```yaml
name: AI CodeOps release gate
on:
  pull_request:
jobs:
  release-gate:
    runs-on: docker
    steps:
      - name: Ask the release gate
        env:
          AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
          AICODEOPS_URL: https://console.aicodeops.dev
          PR_URL: ${{ github.server_url }}/${{ github.repository }}/pulls/${{ github.event.number }}
          BRANCH: ${{ github.head_ref }}
        run: |
          set -eu
          case "$BRANCH" in
            codeops/run-*) ;;
            *) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
          esac
          response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
            -H "Authorization: Bearer $AICODEOPS_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"pullRequestURL\":\"$PR_URL\"}") || { echo "Release check unavailable: failing closed"; exit 1; }
          echo "$response"
          printf '%s' "$response" | grep -Eq '"allowed"[[:space:]]*:[[:space:]]*true' || { echo "AI CodeOps release gate denied this change"; exit 1; }
```

This one uses `grep` in place of `jq`, so the runner needs only `curl`. The pattern allows spaces around the colon, so it reads the answer the same way however it is formatted. It prints the whole answer, reasons included.

### If the job fails on a change that should pass

- **"No workflow runs found for …"**: the URL the job sent isn't the one AI CodeOps stored when it opened the pull request. Compare the URL in the job log with the pull request link on the change in the console. A trailing slash is ignored.
- **The job fails before it prints a summary**: the key is missing or wrong, or the workspace made more than 60 checks in a minute. Check the secret's name, and that the key hasn't been deleted.

## Make it a required check

A failing job doesn't stop a merge by itself. Require it on your Git host:

- **GitHub.** In branch protection or a ruleset for your default branch, turn on **Require status checks to pass before merging** and add **AI CodeOps release gate**. A check shows in the list after it has run once. On pull requests from other branches the job is skipped, and GitHub counts a skipped job as passed.
- **GitLab.** Under **Settings → Merge requests → Merge checks**, turn on **Pipelines must succeed**. Leave **Skipped pipelines are considered successful** off.
- **Bitbucket.** Under **Repository settings → Branch restrictions**, add the merge check for a minimum number of successful builds with no failed builds. Blocking a merge on unresolved merge checks needs the Premium plan. On Standard the check warns and people can still merge.
- **Forgejo and Gitea.** In the branch protection rule for your default branch, turn on **Enable status check** and add the job to **Status check patterns**. Run the job once first so its name shows up.

Then restrict who can push to `codeops/*` branches, or have approvals reset when a branch changes. The gate answers about the session's change, not about a commit someone adds to the branch afterwards.

## Options worth knowing

Add fields to the JSON body to ask for more. In the jobs above that is the `jq -n` line:

```bash
body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
```

| Option                | Default | What it does                                                                                                                    |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `blockingSeverity`    | `high`  | The lowest severity of open finding that denies: `critical`, `high`, `medium`, `low` or `info`                                  |
| `minCoveragePct`      | not set | A coverage floor from 0 to 100. The most recent test run that reported coverage must meet it                                    |
| `blockOnInFlight`     | `false` | Deny while a session or a repository build for the change is still running                                                      |
| `blockOnBuildFailure` | `true`  | A repository build of the commit or pull request that failed, timed out or was canceled denies. Set `false` to leave builds out |

**The coverage floor fails closed.** If you set `minCoveragePct` and no test run on the change reported coverage, the gate denies: "Coverage wasn't reported, so the 80% floor can't be checked". A floor it can't check doesn't pass. Set it once your project's test command prints a coverage summary, for example `pytest --cov` or `vitest run --coverage`, and the session's run page shows a coverage figure.

**Waiting for a running session.** Without `blockOnInFlight`, a change with one finished session can pass while another is still running. With it, the gate denies until every session and build for the change has finished. A job that should wait can repeat the call with a pause while a reason says something is still running, and give up after its own time limit. Stay under 60 checks a minute for the workspace.

Required workflows, disallowed licenses, a required earlier deployment and the other fields are on the [API page](https://aicodeops.dev/docs/api), with every response field in the [release check reference](https://aicodeops.dev/docs/api/release-check).

## Next steps

- [Quality gates](https://aicodeops.dev/docs/quality-gates)
- [API](https://aicodeops.dev/docs/api)
- [Approvals and policies](https://aicodeops.dev/docs/approvals-and-policies)
- [Gated deploys](https://aicodeops.dev/docs/gated-deploys)

## Frequently asked questions

### Why do the jobs only ask about codeops/ branches?

The gate judges AI CodeOps sessions and denies a change that has none. A pull request a person opened by hand has no session behind it, so asking about it would always fail.

### Does a denied change come back as an error status?

No. The endpoint answers 200 for allow and for deny. The job reads the allowed field and fails unless it is true.

### What happens if the gate can't be reached?

The job fails. Each job on this page treats a network error, a bad key or a rate limit as a failure, so a check that didn't run never passes a change.
