GitHub Actions

    StructKit has two separate GitHub Actions: httpdss/structkit-setup@v0 installs StructKit only, and httpdss/structkit-action@v0 runs validate or generate, including drift detection.

    Setup uses uv tool install, caches by OS, architecture, Python version, and StructKit version, and puts structkit on PATH so any StructKit command can run in later steps. The runner Action does not install StructKit: add setup before it.

    Earlier releases of structkit-action installed StructKit themselves using structkit_version / python_version inputs. Those inputs are now removed; use structkit-version / python-version on structkit-setup instead.

    Quick start

    .github/workflows/structkit.ymlyaml
    name: StructKit
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: httpdss/structkit-setup@v0
      - uses: httpdss/structkit-action@v0
        with:
          command: validate

    If struct_file is empty, structkit-action uses .structkit.yaml, falling back to the legacy .struct.yaml.

    Drift check on pull requests

    Generate in dry-run mode, print the diff, and fail the job when the repository has drifted from its structure definition:

    on: pull_request
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: httpdss/structkit-setup@v0
      - uses: httpdss/structkit-action@v0
        with:
          command: generate
          dry_run: 'true'
          diff: 'true'
          fail_on_diff: 'true'

    Setup only, run any command

          - uses: httpdss/structkit-setup@v0
        id: structkit
      - run: structkit list
      - run: echo "Installed ${{ steps.structkit.outputs.version }} (cache hit: ${{ steps.structkit.outputs.cache-hit }})"

    Pin a version and disable cache

          - uses: httpdss/structkit-setup@v0
        with:
          structkit-version: '3.3.0'
          python-version: '3.12'
          cache: 'false'

    structkit-setup inputs

    InputDefaultDescription
    structkit-versionlatest"latest", an exact PyPI version, or a git URL.
    python-version3.xPython version used to install StructKit.
    cachetrueCache the installed tool; set to 'false' to disable.

    Outputs

    • version — resolved version or git URL.
    • cache-hit — true/false.

    structkit-action inputs

    InputDefaultDescription
    commandvalidatevalidate or generate.
    struct_file''Empty means auto-detect .structkit.yaml, then legacy .struct.yaml.
    output_dir.Directory to generate into.
    dry_runfalseGenerate without writing files.
    difffalsePrint a diff of generated changes.
    no_hooksfalseSkip generation hooks; requires StructKit >= 3.3.0.
    non_interactivefalseNever block on a confirmation prompt.
    structures_path''Local path to custom structures.
    structures_repository''Custom structures repository in owner/repo form.
    structures_repository_pathstructuresPath within the structures repository.
    structures_repository_refmainBranch, tag, or commit of the structures repository.
    extra_args''Additional CLI arguments.
    fail_on_difffalseFail when structure drift is detected.

    Outputs

    • success
    • has_changes
    • diff_file
    • exit_code

    CI safety defaults

    Both no_hooks and non_interactive default to false — opt in to skip generation hooks and prevent confirmation prompts. no_hooks requires StructKit >= 3.3.0:

    - uses: httpdss/structkit-setup@v0
- uses: httpdss/structkit-action@v0
  with:
    command: generate
    no_hooks: 'true'
    non_interactive: 'true'

    See Hook safety controls for what these flags do.

    Alternative: install the CLI in a job

    If you prefer not to use either Action, install StructKit with pip:

    .github/workflows/structkit.ymlyaml
    name: Generate Structure
on:
  push:
    branches: [main]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Install StructKit
        run: pip install structkit
      - name: Generate structure
        run: structkit generate .structkit.yaml . --no-hooks
      - name: Commit changes
        run: |
          git add .
          git diff --staged --quiet || git commit -m "chore: update project structure"

    Built-in GitHub Structures

    StructKit includes several GitHub-related structure templates:

    • github/templates — Issue and PR templates
    • github/workflows/run-struct — StructKit workflow
    • github/workflows/labeler — Auto-labeler workflow
    • github/workflows/stale — Stale issues workflow
    • github/workflows/pre-commit — Pre-commit workflow
    • github/workflows/release-drafter — Release drafter workflow

    Related

    Previous

    MCP Integration

    Next

    Hermes Agent