AGENTS.md

Guidance for coding agents working in this repository.

Act runs GitHub Actions locally. It reads .github/workflows/, builds an execution plan, and uses Docker to run each action. The Go version is the go line in go.mod (currently 1.26.0).

Commands

• make build — build the binary to dist/local/act
• make test — go test ./..., then run the act CLI against a sample workflow (needs a Docker daemon)
• make test-fast — go test -short ./.... Skips Docker integration tests. No Docker daemon required. Usually about a minute.
• make lint-go — golangci-lint run (CI pins v2.11.4)
• make format — go fmt ./...
• make tidy — go mod tidy
• make pr — tidy, format-all, lint, and test
• make promote — fetch tags, then tag the next patch release when the current branch is ahead of the last release. It pushes only the tag, never a commit, and HEAD must equal origin/<branch>. promote.yml sets PROMOTE_BRANCH to the repository default branch (main after the rename). A clean HEAD whose release tag is already on origin logs that and exits 0. A dirty worktree (including untracked files), a missing release tag, or a failed push still fails. A release tag that exists only locally is pushed.
• Version: release builds set main.version from the tag with ldflags (GoReleaser, make build). go install github.com/nektos/act@vX uses the module version. The committed VERSION file is only the fallback and is no longer bumped on release.
• make snapshot — local GoReleaser snapshot (goreleaser build --clean --single-target --snapshot)
• go test ./pkg/runner/ -run TestRunEvent — run a single test

make pr formats Markdown and JavaScript with npx as well as Go. The Makefile loads GITHUB_TOKEN from ~/.config/github/token when that file exists.

Layout

Execution flow:

1. CLI (cmd/root.go) — Cobra parses flags into an Input struct
2. Planner (pkg/model/planner.go) — parses workflow YAML into a Plan of serial Stages, each with parallel Runs
3. Runner (pkg/runner/runner.go) — turns the plan into Executor chains
4. RunContext (pkg/runner/run_context.go) — job state (env, matrix, containers, expressions)
5. Steps (pkg/runner/step.go) — action, docker, and script steps implement the step interface

The Executor type (pkg/common/executor.go) is func(ctx context.Context) error. Chain with .Then(), .Finally(), and .OnError(). NewPipelineExecutor is serial, NewParallelExecutor is parallel, and .If() / .IfNot() are conditional.

Packages:

• pkg/model/ — workflow YAML, plan creation, action definitions
• pkg/runner/ — execution engine, expression evaluation, local/remote/docker/composite actions, reusable workflows
• pkg/container/ — Docker API wrapper, plus container and host execution environments. docker_stub.go is built with -tags WITHOUT_DOCKER (or on unsupported OSes) and must use the standard library errors package.
• pkg/common/ — executor pattern, context helpers, logging
• pkg/exprparser/ — the GitHub Actions ${{ }} language
• pkg/artifacts/ and pkg/artifactcache/ — artifact upload/download and the cache server

Linting

Configured in .golangci.yml:

• Use errors from the standard library, not github.com/pkg/errors
• Use github.com/sirupsen/logrus (alias log), not the standard library log
• Use github.com/stretchr/testify in tests, not gotest.tools/v3
• Max cyclomatic complexity is 20
• Import aliases: logrus → log, testify/assert → assert

Testing and testdata

Tests use testify/assert and testify/mock. Table-driven tests are the norm in pkg/model/ and pkg/exprparser/.

Fixtures live in a testdata/ directory next to the package that reads them. pkg/runner/testdata/<name>/ is one workflow (usually push.yml or an event file) plus any local actions. Integration tests register those directories in the tables in pkg/runner/runner_test.go. Edit the YAML and the expected error string in the table. There is no golden-file or snapshot updater for these fixtures.

testing.Short() skips the Docker-backed runner suites (TestRunEvent and the other event runners in runner_test.go), TestJobExecutor cases that start a job container, pkg/artifacts TestArtifactFlow, the cmd workflow runs (TestRun, TestRunPush, TestRunPushJsonLogger, and the bug-report flag), and the container tests that need a daemon or a default Docker socket (TestDocker, TestImageExistsLocally, TestGetSocketAndHostOnlySocket, TestGetSocketAndHostNoHostNoSocket). make test-fast passes -short so those tests do not run.

pkg/runner/testdata/**/node_modules and generated *.pb.go files are local noise. .cursorignore excludes them. pkg/artifacts/artifact.pb.go was generated by protoc-gen-go v1.32.0 (protoc v4.25.2). The .proto source is not in this repo; do not hand-edit the generated file.

Release binaries, not test fixtures, are what make snapshot rebuilds. The CI snapshot job runs goreleaser release --snapshot --clean.

Docker

make test and the runner integration tests need a working Docker daemon. Multi-arch cases also need binfmt registered:

docker run --privileged --rm tonistiigi/binfmt --install amd64,arm64

make test-fast, go build ./..., go vet ./..., and golangci-lint run do not need Docker. A build without the Docker client uses go build -tags WITHOUT_DOCKER.

CI

.github/workflows/checks.yml and codespell.yml cancel superseded runs on the same ref. Jobs set timeout-minutes. gotestsum is pinned (not @latest). On a pull request that only changes docs (Markdown, images, docs/, license, issue templates), test-linux, test-host, and snapshot skip the heavy steps and still report success so required checks are unchanged. macOS and Windows host tests still run when code changes.

Agent environment

.cursor/environment.json builds an image with the Go version from go.mod, golangci-lint v2.11.4 (matching CI), and Node.js with npm so make pr can run npx.