Skip to content

Commit 14d398c

Browse files
NagyViktNagyVikt
NagyVikt
and
NagyVikt
authored
feat(skills): add gx-act for running GitHub Actions locally with nektos/act (#602)
Adds a first-class skill and `/gx-act` slash command that wraps nektos/act (https://github.com/nektos/act), so agents run CI workflows locally before pushing. The remote PR run then lands green on the first round-trip and can be squash-merged immediately. - skills/gx-act/SKILL.md (top-level) - .claude/skills/gx-act/SKILL.md (Claude Code mirror) - templates/codex/skills/gx-act/SKILL.md (codex install template) - .claude/commands/gx-act.md (slash command source) - src/cli/commands/claude.js: register gx-act.md in MANAGED_SLASH_COMMANDS so `gx claude install` propagates the command into target repos - AGENTS.md / CLAUDE.md quickstart: mention /gx-act and the local-CI-then-squash-merge flow Verification: node --test test/claude-install.test.js passes 12/12. Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
1 parent b8ec4ff commit 14d398c

8 files changed

Lines changed: 359 additions & 2 deletions

File tree

‎.claude/commands/gx-act.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# /gx-act
2+
3+
Run GitHub Actions workflows locally with [nektos/act](https://github.com/nektos/act) before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run.
4+
5+
## Pre-conditions
6+
7+
- Docker (or Podman) is running.
8+
- `act` is installed:
9+
10+
```sh
11+
command -v act || curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
12+
```
13+
14+
## Default flow
15+
16+
1. Inspect what would run:
17+
18+
```sh
19+
act -l
20+
```
21+
22+
2. Execute the push workflows locally:
23+
24+
```sh
25+
act push
26+
```
27+
28+
Or a single job / event:
29+
30+
```sh
31+
act -j <job-name>
32+
act pull_request
33+
act workflow_dispatch -W .github/workflows/release.yml
34+
```
35+
36+
3. Only after `act` is green, hand off to the finish flow:
37+
38+
```sh
39+
gx branch finish \
40+
--branch "$(git branch --show-current)" \
41+
--base main \
42+
--via-pr \
43+
--wait-for-merge \
44+
--cleanup
45+
```
46+
47+
4. Squash-merge the PR on GitHub once the remote run mirrors the local one.
48+
49+
## When to use vs the remote run
50+
51+
- `act` is a **fast pre-flight**: catches syntax errors, missing tools, broken matrix configs, obvious test failures.
52+
- It does **not** replace the remote run. GitHub-hosted services, real secrets, and concurrency groups only exist remotely. Treat green `act` as a strong signal, full proof comes from the PR's checks.
53+
54+
## Secrets and env
55+
56+
Never commit secrets. Pass them at invocation time:
57+
58+
```sh
59+
act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
60+
```
61+
62+
Add `.env.act` to `.gitignore` if you create one.
63+
64+
## Notes
65+
66+
- Pin a runner image close to GitHub's: `act -P ubuntu-latest=catthehacker/ubuntu:act-latest`.
67+
- `act --reuse` keeps containers between runs for faster iteration.
68+
- Store shared flags in `.actrc` at the repo root so every agent uses the same setup.

‎.claude/skills/gx-act/SKILL.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: gx-act
3+
description: "Run GitHub Actions workflows locally with nektos/act before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run."
4+
---
5+
6+
# gx-act — local GitHub Actions
7+
8+
Use whenever a change touches code that would trigger CI on GitHub. Run the workflows locally with `act` first; only push the branch when the local run is green, then squash-merge the PR on GitHub.
9+
10+
## When to invoke
11+
12+
- Before `gx pr open` / `gx pr sync` / `gx branch finish --via-pr`.
13+
- Before re-pushing after a CI failure.
14+
- When iterating on `.github/workflows/*.yml` itself.
15+
16+
## Install `act`
17+
18+
`act` requires Docker (or Podman). Check the binary:
19+
20+
```sh
21+
command -v act || echo "act not installed"
22+
```
23+
24+
Install one way:
25+
26+
```sh
27+
# Linux/macOS via the upstream installer
28+
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
29+
30+
# macOS via Homebrew
31+
brew install act
32+
33+
# Arch
34+
sudo pacman -S act
35+
36+
# Or use the GitHub CLI extension
37+
gh extension install https://github.com/nektos/gh-act
38+
```
39+
40+
Upstream: https://github.com/nektos/act
41+
42+
## Quick commands
43+
44+
```sh
45+
# List jobs the local runner would execute for the push event
46+
act -l
47+
48+
# Run the default push workflows (what GitHub runs on a normal push)
49+
act push
50+
51+
# Run a specific event
52+
act pull_request
53+
act workflow_dispatch -W .github/workflows/release.yml
54+
55+
# Run a single job
56+
act -j test
57+
58+
# Pin a runner image (medium is the act default; large matches real GH closer)
59+
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
60+
61+
# Pass secrets / env without committing them
62+
act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
63+
64+
# Reuse containers between runs (faster iteration)
65+
act --reuse
66+
```
67+
68+
## Workflow (local CI → squash-merge on GitHub)
69+
70+
1. Implement the change in the agent worktree.
71+
2. `act -l` to confirm which jobs will fire for the event you care about.
72+
3. `act push` (or the specific event/job) until it is green locally.
73+
4. `gx branch finish --branch "<agent-branch>" --base main --via-pr --wait-for-merge --cleanup`.
74+
- Or `gx pr open` then `gx pr sync --auto-merge --merge-strategy squash` for explicit PR control.
75+
5. On GitHub: squash-merge once the remote run mirrors the local one.
76+
77+
## Notes
78+
79+
- `act` does not reproduce GitHub-hosted services exactly (no real secrets, different runner image, no concurrency groups). Treat a green `act` run as a strong signal, not a proof — the remote run is still authoritative.
80+
- Keep `act` config in `.actrc` at the repo root so every agent uses the same runner image.
81+
- If a workflow uses `GITHUB_TOKEN` for API calls, pass a PAT via `-s GITHUB_TOKEN=...`; do not commit it.
82+
- Add `.actrc`, `.cache/act`, and any `act`-specific event payloads to `.gitignore` if they appear.

‎AGENTS.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@ If you are a Claude Code session arriving in this repo for the first time:
1818
namespaces, set `GUARDEX_AGENT_BRANCH_PREFIXES_ONLY=1` plus an explicit
1919
list.
2020
2. **Slash commands** — `/gx-status`, `/gx-doctor`, `/gx-pivot`,
21-
`/gx-pr`, `/gx-finish`, `/gx-setup` are available out of the box. See
22-
`.claude/commands/`.
21+
`/gx-pr`, `/gx-finish`, `/gx-setup`, `/gx-act` are available out of the
22+
box. See `.claude/commands/`. `/gx-act` wraps
23+
[nektos/act](https://github.com/nektos/act) so CI workflows run locally
24+
before the remote PR run, letting you squash-merge on the first green
25+
round-trip.
2326
3. **PR flow** — when you need explicit PR control, use `gx pr open`,
2427
`gx pr status`, `gx pr sync`, or `gx pr watch`. For end-of-task
2528
commit + push + PR + merge + cleanup, still use the non-negotiable

‎openspec/changes/agent-claude-add-nektos-act-skill-2026-05-18-10-00/.openspec.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
schema: spec-driven
2+
created: 2026-05-18

‎openspec/changes/agent-claude-add-nektos-act-skill-2026-05-18-10-00/notes.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# agent-claude-add-nektos-act-skill-2026-05-18-10-00 (minimal / T1)
2+
3+
Branch: `agent/claude/add-nektos-act-skill-2026-05-18-10-00`
4+
5+
## Change
6+
7+
Add `gx-act` skill + `/gx-act` slash command for running GitHub Actions
8+
locally with [nektos/act](https://github.com/nektos/act) before pushing,
9+
so PR remote runs land green on the first round-trip and can be
10+
squash-merged immediately.
11+
12+
Files added:
13+
14+
- `skills/gx-act/SKILL.md` — top-level skill (Codex auto-loadable).
15+
- `.claude/skills/gx-act/SKILL.md` — Claude Code skill mirror.
16+
- `templates/codex/skills/gx-act/SKILL.md` — codex install template.
17+
- `.claude/commands/gx-act.md` — `/gx-act` slash command source.
18+
19+
Files modified:
20+
21+
- `src/cli/commands/claude.js` — `MANAGED_SLASH_COMMANDS` now includes
22+
`gx-act.md` so `gx claude install` propagates `/gx-act` into target
23+
repos.
24+
- `AGENTS.md` (and via symlink `CLAUDE.md`) — quickstart mentions
25+
`/gx-act` and the local-CI-then-squash-merge flow.
26+
27+
## Verification
28+
29+
- `node --test test/claude-install.test.js` — 12 pass, 0 fail.
30+
- Full `npm test` shows 23 unrelated pre-existing failures (same on
31+
bare `main` at b8ec4ff); none touch slash-command or skill installs.
32+
33+
## Cleanup
34+
35+
- [ ] Run: `gx branch finish --branch agent/claude/add-nektos-act-skill-2026-05-18-10-00 --base main --via-pr --wait-for-merge --cleanup`
36+
- [ ] Record PR URL + `MERGED` state in the completion handoff.
37+
- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).

‎skills/gx-act/SKILL.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: gx-act
3+
description: "Run GitHub Actions workflows locally with nektos/act before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run."
4+
---
5+
6+
# gx-act — local GitHub Actions
7+
8+
Use whenever a change touches code that would trigger CI on GitHub. Run the workflows locally with `act` first; only push the branch when the local run is green, then squash-merge the PR on GitHub.
9+
10+
## When to invoke
11+
12+
- Before `gx pr open` / `gx pr sync` / `gx branch finish --via-pr`.
13+
- Before re-pushing after a CI failure.
14+
- When iterating on `.github/workflows/*.yml` itself.
15+
16+
## Install `act`
17+
18+
`act` requires Docker (or Podman). Check the binary:
19+
20+
```sh
21+
command -v act || echo "act not installed"
22+
```
23+
24+
Install one way:
25+
26+
```sh
27+
# Linux/macOS via the upstream installer
28+
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
29+
30+
# macOS via Homebrew
31+
brew install act
32+
33+
# Arch
34+
sudo pacman -S act
35+
36+
# Or use the GitHub CLI extension
37+
gh extension install https://github.com/nektos/gh-act
38+
```
39+
40+
Upstream: https://github.com/nektos/act
41+
42+
## Quick commands
43+
44+
```sh
45+
# List jobs the local runner would execute for the push event
46+
act -l
47+
48+
# Run the default push workflows (what GitHub runs on a normal push)
49+
act push
50+
51+
# Run a specific event
52+
act pull_request
53+
act workflow_dispatch -W .github/workflows/release.yml
54+
55+
# Run a single job
56+
act -j test
57+
58+
# Pin a runner image (medium is the act default; large matches real GH closer)
59+
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
60+
61+
# Pass secrets / env without committing them
62+
act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
63+
64+
# Reuse containers between runs (faster iteration)
65+
act --reuse
66+
```
67+
68+
## Workflow (local CI → squash-merge on GitHub)
69+
70+
1. Implement the change in the agent worktree.
71+
2. `act -l` to confirm which jobs will fire for the event you care about.
72+
3. `act push` (or the specific event/job) until it is green locally.
73+
4. `gx branch finish --branch "<agent-branch>" --base main --via-pr --wait-for-merge --cleanup`.
74+
- Or `gx pr open` then `gx pr sync --auto-merge --merge-strategy squash` for explicit PR control.
75+
5. On GitHub: squash-merge once the remote run mirrors the local one.
76+
77+
## Notes
78+
79+
- `act` does not reproduce GitHub-hosted services exactly (no real secrets, different runner image, no concurrency groups). Treat a green `act` run as a strong signal, not a proof — the remote run is still authoritative.
80+
- Keep `act` config in `.actrc` at the repo root so every agent uses the same runner image.
81+
- If a workflow uses `GITHUB_TOKEN` for API calls, pass a PAT via `-s GITHUB_TOKEN=...`; do not commit it.
82+
- Add `.actrc`, `.cache/act`, and any `act`-specific event payloads to `.gitignore` if they appear.

‎src/cli/commands/claude.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ const MANAGED_HOOK_FILES = [
2929
];
3030

3131
const MANAGED_SLASH_COMMANDS = [
32+
'gx-act.md',
3233
'gx-doctor.md',
3334
'gx-finish.md',
3435
'gx-pivot.md',

‎templates/codex/skills/gx-act/SKILL.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
name: gx-act
3+
description: "Run GitHub Actions workflows locally with nektos/act before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run."
4+
---
5+
6+
# gx-act — local GitHub Actions
7+
8+
Use whenever a change touches code that would trigger CI on GitHub. Run the workflows locally with `act` first; only push the branch when the local run is green, then squash-merge the PR on GitHub.
9+
10+
## When to invoke
11+
12+
- Before `gx pr open` / `gx pr sync` / `gx branch finish --via-pr`.
13+
- Before re-pushing after a CI failure.
14+
- When iterating on `.github/workflows/*.yml` itself.
15+
16+
## Install `act`
17+
18+
`act` requires Docker (or Podman). Check the binary:
19+
20+
```sh
21+
command -v act || echo "act not installed"
22+
```
23+
24+
Install one way:
25+
26+
```sh
27+
# Linux/macOS via the upstream installer
28+
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
29+
30+
# macOS via Homebrew
31+
brew install act
32+
33+
# Arch
34+
sudo pacman -S act
35+
36+
# Or use the GitHub CLI extension
37+
gh extension install https://github.com/nektos/gh-act
38+
```
39+
40+
Upstream: https://github.com/nektos/act
41+
42+
## Quick commands
43+
44+
```sh
45+
# List jobs the local runner would execute for the push event
46+
act -l
47+
48+
# Run the default push workflows (what GitHub runs on a normal push)
49+
act push
50+
51+
# Run a specific event
52+
act pull_request
53+
act workflow_dispatch -W .github/workflows/release.yml
54+
55+
# Run a single job
56+
act -j test
57+
58+
# Pin a runner image (medium is the act default; large matches real GH closer)
59+
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
60+
61+
# Pass secrets / env without committing them
62+
act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
63+
64+
# Reuse containers between runs (faster iteration)
65+
act --reuse
66+
```
67+
68+
## Workflow (local CI → squash-merge on GitHub)
69+
70+
1. Implement the change in the agent worktree.
71+
2. `act -l` to confirm which jobs will fire for the event you care about.
72+
3. `act push` (or the specific event/job) until it is green locally.
73+
4. `gx branch finish --branch "<agent-branch>" --base main --via-pr --wait-for-merge --cleanup`.
74+
- Or `gx pr open` then `gx pr sync --auto-merge --merge-strategy squash` for explicit PR control.
75+
5. On GitHub: squash-merge once the remote run mirrors the local one.
76+
77+
## Notes
78+
79+
- `act` does not reproduce GitHub-hosted services exactly (no real secrets, different runner image, no concurrency groups). Treat a green `act` run as a strong signal, not a proof — the remote run is still authoritative.
80+
- Keep `act` config in `.actrc` at the repo root so every agent uses the same runner image.
81+
- If a workflow uses `GITHUB_TOKEN` for API calls, pass a PAT via `-s GITHUB_TOKEN=...`; do not commit it.
82+
- Add `.actrc`, `.cache/act`, and any `act`-specific event payloads to `.gitignore` if they appear.

0 commit comments

Comments
 (0)