Build documentation in GitHub Actions

Keep your publication configuration with your ontologies, then use one GraphArch step to build their specification website, PDF and documentation KG. The action installs and verifies the GraphArch release it belongs to before running the build.

Build in one step

Reference the action by the full commit SHA of a GraphArch release, with the release tag as a comment. After checking out your repository, add this step:

- uses: actions/checkout@v7
- uses: EKGF/grapharch@<release-commit-sha> # vX.Y.Z
  id: docs
  with:
    source-kind: checkout
    source: .
    output: build/docs

The reference alone selects the generator. The action reads the version from its own Cargo.toml, takes its own commit from the reference, and installs the native binary of that release. Before running it, the action checks the published archive against its .sha256 file and the release manifest against the version, platform, archive checksum and source commit. The manifest's source_commit must be the action's commit. A branch, a tag name, a short SHA, or a commit that is not the release commit of its version fails the action. It never compiles a replacement or downloads another release. Self-selection is available from the first release after v0.2.8; earlier releases need version and expected-revision.

Use the commit of the release tag, not the annotated tag object. The release page shows it, or run:

git ls-remote https://github.com/EKGF/grapharch 'refs/tags/vX.Y.Z^{}'

GraphArch discovers a unique project and target from publication hints in your repository’s RDF. Put those hints in your ontologies or a separate RDF file alongside them. Ambiguous or incomplete hints fail explicitly. To use external definitions instead, supply definitions, project and target together.

source-kind: checkout records provenance from a local Git checkout. Use directory to collect a plain source directory; GraphArch never switches between these modes implicitly. Paths with spaces are supported. Keep generated output directories ignored in your repository when also building locally.

The step exposes publication-path, pdf-path and kg-path as absolute paths. The publication path is the website directory containing index.html. Use these outputs to upload artifacts or integrate your own deployment process. The KG archive is exposed separately. pdf-path is empty for paginated or bookshelf publications without a single collection PDF; book PDFs remain inside the publication directory. A failed build fails the step.

For installation alone, set mode: install; the grapharch command is then available to subsequent steps:

- uses: EKGF/grapharch@<release-commit-sha> # vX.Y.Z
  id: grapharch
  with:
    mode: install

Both modes expose version, revision and binary-path. revision is the verified release source commit. Deployment is a separate choice.

Upgrade with Dependabot

Because one line selects both the action and its binary, Dependabot upgrades GraphArch with a single change. Enable version updates for GitHub Actions in .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

For a new release, Dependabot replaces the commit SHA and the # vX.Y.Z comment together. Review and merge the pull request; the action then installs the new release. Each automatic release tags its own release commit, so every vX.Y.Z tag commit carries the action and the Cargo.toml of that release.

Install from a checked-out release

A workflow can also check out GraphArch at a release commit, for example when a configuration file records the generator revision, and run that checkout as a local action:

- uses: actions/checkout@v7
  with:
    repository: EKGF/grapharch
    ref: ${{ steps.configuration.outputs.generator-revision }}
    path: .grapharch-tool
    persist-credentials: false
- uses: ./.grapharch-tool
  id: grapharch
  with:
    mode: install

A local action has no reference, so it identifies itself by the HEAD commit of its checkout. The action path must be the root of that Git checkout, and the checkout must be clean, with no modified, untracked or extra ignored executable inputs. The same release verification then applies: the HEAD commit must be the release commit of the checked-out version.

Install another release explicitly

Supply version and expected-revision together to install a release other than the action's own:

- uses: EKGF/grapharch@v0
  with:
    mode: install
    version: 'X.Y.Z'
    expected-revision: <release-commit-sha>

The action verifies that release against expected-revision exactly as it verifies its own. Use this when the action reference is not a release commit: the floating v0 and v0.2 references, a checkout of an unreleased commit, or a composite action of your own that wraps this one. Within a wrapping composite action, the runner reports the outer action's reference instead of this one (actions/runner#2473), so self-selection fails there. version without expected-revision, or the reverse, fails before anything is downloaded.

An automatic release advances the Action convenience tags vMAJOR and vMAJOR.MINOR only after all its publication channels succeed. EKGF/grapharch@v0 follows the maintained Action implementation within major version zero. Because these references move, they never select a binary themselves. Existing repository workflows are never rewritten by a release.

