creating-gha · diff
git:20260404.d174eb3 to git:20260418.9c50b2a
26 added, 2 removed. Audit A to A.
---
name: creating-gha
description: Creates GitHub Actions for the Marketplace. Use when scaffolding a new action, implementing composite steps, writing BATS tests, or preparing a Marketplace release.
compatibility: Designed for Claude Code
metadata:
allowed-tools: Read, Grep, Glob, Edit, Write, Bash, WebSearch, WebFetch
argument-hint: [action-name]
stability: stable
---
# 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, simplify, security-audit, commit-helper, makefile-core)
+
## 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/ # shell scripts called by action steps
+ 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 @v1, inputs table, version badge
+ 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:**
```bash
# 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; }
```
Run: `bats tests/unit/` — all must fail first.
**GREEN — implement to pass:**
Write `action.yaml` with required fields. Add `scripts/` and steps. Run `bats tests/unit/` — all pass.
**VALIDATE:**
```bash
actionlint
shellcheck scripts/*.sh
```
## Commit Flow (protected main — no direct push)
Use signed commit via GitHub API (blob→tree→commit→branch→PR→squash).
See `references/marketplace-checklist.md` for the full bash pattern.
Never `git push` directly to main.
## Release Flow
1. Merge PR to main
2. Trigger `release.yaml` workflow (uses `bump-my-version` with `commit=false tag=false`)
3. Workflow creates `v0.1.0` tag + GitHub Release + floating `v0` tag
4. On GitHub Release page: check "Publish this Action to the GitHub Marketplace"
## Quality Checks
```bash
actionlint
shellcheck scripts/*.sh
bats tests/unit/
```
All must pass before PR creation.
## Repository Security Settings
- **Actions permissions**: allow owner + selected non-owner actions only
- **Commit SHA pinning**: require for all third-party actions
- **Workflow permissions**: read-only default (workflows declare writes explicitly)
- **Artifact/log retention**: 30 days (not default 90)
- **Cache retention**: 7 days, 1 GB limit
- **Fork PR approval**: require for all external contributors
- **Allow Actions to create PRs**: enabled (for bump + data workflows)
## Python GHA Pattern (uv)
```yaml
- uses: astral-sh/setup-uv@v6
with:
enable-cache: true
- run: |
uv sync --frozen --no-dev --project "${{ github.action_path }}"
uv run --project "${{ github.action_path }}" python "${{ github.action_path }}/src/app.py"
```