# CI with the GitHub Action

> Run Nightshade in GitHub Actions, upload SARIF to code scanning and decide what fails CI.

Canonical: https://nightshade.dicksonwu.xyz/github-action.html
Release: Nightshade 0.1.1 (v0.1.1)

The composite Action builds Nightshade from its pinned source, scans your workspace, uploads SARIF and preserves the scan exit status. It also uploads reports containing incomplete results when a report is available.

## Add a workflow

Save this as `.github/workflows/nightshade.yml`:

```yaml
name: Compact analysis
on: [push, pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  nightshade:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: DicksonWu654/nightshade@v0.1.1
        with:
          path: contracts
          fail-on: medium
          category: compact-contracts
```

Change `contracts` to your source directory. Add your project's dependency installation before the Nightshade step so Compact imports resolve locally. Pin the Nightshade Action to a reviewed commit if you need an immutable dependency.

Use a runner with a C/C++ toolchain. The Action builds the native parser on clean runners; its npm download cache does not reuse compiled native objects across workflows.

## Inputs and outputs

| Input | Purpose |
| --- | --- |
| `path` | Contract file or project directory, relative to the workspace; defaults to `.` |
| `config` | Optional JSON configuration, relative to the workspace |
| `compiler-version` | Optional exact compiler profile; otherwise selected from source pragmas |
| `fail-on` | Finding threshold: `info`, `low`, `medium`, `high`, `critical` or `none`; defaults to `info` |
| `category` | SARIF category; use a distinct value for each application |

Outputs are `exit-code` and `sarif`, the local report path on the runner. Configuration can set rule selection, imports and policies.

## Decide what fails CI

With the default coverage policy, exit 0 means analysis completed and no unsuppressed new finding meets the threshold. Exit 1 means a finding meets it. Exit 2 means incomplete or invalid analysis, configuration error or worker failure. `fail-on: none` does not clear incomplete analysis.

An explicit `ruleIncomplete: warn` configuration allows rule-only gaps to warn when baseline semantics are complete. Reports still say incomplete and retain diagnostics. Baseline, input, configuration and worker failures still fail. Read [configuration and suppressions](https://nightshade.dicksonwu.xyz/configuration.md) before changing this policy.

SARIF upload requires GitHub code-scanning availability and the shown token permissions. Repository and event restrictions can still prevent upload. Local SARIF validation does not establish hosted access. Hosted uploads have not been established by the documented local checks.

[Action source](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/action.yml) | [Full Action guide](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/user-guide.md#github-action) | [Configuration reference](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/configuration.md)