> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iriscode.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Run iris gate as a CI enforcement step in GitHub Actions, GitLab CI, or any shell pipeline. Pass your licence via IRIS_LICENCE_TOKEN and fail builds that miss the threshold.

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.

<Note>
  `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`.
</Note>

## 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](/enforcement/github-actions) guide.

```yaml theme={null}
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 }}
```

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

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

```yaml theme={null}
      - 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:

```yaml theme={null}
      - name: CVE gate
        run: iris cve --severity high
        env:
          IRIS_LICENCE_TOKEN: ${{ secrets.IRIS_LICENCE_TOKEN }}
```

See the [command reference](/cli/commands#iris-cve) 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:

```yaml theme={null}
      - 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](/enforcement/slack-notifications) for the full setup.

## GitLab CI

```yaml theme={null}
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:

```bash theme={null}
#!/bin/sh
set -e
npm install -g @iris-code/cli
iris gate
```

<Note>
  `iris gate` has no threshold flag - set `minHealthScore` (and any `gateMax*` limits) in `.irisconfig.json` instead. See [.irisconfig.json](/configuration/irisconfig) for the full reference.
</Note>

<Tip>
  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.
</Tip>