GitHub Actions act for coding agents

When a coding agent edits a repository, it can use act to inspect and run GitHub Actions workflows on the developer’s machine. GitHub Actions workflows are YAML files that define automated jobs, such as linting or testing. act runs those jobs locally in Docker containers, so an agent can check workflow changes before anyone commits or pushes them.

A local run does not guarantee the same result as a GitHub-hosted runner. Use act to catch issues early, then rely on GitHub Actions for the final result. The commands below show how to list jobs, preview a selected job, and decide whether to run it.

Set up act

Install Docker or another compatible container runtime. Then follow the official installation instructions for your operating system. On macOS with Homebrew, the repository documents:

brew install act

Run act from the repository root, where it can find the .github/workflows directory. It uses the container runtime to run workflow steps, so Docker must be available when you execute a job.

List and preview a workflow

Suppose the repository has a workflow at .github/workflows/ci.yml. First, ask act to list its jobs:

act -l -W .github/workflows/ci.yml

Here, -l lists jobs and -W selects the workflow file. Review the listed job IDs, then preview the job you want to check:

act -n -W .github/workflows/ci.yml -j lint

-n requests a dry run, which prints the actions act would run without executing them. lint is an example job ID; replace it with an ID from the listing. The official usage guide explains workflow and job selection. The CLI source defines -n as a dry run that skips container creation.

The preview helps an agent confirm which job act selected. It does not execute the job’s commands or prove they will pass. Act still reads options from .actrc and local environment and secret files, so check those when using a checkout you do not know.

To execute the selected job, remove -n:

act -W .github/workflows/ci.yml -j lint

That command runs workflow steps in containers. Steps can download dependencies or actions, connect to external services, and write files in the checkout. If a workflow includes deployment or publishing steps, running it can also change a remote service. Inspect the job and its referenced actions before asking an agent to execute it.

Handle credentials outside the prompt

act does not automatically supply every GitHub secret that a workflow expects. A secret is a value such as a token or password that a workflow reads without storing it in the workflow file. If a job needs secrets, act supports supplying them through command-line options or a secrets file; see the documented secret and environment-file options.

Keep credentials out of the agent’s prompt and avoid committing a secrets file. Give act only the secrets the job needs, and check whether the job connects to GitHub or another service. A job that does not need credentials should run without them.

Give the agent a bounded task

A coding agent can inspect the workflow, find the job ID, and run the listing and preview commands. For example:

Inspect .github/workflows/ci.yml and identify the job that runs lint checks. Run act -l -W .github/workflows/ci.yml, then preview that job with act -n -W .github/workflows/ci.yml -j JOB_ID. Do not execute the job or use secrets. Report the job ID and any actions the preview shows.

Replace JOB_ID with the ID from act’s listing. If the preview looks appropriate, a developer can separately approve running the job without -n. This keeps the initial check local and avoids treating a preview as proof of a passing test.

Know what local runs miss

Act runs jobs in a different environment from GitHub’s hosted runners. A job can depend on tools, runner images or event data that your local setup does not provide. Check the project’s unsupported functionality and runner documentation before relying on a local result.

Use the preview to inspect job selection, then use a local run to catch errors in supported workflows. Keep the hosted GitHub Actions result as the check for the environment where your CI actually runs.