Skip to main content
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:
Your repository needs a GraphCheck project (graphcheck.yml and a checks/ directory — see the Quickstart) and a graph reachable from the CI runner.
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.

​
Inputs

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. 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 for the full Action reference.