k9-validate-action

Overview

GitHub Action to validate K9 configuration files in your repository.

K9 is a Nickel-based configuration contract format used by the contractile system for deployment validation and policy enforcement. Files use the .k9 or .k9.ncl extension and follow a security-tiered "leash" model: kennel (data-only), yard (validated), and hunt (full execution).

Checks Performed

1. K9! magic number — First non-empty line must be exactly K9!

2. SPDX header — Verifies SPDX-License-Identifier in the first 10 lines

3. Pedigree block — Requires a pedigree = { …​ } section with:

   • name field (in pedigree.metadata or directly)

   • version or schema_version field

4. Security level — leash or security_level must be one of: kennel, yard, hunt

5. Hunt-level signature — Files at hunt security level must include a signature or signature_required field

Usage

Add to your workflow:

name: Validate K9
on: [push, pull_request]

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hyperpolymath/k9-validate-action@v1
        with:
          path: '.'        # Directory to scan (default: repo root)
          strict: 'false'  # Promote warnings to errors (default: false)

Inputs

Input	Default	Description
path	.	Directory path to scan for K9 files
strict	false	When true, warnings become errors and the action fails on any issue

Outputs

Output	Description
files-scanned	Number of K9 files processed
errors	Count of validation errors
warnings	Count of validation warnings

Security Levels

Level	Trust	Requirements
kennel	Data-only	No signature required. Pure configuration values.
yard	Validated	Nickel contracts enforced. Type-checked before use.
hunt	Full access	Signature required. Can execute commands and access system resources.

Author

Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

License

SPDX-License-Identifier: PMPL-1.0-or-later

See LICENSE for details.