Install an unreleased source revision

On Linux runners, the same action can build an exact reviewed source revision. Check out GraphArch separately, then invoke that local action with source-revision:

- uses: actions/checkout@v7
  with:
    repository: EKGF/grapharch
    ref: ${{ steps.configuration.outputs.generator-revision }}
    path: .grapharch-tool
    persist-credentials: false
- uses: ./.grapharch-tool
  id: grapharch
  with:
    mode: install
    source-revision: ${{ steps.configuration.outputs.generator-revision }}

The configuration output must contain the full 40-character Git commit SHA. The action verifies that its checkout matches and has no modified or extra executable inputs, installs Linux compiler dependencies and the repository's pinned Rust toolchain, then builds with cargo build --locked --release. The runner must provide Git, rustup, and sudo access to apt-get, as standard GitHub-hosted Ubuntu runners do. Source builds are not supported on macOS or Windows yet; release installation remains available there.

binary-path and version retain their existing meanings; revision records the exact source commit. Source builds use a separate runner-temporary build directory and do not use the release binary cache. source-revision excludes version and expected-revision; an invalid selector or failed build fails the action. Every selection supports mode: install and the normal family build mode.

Build a Pages artifact

The reusable workflow checks out your repository, builds the family, and stages the generated website with a downloadable documentation.nq. It uploads a Pages artifact without deploying by default. Start with a manual workflow:

name: Documentation
on:
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  documentation:
    uses: EKGF/grapharch/.github/workflows/publish-family-pages.yml@v0.2.4
    with:
      version: '0.2.4'
      source-kind: checkout
      source: .
      deploy: false

For an immutable pin, replace v0.2.4 with the release commit SHA after reviewing it. Its internal GraphArch step is also pinned to a reviewed commit. The workflow reads the publication paths returned by the build; it does not recollect sources to assemble the deployment artifact.

After inspecting the artifact, enable GitHub Pages with GitHub Actions as the publishing source and set deploy: true. The deployment uses the github-pages environment and returns a page-url workflow output. Set include-kg: false to omit the downloadable KG. You can add branch triggers when you are ready for automatic publication.

Check live showcases in CI

GraphArch’s own gallery is also an integration test suite. Run every declared showcase and retain evidence when an upstream repository changes:

grapharch publication verify-gallery \
  --source examples --project urn:grapharch:docs \
  --output-root output/showcase-verification --json

Use a new or empty output directory. Verification checks every case with bounded parallelism, records unexpected failures as KG diagnostics, and exits nonzero if any case fails. It retains report.json, verification.nq, and each available case’s artifacts and KG. A collection failure may prevent a case KG from being available; the report says so explicitly. Repository failures include the observed commit and source location. A case also fails when a relative href or src in its published HTML does not name a file that the same case publishes, such as a PDF edition that was not built. Absolute links are not fetched.

The GraphArch website workflow runs these live checks on changes and nightly. It uploads the evidence even when verification fails and blocks publication of an incomplete gallery. Pinned offline fixtures remain separate regression tests; they are never substituted for an unavailable live source.

Local UML rendering dependency

The action explicitly installs Temurin Java 21 and PlantUML MIT 1.2026.9 during setup, including mode: install. The official release JAR is pinned by SHA-256 in packaging/setup_plantuml.py; cached bytes are rechecked before use. Setup verifies the reported version and renders a small Smetana class diagram before adding the launcher to PATH. Unsupported platforms, checksum mismatches and missing Java fail setup.

OWL diagram generation needs this local renderer. Smetana runs inside Java and does not require Graphviz. Authored PlantUML diagrams that explicitly use other layout engines may have additional prerequisites. The CLI does not download a renderer or send ontology content to an external service. Rendering an already collected and documented KG requires neither Java nor PlantUML.

Repository CI uses .github/actions/setup-plantuml, which calls the same installer. Direct CLI users must install Java and PlantUML on PATH themselves. The JAR is an explicit CI tool dependency, not bundled into GraphArch binaries.

Search documentation

Enter words to search this site.