> ## 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.5.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.5.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, native lifecycle events such as deprecated or withdrawn releases, outdated and duplicate versions, and manifest/lockfile disagreements. Unignored findings, retained lifecycle warnings, and actionable incomplete checks return exit 1. Expected Git coverage limits appear as informational notes and don't fail the step on their own.

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, actionable audit gaps, 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 after Scan's bounded rate-limit recovery. Respect `Retry-After` before a deliberate retry. |

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.