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

# Use Scan in CI

> Generate an SBOM and enforce license policy in GitHub Actions with a pinned githits-scan version and a secret token.

Generate an SBOM in CI, then check its licenses against your policy. The workflow below checks the saved document, so license enforcement needs no second upload.

Scan is **Alpha**. Pin a released version and review migration notes before upgrading.

## Prepare your repository

Before adding the workflow:

1. [Review what Scan uploads](https://docs.githits.com/scan/overview.md#review-what-you-upload). Upload commands send the full contents of selected package files without redacting them.
2. [Save a reviewed inventory](https://docs.githits.com/scan/configuration.md#save-a-reviewed-inventory) in `githits-scan.toml` and commit it.
3. Enable a reviewed [`[licenses]` policy](https://docs.githits.com/scan/configuration#license-policy) in that configuration.
4. Store an API token as the repository secret `GITHITS_API_TOKEN`.

## GitHub Actions

Save this workflow as `.github/workflows/dependencies.yml`. It runs on pushes and manual dispatch, and installs version 0.3.0 from crates.io.

```yaml theme={null}
name: Dependency checks
on: [push, workflow_dispatch]
permissions:
  contents: read
jobs:
  sbom:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
        with:
          toolchain: 1.99.1
      - name: Install githits-scan
        run: cargo install githits-scan --version 0.3.0 --locked
      - name: Generate the SBOM (fails on inventory drift)
        env:
          GITHITS_API_TOKEN: ${{ secrets.GITHITS_API_TOKEN }}
        run: githits-scan sbom generate --output bom.cdx.json
      - name: Enforce the license policy on the same document
        run: githits-scan license check --sbom bom.cdx.json
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: sbom
          path: bom.cdx.json
          if-no-files-found: error
```

The generation step checks for [inventory drift](https://docs.githits.com/scan/configuration.md#inventory-drift) before uploading. The license step reads `bom.cdx.json` offline and needs no token. GitHub Actions uploads the SBOM artifact after both steps succeed.

Review reports before sharing them. They can contain private package names and paths.

## Add a dependency audit

Run `githits-scan audit` in a separate step with `GITHITS_API_TOKEN` supplied from the same secret. An audit checks vulnerabilities, deprecated releases, outdated and duplicate versions, and manifest/lockfile disagreements. Any finding or incomplete check returns exit 1.

The audit submits another analysis job. It does not read the SBOM generated above.

## Interpret failures

| Exit | What to do |
| - | - |
| 0 | Continue. A license report is informational; use `license check` for enforcement. |
| 1 | Review findings, incomplete audit checks, inventory drift, license violations, unresolved projects, or an empty selection. |
| 2 | Fix the invocation, configuration, input, upload limits, token, or account access described in stderr. |
| 3 | Investigate the network, I/O, rate limit, service, or protocol failure. Respect `Retry-After` when supplied before retrying. |

Do not mask exit 1 with `|| true` when enforcing a check. If the inventory changes, review it before updating `githits-scan.toml`. Automatically running `detect --save` in CI would accept changes without that review.

See the [exit code reference](https://docs.githits.com/scan/commands.md#exit-codes) and [troubleshooting guide](https://docs.githits.com/scan/troubleshooting.md) for details.

## Protect tokens and uploads

Keep secrets out of untrusted fork jobs. Do not use `pull_request_target` to run untrusted code with a token. Keep shell tracing off and inject tokens into the steps that need them.

Review [uploaded data](https://docs.githits.com/scan/overview.md#review-what-you-upload) and [exclusions](https://docs.githits.com/scan/configuration.md#exclusions-and-discovery) before enabling a workflow. Do not automatically resubmit failed jobs in a retry loop. Each new submission can consume quota again. The [HTTP API reference](https://docs.githits.com/api/lockfile-analysis.md) describes upload limits, quota, and job results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.