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.
The shape of a gate step, anywhere
Section titled “The shape of a gate step, anywhere”Every provider reduces to the same three moving parts:
- Install
b8e—npm i -g @binclusive/cli, or run it withnpx @binclusive/cli. - Run the gate —
b8e ci --base <merge-target-ref>. - Let the exit code fail the job — do not swallow it.
0passes,1is gating findings, and2or 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:
| Provider | Merge-target ref |
|---|---|
| GitLab CI | origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME |
| CircleCI | origin/main (CircleCI exposes no base-branch var; pin your trunk) |
| Buildkite | origin/$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:
| Variable | What it is |
|---|---|
GITHUB_REPOSITORY | owner/repo — the repo slug. There is no provider-neutral alias yet; set this exact name even on GitLab or Buildkite. |
BINCLUSIVE_PR_NUMBER | the merge-request / PR number |
BINCLUSIVE_COMMIT_SHA | the 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.
GitLab CI
Section titled “GitLab CI”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_NAMEStore the key as a masked, protected CI/CD variable — not in the file.
CircleCI
Section titled “CircleCI”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.
Buildkite
Section titled “Buildkite”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.
Jenkins (declarative pipeline)
Section titled “Jenkins (declarative pipeline)”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.
Emit results a provider can render
Section titled “Emit results a provider can render”--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:
b8e ci --base origin/main --format sarif > a11y.sarifFor every flag b8e ci accepts, see the ci reference. To gate only
new findings on a codebase with a backlog, adopt a baseline first.