Wire Up CI

hpc-compose ships fast, authoring-time commands (validate, lint) that are well-suited to pre-commit hooks and CI. This page covers three drop-in integrations: a pre-commit hook, a reusable GitHub Actions workflow, and a GitLab CI snippet.

All integrations require the hpc-compose binary to be installed first. The latest installer is:

curl -fsSL https://raw.githubusercontent.com/NicolasSchuler/hpc-compose/main/install.sh | sh

For pinned tags, checksum verification, and other install variants, see Installation. The CI snippets below pin a release tag for reproducible runs.

Pre-commit

The repository ships a .pre-commit-hooks.yaml defining two local hooks that run hpc-compose validate and hpc-compose lint against compose.yaml. Because hpc-compose is not distributed via pip, the hooks use language: system and require the binary to already be on PATH.

Add this repo to your .pre-commit-config.yaml:

Replace vX.Y.Z below with the latest release tag from the GitHub Releases page.

repos:
  - repo: https://github.com/NicolasSchuler/hpc-compose
    rev: vX.Y.Z  # pin to a release tag
    hooks:
      - id: hpc-compose-validate
      - id: hpc-compose-lint

By default the hooks run when a top-level compose.yaml is staged. If your project uses compose.yml or a nested spec, override both entry and files so the hook checks the file that triggered it:

      - id: hpc-compose-validate
        entry: hpc-compose validate -f compose.yml
        files: ^compose\.yml$
      - id: hpc-compose-lint
        entry: hpc-compose lint -f compose.yml --allow-warnings
        files: ^compose\.yml$

hpc-compose-validate fails on any spec error.
hpc-compose-lint passes with --allow-warnings (warnings are advisory). Use hpc-compose-validate plus a strict CI lint (below) to enforce both.

GitHub Actions

Reusable workflow

The simplest integration calls the maintained reusable workflow, which installs a pinned release and runs validate + lint. Replace vX.Y.Z with the latest release tag from the GitHub Releases page:

jobs:
  hpc-compose:
    uses: NicolasSchuler/hpc-compose/.github/workflows/hpc-compose-lint.yml@vX.Y.Z
    with:
      compose-file: compose.yaml
      version: vX.Y.Z
      strict: true

Set strict: true to fail on lint warnings, or strict: false (default) to allow warnings. Pin both the uses: ref and version to the same release tag.

Inline snippet

For repos that prefer an inline step. Replace vX.Y.Z with the latest release tag from the GitHub Releases page:

jobs:
  lint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Install hpc-compose
        run: |
          set -euo pipefail
          curl -fsSL "https://raw.githubusercontent.com/NicolasSchuler/hpc-compose/vX.Y.Z/install.sh" \
            | env HPC_COMPOSE_VERSION="vX.Y.Z" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: hpc-compose validate -f compose.yaml
      - run: hpc-compose lint -f compose.yaml --allow-warnings

GitLab CI

GitLab runners typically do not provide hpc-compose, so install it inside the job first. Replace vX.Y.Z with the latest release tag from the GitHub Releases page:

hpc-compose-lint:
  image: alpine:3.20
  rules:
    - changes: [compose.yaml]
  variables:
    HPC_COMPOSE_VERSION: vX.Y.Z
  before_script:
    - apk add --no-cache curl ca-certificates
    - |
      curl -fsSL "https://raw.githubusercontent.com/NicolasSchuler/hpc-compose/${HPC_COMPOSE_VERSION}/install.sh" \
        | env HPC_COMPOSE_VERSION="${HPC_COMPOSE_VERSION}" sh
    - export PATH="${HOME}/.local/bin:${PATH}"
  script:
    - hpc-compose validate -f compose.yaml
    - hpc-compose lint -f compose.yaml --allow-warnings

Strict vs. warnings

validate always fails on structural spec errors. lint emits advisory findings (HPC001–HPC007, HPC900); by default these fail the command, so add --allow-warnings for advisory-only runs. A common setup is:

pre-commit / local: lint --allow-warnings (fast feedback, advisory).
CI (merge gate): lint without --allow-warnings, or strict: true (enforce).

See CLI Reference for the full lint rule table and Troubleshooting for related workflows.

Keyboard shortcuts

hpc-compose