github-act-runner

The runner's capabilities depend on the environment and the type of GitHub Action being executed:

Shell Requirements

• Composite/Run steps: Uses bash (preferred), sh, or an explicit shell in your PATH. On Windows, pwsh (preferred) and powershell are the defaults.
• Inside Docker containers: Uses sh or an explicit shell in the container's PATH.

NodeJS Requirements

• For compatibility with existing Node.js actions, ensure Node.js version 20 is in your PATH before running the runner. Newer versions may cause workflow failures.

Docker Requirements

• To use Docker actions or service containers, a reachable Docker daemon must be available. You can specify a remote host using the DOCKER_HOST environment variable.

To install github-act-runner on Debian-based systems, add the repository to your sources list, import the public key, and install via apt.

1. Add the repository: Create /etc/apt/sources.list.d/github-act-runner.list with the following content: deb https://gagis.hopto.org/repo/chrishx/deb all main

2. Import the public key: curl -sS https://gagis.hopto.org/repo/chrishx/pubkey.gpg | sudo tee -a /etc/apt/trusted.gpg.d/chrishx-github-act-runner.asc

3. Install: sudo apt update && sudo apt install github-act-runner

# Add repository
echo "deb https://gagis.hopto.org/repo/chrishx/deb all main" | sudo tee /etc/apt/sources.list.d/github-act-runner.list

# Import key
curl -sS https://gagis.hopto.org/repo/chrishx/pubkey.gpg | sudo tee -a /etc/apt/trusted.gpg.d/chrishx-github-act-runner.asc

# Install
sudo apt update
sudo apt install github-act-runner

If you prefer to run from source, you need Go 1.24 (as of v0.11.0) installed.

1. Clone the repository: git clone https://github.com/ChristopherHX/github-act-runner.git --recursive

2. Configure the runner: Use go run . configure to set up the registration. You must provide the GitHub URL, a name, and the registration token.

3. Run the runner: go run . run

# Clone
git clone https://github.com/ChristopherHX/github-act-runner.git --recursive

# Configure
go run . configure --url <github-repo-or-org-or-enterprise> --name <name> -l label1,label2 --token <token>

# Run
go run . run

Instead of relying on persistent files like settings.json, agent.json, and auth.json, you can provide a single jitconfig string to the run command. This is ideal for containerized or ephemeral environments where you want to pass all configuration via a single environment variable or CLI flag.

# Example: Running with a JIT configuration string
./github-act-runner run --jitconfig "<JSON_CONFIG_STRING>"

On platforms that are incompatible with interactive CLI surveys (specifically non-Linux, non-Darwin, non-Windows, and non-BSD systems), the runner uses fallback functions to prevent execution failure. These functions bypass interactive input by logging a warning and returning default values or the full set of available options.

Key fallback behaviors:

• RunnerGroupSurvey: Returns the provided taskAgentPool string instead of prompting for a selection.
• GetInput: Returns the provided answer string instead of prompting for user input.
• GetMultiSelectInput: Returns the entire options slice instead of prompting for a selection.

While highly compatible, this runner has several limitations compared to the official actions/runner:

• Annotations & Problem Matchers: Not implemented.
• Secret Masking: May leak more secrets than the official runner.
• Job Outputs: Sent regardless of whether they contain secret data.
• Expressions: Expressions in with and env keys (or directly assigned to mapping expressions) are not implemented.
• Node.js: You must provide the node program yourself in all container/host configurations.
• Updates: You must manually update the runner.
• Other: Step summaries (partially implemented in 0.13.1), annotations, and problem matchers are currently unsupported.

Once installed, use the new command to register the runner with GitHub and start it as a background service. You will need a registration token from your GitHub repository, organization, or enterprise settings.

Arguments:

• --url: The GitHub repository, organization, or enterprise URL (e.g., https://github.com/user/repo).
• --name: The name you want to assign to this runner.
• --labels: A comma-separated list of labels (e.g., label1,label2). This is optional.
• --token: The runner registration token obtained from GitHub settings.

github-act-runner new --url <url> --name <runner-name> --labels <labels> --token <runner-registration-token>

Use RunnerGroupSurvey to provide an interactive CLI selection for choosing a runner group from a provided list. If the user interaction fails, it returns the taskAgentPool value passed as the initial taskAgentPool argument.

// taskAgentPool is the default value returned on error
// taskAgentPools is the list of available options
selectedGroup := RunnerGroupSurvey(defaultGroup, availableGroups)

Use GetInput to prompt the user for a single string input. It accepts a prompt message and a default answer. If the user interaction fails, the function returns the provided default answer.

// prompt: the message shown to the user
// answer: the default value to return if input fails
result := GetInput("Enter runner name: ", "my-runner")

Use GetMultiSelectInput to allow a user to select one or more options from a list. It returns a slice of strings containing the selected options. If the interaction fails, it returns an empty slice and prints an error message listing all available options.

options := []string{"option1", "option2", "option3"}
selected := GetMultiSelectInput("Select features: ", options)

Use the remove command to unregister the runner from GitHub and clean up local configuration files.

Key flags:

• --url: Required if unconfiguring version <= 0.0.3.
• --token: The runner registration or removal token.
• --pat: A personal access token.
• --name: The name of the runner to remove.
• --force: Force removal even if the service responds with an error.
• --local: Only delete the local configuration files without notifying GitHub.

# Example: Remove a runner using a token
./github-act-runner remove --token YOUR_TOKEN --name my-runner

Use the run command to start the runner and begin listening for jobs. The runner will use the configuration stored in settings.json or a provided jitconfig.

Key flags:

• --once: Execute only one job and then exit (useful for ephemeral runners).
• --terminal: Allocate a PTY if possible (defaults to true).
• --trace: Trace HTTP communication with the GitHub Actions service.
• --worker-args: Pass custom arguments to the worker.
• --jitconfig: Read the runner configuration from a JIT configuration string instead of settings.json.

# Example: Run the runner once and enable tracing
./github-act-runner run --once --trace