act

List the available jobs

$ act [[-l|--list]]

$ act

$ act [event_type]

$ act [[-j|--job]] [job_id]

$ act [[-n|--dryrun]]

$ act [[-v|--verbose]]

$ act push [[-W|--workflows]] [path/to/workflow]

act [OPTIONS] [event]

--workflows, -W <path>
    Specify the path to the workflow file(s) or directory containing workflows.

--job, -j <job_name>
    Run only a specific job from the workflow.

--event, -e <event_type>
    Define the GitHub event type to trigger the workflow with (e.g., push, pull_request).

--input, -i <name=value>
    Pass an input to the workflow, typically used with workflow_dispatch events. Can be specified multiple times.

--secret, -s <name=value>
    Provide a secret to the workflow. Can be specified multiple times.

--secret-file, -sf <file_path>
    Path to a file containing secrets (e.g., an .env file).

--env, -E <name=value>
    Set an environment variable for the workflow execution. Can be specified multiple times.

--container-architecture <arch>
    Specify the architecture of the container to use (e.g., linux/amd64, linux/arm64).

--bind, -b
    Bind the current directory to the container, making it accessible inside the workflow.

--dryrun, -n
    Perform a dry run: parse and print the workflow without executing any actions.

--list, -l
    List all available jobs within the specified workflow file(s).

--privileged
    Run job containers in privileged mode, granting broader access to the host.

--verbose
    Enable verbose logging to display more detailed information during execution.

--quiet
    Suppress most output, showing only errors or critical messages.

--artifact-server-port <port>
    Specify the port for the local artifact server, used for uploading/downloading artifacts.

--artifact-server-path <path>
    Set the directory where artifacts will be stored locally.

--rebuild
    Force a rebuild of Docker images before running the workflow.

--rm
    Remove containers after the job completes, cleaning up resources.

--help, -h
    Display the help message and exit.

The act command, while not a standard core Linux utility, is a popular open-source tool that allows developers to run their GitHub Actions workflows directly on their local machine. It simulates the GitHub Actions environment by leveraging Docker containers to execute jobs and steps defined in your workflow files (typically located in .github/workflows/).

This capability significantly speeds up the development and debugging process for GitHub Actions workflows. Instead of pushing changes to a remote repository and waiting for GitHub's cloud runners, developers can test iterations almost instantly. act supports various GitHub events like push, pull_request, and workflow_dispatch, and can handle inputs, secrets, and environment variables, providing a comprehensive local testing environment. It's an indispensable tool for anyone building complex CI/CD pipelines with GitHub Actions.

Docker Requirement: act fundamentally relies on Docker to create and manage containers for workflow execution. Docker must be installed and running on the host system.

Environment Parity: While act aims for high fidelity, it may not perfectly replicate all nuances of GitHub's cloud-hosted runners (e.g., pre-installed tools, specific runner configurations, network conditions).

Security Concerns: Running untrusted workflows locally, especially with --privileged mode, can pose security risks. Always be cautious when executing code from external sources.

Resource Usage: Local execution can consume significant CPU, memory, and disk resources, especially for large workflows or those involving heavy builds.

act can be installed through various methods depending on your operating system. Common approaches include using package managers like Homebrew (macOS), Scoop (Windows), or downloading pre-compiled binaries directly from the project's GitHub releases page. Alternatively, it can be built from source using Go.

To use act, navigate to the root directory of your Git repository where your .github/workflows directory resides. You can then run act with specific options, for example, act -j "build" to run a job named 'build', or act --event push to simulate a push event triggering your workflow. It's often preceded by git checkout to ensure you are testing the desired branch or commit.

act was developed by Nektos (a GitHub organization) as an open-source project to address the growing demand for local development and debugging of GitHub Actions workflows. It emerged as a crucial tool for developers to accelerate their CI/CD pipeline iteration cycles, eliminating the need to push changes to GitHub for every test run. Its development reflects the broader trend of shifting left in testing practices, bringing the execution environment closer to the developer's machine.

docker(1): Underlying containerization technology used by act., git(1): Version control system commonly used with GitHub and GitHub Actions.