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

# CI Setup

> Run GraphCheck in GitHub Actions and gate merges on the exit-code contract

GraphCheck ships as a reusable composite GitHub Action. It installs a pinned GraphCheck version
from PyPI, connects to your graph, runs your checks, sets the workflow job status from the exit code, and
writes a detailed pass/fail/error breakdown to the workflow-run summary.

## Usage

Reference the Action from the GraphCheck repository, pinned to a commit SHA (it is not yet listed
on the GitHub Marketplace), and set the released GraphCheck version explicitly:

```yaml theme={null}
- uses: actions/checkout@v4
- uses: graphora/graphcheck/.github/actions/graphcheck-action@c735adecdc455a0040ec819fc0d63f363fd8e503 # v0.2.0
  with:
    version: '0.2.0'
    profile: ci
    uri: bolt://localhost:7687
    user: neo4j
    database: neo4j
    fail-fast: false
  env:
    NEO4J_PASSWORD: ${{ secrets.NEO4J_PASSWORD }}
```

Your repository needs a GraphCheck project (`graphcheck.yml` and a `checks/` directory — see the
[Quickstart](/graphcheck/quickstart)) and a graph reachable from the CI runner.

<Note>
  Setting `version: ''` skips the PyPI install and uses whatever `graphcheck` is already on the
  job's PATH. That mode exists for development inside the GraphCheck repository itself, where the
  workflow installs from source first; consumer repositories should always pin a released version.
</Note>

## Inputs

| Input       | Required | Default | Description                                                                                                                                                                               |
| ----------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profile`   | no       | `ci`    | Profile name to generate and use, if `profiles.yml` does not already exist                                                                                                                |
| `uri`       | yes      | -       | Neo4j Bolt URI                                                                                                                                                                            |
| `user`      | yes      | -       | Neo4j username                                                                                                                                                                            |
| `database`  | no       | `neo4j` | Neo4j database name                                                                                                                                                                       |
| `fail-fast` | no       | `false` | Stop after the first error-severity failure                                                                                                                                               |
| `suite`     | no       | -       | Suite name to run via `--suite`; skipped if empty                                                                                                                                         |
| `version`   | no       | `0.1.0` | Exact GraphCheck version to install from PyPI. Set it explicitly (`0.2.0` is current); the default lags releases. Empty skips the install and uses whatever GraphCheck is already on PATH |

Leaving `version` empty is a development escape hatch for the GraphCheck repository itself, where
GraphCheck is installed from source earlier in the job. Consumer repositories should always pin an
explicit released version.

## Exit codes and job status

The job's final status is the run's original exit code, preserved through the upload/summary
steps - those steps always run (`if: always()`), but never mask or overwrite the run's result.

| Exit | Meaning                                                                                                                 | Job status |
| ---- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| 0    | Complete run with at least one evaluated check, where every evaluated check passed; generated skips may also be present | green      |
| 1    | A check failed, or an error-severity check errored                                                                      | red        |
| 2    | Incomplete coverage, or a warning                                                                                       | red        |
| 3    | The run could not execute (bad config, no connection, setup failure)                                                    | red        |

The pass/fail/warn/error breakdown written to the workflow-run summary is read from `results.json`, not
inferred from the exit code - the two are independent, since exit 1 covers both a failed check and
an error-severity errored check.

## What it does

1. Installs the pinned GraphCheck version from PyPI, unless `version` is empty.
2. Resolves the artifacts directory from `graphcheck.yml` (defaults to `.graphcheck`).
3. If `profiles.yml` does not already exist, generates one from the `uri`/`user`/`database`
   inputs. Only `password_env: NEO4J_PASSWORD` is written - the real password is never in the
   generated file, and is read from the `NEO4J_PASSWORD` environment variable at runtime.
4. Runs `graphcheck run` using the given profile.
5. Removes the generated `profiles.yml`, only if this Action created it.
6. Uploads `results.json` and the HTML report as build artifacts, whenever they were produced. If
   an early failure produced none, the summary says so explicitly rather than uploading nothing
   silently.
7. Writes a pass/fail/errored/warn breakdown to the GitHub Step Summary.

## Notes

* This Action requires a graph reachable from the CI runner.
* The install step runs on a pinned Python 3.12 via `actions/setup-python`, but only when
  installing from PyPI (`version` is non-empty) - a source install earlier in the job is expected
  to have already set up the interpreter it needs.

See [`.github/actions/graphcheck-action/README.md`](https://github.com/graphora/graphcheck/blob/development/.github/actions/graphcheck-action/README.md)
for the full Action reference.