How to Run aislop in GitHub Actions, GitLab CI, and Bitbucket

The safest way to add a code-quality gate is to make four decisions explicitly: what code is scanned, which CLI version runs, what score or findings fail the job, and how legacy debt is handled.

The examples below pin the action commits, container digest, and aislop 0.13.1 CLI available when this article was updated. Review the repository documentation and the referenced release notes before upgrading. A dependency bot can propose reviewed pin updates without making CI behavior drift between repository changes.

Option A: full-repository gate in GitHub Actions

name: aislop

on:
pull_request:
push:
  branches: [main]

jobs:
quality-gate:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
      with:
        node-version: 24
    - run: npx --yes aislop@0.13.1 ci

This is self-contained and reproducible. The comments record the human-readable major versions, while the full commit SHAs are the values the runner executes. The direct CLI form also keeps the complete action dependency chain visible in this workflow.

Option B: changed-file gate

A changed-file gate avoids making every contributor pay for historical debt. It needs the base branch and enough Git history to calculate the diff:

jobs:
changed-code-quality:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
      with:
        fetch-depth: 0
    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
      with:
        node-version: 24
    - run: npx --yes aislop@0.13.1 ci --changes --base origin/main

If your default branch is not main, change the base. In forks or unusual checkout configurations, explicitly fetch the target branch before the scan.

GitLab CI

aislop:
image: node:24@sha256:5711a0d445a1af54af9589066c646df387d1831a608226f4cd694fc59e745059
variables:
  GIT_DEPTH: "0"
script:
  - npx --yes aislop@0.13.1 ci --changes --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"

For branch pipelines without merge-request variables, run the full-repository ci command or supply a stable base branch.

Bitbucket Pipelines

clone:
depth: full

pipelines:
pull-requests:
  '**':
    - step:
        name: aislop quality gate
        image: node:24@sha256:5711a0d445a1af54af9589066c646df387d1831a608226f4cd694fc59e745059
        script:
          - git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
          - npx --yes aislop@0.13.1 ci --changes --base FETCH_HEAD

The explicit fetch puts the destination branch at FETCH_HEAD so the diff has a reliable base.

Set the threshold from evidence

Run npx --yes aislop@0.13.1 scan on the default branch and inspect the findings. Configure the CI floor at a level the repository currently meets, then raise it as high-confidence issues are removed.

ci:
failBelow: 70

There is no universal “good” score across languages and configurations. The useful signal is whether the same repository improves and whether the gate prevents regressions without creating suppression work.

Troubleshooting

• Unknown revision or empty diff: fetch the base branch and use full history.
• Local and CI results differ: compare CLI versions, Node versions, configuration inheritance, ignored paths, and generated files.
• Too many legacy findings: use changed-file mode or start with a lower floor; do not blanket-disable the job.
• Noisy rule: inspect examples, tune or suppress it narrowly, and record why. A reproducible false positive is still a false positive.
• Flaky updates: pin the CLI version and upgrade it through reviewed dependency changes.

Make the job required after the pilot

Observe several representative pull requests, confirm the findings are useful, and then add the job to the repository's required checks. Keep tests, security analysis, and human review alongside it. A quality gate should remove repetitive work from reviewers, not become a substitute for understanding the change.