AI CodeOps

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.

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 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 systemWhere the secret goes
GitHub ActionsThe repository's Settings → Secrets and variables → Actions, as a repository secret
GitLab CISettings → CI/CD → Variables, masked
Bitbucket PipelinesRepository settings → Repository variables, with Secured ticked
Forgejo and Gitea ActionsThe 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.

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:

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:

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:

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:

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:

body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
OptionDefaultWhat it does
blockingSeverityhighThe lowest severity of open finding that denies: critical, high, medium, low or info
minCoveragePctnot setA coverage floor from 0 to 100. The most recent test run that reported coverage must meet it
blockOnInFlightfalseDeny while a session or a repository build for the change is still running
blockOnBuildFailuretrueA 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, with every response field in the release check reference.

Next steps

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.

Was this page helpful?