creating-gha

Creating GitHub Actions

Target: $ARGUMENTS

Creates a Marketplace-ready composite GitHub Action with TDD, signed commits, and proper release flow.

References

• references/marketplace-checklist.md — action.yaml fields, signed commits, release flow, gotchas
• references/python-gha-patterns.md — full Python composite action walkthrough (uv, pyproject.toml, CI)
• references/companion-plugins.md — companion plugins by workflow phase (tdd-core, python-dev, security-audit, commit-helper, makefile-core; built-in /simplify)

Marketplace Requirements

See references/marketplace-checklist.md for full reference.

Required action.yaml fields:

• name — unique on Marketplace (check before using)
• description — shown in search results
• branding — icon (Feather icon name) + color (white/yellow/blue/green/orange/red/purple/gray-dark)

Scaffold

Pick the layout that matches the action's language:

Shell-based (composite with inline run: or scripts/*.sh):

action.yaml           # composite action definition + branding
scripts/              # extracted shell logic (when inline run: grows too large)
tests/unit/           # BATS test files
.github/workflows/    # ci.yaml (bats + actionlint + shellcheck), release.yaml
README.md             # usage example with @vN, inputs table, version badge

Python-based (composite calling uv run):

action.yaml           # composite action definition + branding
src/                  # Python source (app.py entry point)
tests/                # pytest tests
.github/workflows/    # ci.yaml (pytest + ruff), release.yaml
pyproject.toml        # deps, ruff, bumpversion
uv.lock               # committed, CI uses --frozen
README.md             # usage example with @vN, inputs table, version badge

See references/python-gha-patterns.md for the full Python walkthrough.

TDD Workflow

RED — infra tests first:

# tests/unit/test_action.bats
@test "action.yaml exists" { [ -f action.yaml ]; }
@test "action.yaml has name field" { grep -q "^name:" action.yaml; }
@test "action.yaml has description field" { grep -q "^description:" action.yaml; }
@test "action.yaml has branding" { grep -q "^branding:" action.yaml; }
@test "action.yaml has runs.using composite" { grep -q "using: composite" action.yaml; }