Skip to content

Gate on CircleCI, GitLab, Buildkite, or Jenkins

The Binclusive/a11y action is a convenience wrapper for GitHub Actions. The gate underneath it is just the b8e binary: it scans, exits non-zero on gating findings, and — when you tell it where — files them to the dashboard. That runs on any CI provider. This guide wires it up outside GitHub Actions.

Every provider reduces to the same three moving parts:

  1. Install b8e — npm i -g @binclusive/cli, or run it with npx @binclusive/cli.
  2. Run the gate — b8e ci --base <merge-target-ref>.
  3. Let the exit code fail the job — do not swallow it. 0 passes, 1 is gating findings, and 2 or higher is a tool failure. See the exit-codes reference.

The credential is BINCLUSIVE_API_KEY, a project CI token minted under Settings → CI access — a personal key will not authenticate ingestion. Add BINCLUSIVE_PROJECT_ID to upload findings to your dashboard.

Point --base at your provider’s merge target

Section titled “Point --base at your provider’s merge target”

--base scopes the gate to the files a change touches. Each provider exposes the base branch under a different variable:

ProviderMerge-target ref
GitLab CIorigin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
CircleCIorigin/main (CircleCI exposes no base-branch var; pin your trunk)
Buildkiteorigin/$BUILDKITE_PULL_REQUEST_BASE_BRANCH
Jenkins (multibranch)origin/$CHANGE_TARGET

Fetch the base branch before you diff against it — a shallow CI clone often has only the feature branch. git fetch origin <branch> first.

Post a sticky comment on the change (the manual PR-ref)

Section titled “Post a sticky comment on the change (the manual PR-ref)”

On GitHub Actions the action reads the pull-request context for free. Off GitHub, b8e has nothing to read, so the sticky comment and the PR-scoped dashboard view stay empty unless you supply the reference yourself. Three variables, together, form it — set all three or none is used:

VariableWhat it is
GITHUB_REPOSITORYowner/repo — the repo slug. There is no provider-neutral alias yet; set this exact name even on GitLab or Buildkite.
BINCLUSIVE_PR_NUMBERthe merge-request / PR number
BINCLUSIVE_COMMIT_SHAthe head commit SHA of the change

Set BINCLUSIVE_BRANCH to the branch the pipeline built as well. An uploaded run records its branch, and the comment counts what is new and what is fixed against the previous run on that branch. A detached checkout with no BINCLUSIVE_BRANCH still gates, but its findings are not uploaded.

On a non-PR pipeline (a trunk build or a schedule) skip the three PR-ref variables and set BINCLUSIVE_ENVIRONMENT to production or staging instead — without it the run is stamped unknown and its findings are attributed to no deployment — listed in the dashboard, but absent whenever anyone narrows to Production. See the environment reference.

a11y-gate:
image: node:20
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- npm i -g @binclusive/cli
- git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- b8e ci --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --summary
variables:
BINCLUSIVE_API_KEY: $BINCLUSIVE_API_KEY
BINCLUSIVE_PROJECT_ID: $BINCLUSIVE_PROJECT_ID
GITHUB_REPOSITORY: $CI_PROJECT_PATH
BINCLUSIVE_PR_NUMBER: $CI_MERGE_REQUEST_IID
BINCLUSIVE_COMMIT_SHA: $CI_COMMIT_SHA
BINCLUSIVE_BRANCH: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

Store the key as a masked, protected CI/CD variable — not in the file.

jobs:
a11y-gate:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run: npm i -g @binclusive/cli
- run: git fetch origin main
- run:
name: Accessibility gate
command: b8e ci --base origin/main --summary
environment:
GITHUB_REPOSITORY: your-org/your-repo
BINCLUSIVE_BRANCH: << pipeline.git.branch >>

Set BINCLUSIVE_API_KEY and BINCLUSIVE_PROJECT_ID as project or context environment variables in the CircleCI UI. CircleCI exposes the PR number as CIRCLE_PR_NUMBER only on forked PRs, so map it into BINCLUSIVE_PR_NUMBER where available and fall back to a trunk-scoped run otherwise.

steps:
- label: ":wheelchair: a11y gate"
command: |
npm i -g @binclusive/cli
git fetch origin "$BUILDKITE_PULL_REQUEST_BASE_BRANCH"
b8e ci --base "origin/$BUILDKITE_PULL_REQUEST_BASE_BRANCH" --summary
env:
GITHUB_REPOSITORY: "${BUILDKITE_ORGANIZATION_SLUG}/${BUILDKITE_PIPELINE_SLUG}"
BINCLUSIVE_PR_NUMBER: "${BUILDKITE_PULL_REQUEST}"
BINCLUSIVE_COMMIT_SHA: "${BUILDKITE_COMMIT}"
BINCLUSIVE_BRANCH: "${BUILDKITE_BRANCH}"

BINCLUSIVE_API_KEY and BINCLUSIVE_PROJECT_ID belong in an agent secret or the cluster’s secret store, never in the pipeline YAML. BUILDKITE_PULL_REQUEST is false on non-PR builds — guard the step or let it run trunk-scoped.

stage('a11y gate') {
environment {
BINCLUSIVE_API_KEY = credentials('binclusive-api-key')
BINCLUSIVE_PROJECT_ID = 'prj_your_project_id'
GITHUB_REPOSITORY = 'your-org/your-repo'
BINCLUSIVE_PR_NUMBER = "${env.CHANGE_ID}"
BINCLUSIVE_COMMIT_SHA = "${env.GIT_COMMIT}"
BINCLUSIVE_BRANCH = "${env.CHANGE_BRANCH ?: env.BRANCH_NAME}"
}
steps {
sh 'npm i -g @binclusive/cli'
sh 'git fetch origin "$CHANGE_TARGET"'
sh 'b8e ci --base "origin/$CHANGE_TARGET" --summary'
}
}

CHANGE_ID and CHANGE_TARGET are populated on multibranch pipelines building a PR; on a plain branch build they are empty, so the step runs trunk-scoped.

--summary writes to GitHub’s step summary and posts the sticky comment; on other providers the step summary is a no-op but the comment still posts once the PR-ref is set. For a native artifact, emit SARIF and hand it to whatever your provider ingests:

Terminal window
b8e ci --base origin/main --format sarif > a11y.sarif

For every flag b8e ci accepts, see the ci reference. To gate only new findings on a codebase with a backlog, adopt a baseline first.