Use Iris Code in CI Pipelines: GitHub Actions, GitLab, and Shell

Install the CLI, pass your licence as an environment variable, and run iris gate as your quality gate step. There is no browser step, no interactive login, and nothing persisted on the runner. Analysis runs on your own infrastructure, so your code never leaves it.

Exit codes

Use exit codes to control pipeline behaviour. iris gate follows the same conventions as all other Iris Code commands:

Exit code	Meaning	Pipeline action
`0`	All gate rules pass	Pipeline continues
`1`	One or more gate rules failed: the `minHealthScore` threshold or any configured `gateMax*` limit (`gateMaxSecrets`, `gateMaxComplexity`, `gateMaxFileLength`, `gateMaxSmellsPerFile`, `gateMaxSecuritySmells`)	Fail the build
`2`	Bad arguments or invalid config	Fix the workflow step

Setting IRIS_LICENCE_TOKEN

Add your licence key as a secret in your CI provider settings, then expose it as the IRIS_LICENCE_TOKEN environment variable in the step that runs Iris Code. The CLI checks this variable before reading the credentials file, so no iris auth login step is needed on runners.

iris secrets and iris security both run without any authentication at all. Use them for a free CI scan that requires no licence - they work on any runner regardless of IRIS_LICENCE_TOKEN.

GitHub Actions

The example below shows a minimal iris gate step. For the full workflow including branch protection rules and threshold configuration, see the GitHub Actions guide.

name: Iris Code health check
on: [push, pull_request]

jobs:
  iris:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 20
      - run: npm install -g @iris-code/cli
      - name: Gate check
        run: iris gate
        env:
          IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}

For inline PR annotations, use iris gate . --format github (added in v1.6.0). See the full guide at /enforcement/github-actions.

To add free secrets and security smell scans that need no licence, include these steps independently:

      - name: Secrets scan (free, no licence)
        run: |
          npm install -g @iris-code/cli
          iris secrets

      - name: Security smell scan (free, no licence)
        run: |
          npm install -g @iris-code/cli
          iris security

Gating on dependency CVEs

Use iris cve (Pro) as a separate dependency gate. It runs the same scan as iris deps but exits 1 only when an advisory at or above the chosen severity is found, so low-severity noise never turns the pipeline red:

      - name: CVE gate
        run: iris cve --severity high
        env:
          IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}

See the command reference for severity levels and exit codes.

Telling the team in Slack

A pipeline that only writes to the build log gets read by whoever opened the build log. Set IRIS_SLACK_WEBHOOK as a protected CI secret and the outcome lands in a channel instead:

      - name: Iris Code gate
        run: iris gate . --format github
        env:
          IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}
          IRIS_SLACK_WEBHOOK: ${{ secrets.IRIS_SLACK_WEBHOOK }}

The message is built and sent by your own runner and never passes through Iris servers, so it can name the failing files. It stays quiet on a passing run unless you add --slack-on always, and a Slack outage can never change the exit code. See Slack notifications for the full setup.

GitLab CI

iris-gate:
  stage: test
  image: node:20
  script:
    - npm install -g @iris-code/cli
    - iris gate
  variables:
    IRIS_LICENCE_TOKEN: $IRIS_LICENCE_TOKEN

Generic shell

For any CI environment that runs arbitrary shell scripts:

#!/bin/sh
set -e
npm install -g @iris-code/cli
iris gate

iris gate has no threshold flag - set minHealthScore (and any gateMax* limits) in .irisconfig.json instead. See .irisconfig.json for the full reference.

Pair iris gate (Pro) with iris secrets (free) for layered coverage - gate blocks low-quality code, secrets scan catches leaked credentials on every push regardless of licence status.

Start here

What Iris Code finds

Blocking bad code

Configuration

Editors

Reference

Use Iris Code in CI Pipelines: GitHub Actions, GitLab, and Shell

Exit codes

Setting IRIS_LICENCE_TOKEN

GitHub Actions

Gating on dependency CVEs

Telling the team in Slack

GitLab CI

Generic shell

​Exit codes

​Setting IRIS_LICENCE_TOKEN

​GitHub Actions

​Gating on dependency CVEs

​Telling the team in Slack

​GitLab CI

​Generic shell

Exit codes

Setting IRIS_LICENCE_TOKEN

GitHub Actions

Gating on dependency CVEs

Telling the team in Slack

GitLab CI

Generic shell