gh-agent

View documentation for the original command

$ tldr gh agent-task

gh-agent [options]

config
    Registers and configures the self-hosted runner with GitHub.
Common options include --url (GitHub URL), --token (registration token), --name (runner name), and --labels (custom labels).

run
    Starts the runner to actively listen for and execute GitHub Actions jobs.
The --once option can be used to execute a single job and then exit.

remove
    Unregisters and removes the self-hosted runner from GitHub.
Requires --url and a Personal Access Token (PAT) or runner token (--token) for authentication.

service
    Manages the runner as a background system service (e.g., systemd on Linux).
Subcommands like install, uninstall, start, stop, and status are used to control the service lifecycle.

The gh-agent command (representing the GitHub Actions self-hosted runner application) is the core executable responsible for enabling and managing a self-hosted runner on a user's infrastructure. It allows users to register, configure, run, and remove a runner machine, connecting it to a GitHub repository or organization. This agent polls GitHub for new jobs, executes them in its local environment, and reports the status back to GitHub.

By using gh-agent, organizations can utilize their own hardware and custom environments for executing CI/CD workflows, providing more control over compute resources, security, and specific software requirements than GitHub-hosted runners. It's typically deployed on Linux, Windows, or macOS machines and requires proper authentication and configuration to interact with GitHub.

Security Risks: Self-hosted runners execute potentially untrusted code on your infrastructure, requiring careful security measures.
Maintenance Overhead: Users are responsible for updating the runner application, OS, and dependencies.
Resource Management: Adequate compute, memory, and storage must be provisioned for job execution.
Network Access: Requires outbound access to GitHub.com and potentially other services.

The gh-agent (runner application) is typically downloaded as a compressed archive from GitHub, extracted into a directory, and then configured. This usually involves using commands like curl to download the archive and tar to decompress it, followed by executing the config subcommand.

Given that self-hosted runners execute code directly on your infrastructure, it is paramount to follow security best practices. This includes isolating the runner machine, using dedicated service accounts with minimal permissions, regularly auditing access, and ensuring that only trusted workflows are allowed to run on these agents. Avoid exposing sensitive environment variables unnecessarily.

By default, the gh-agent is configured to automatically update itself to the latest version. This ensures that runners benefit from the newest features, bug fixes, and security patches without manual intervention. However, this behavior can be optionally disabled during configuration (with --disableupdate) or when running the agent (with --no-autoupdate) for environments requiring strict version control.

The concept of self-hosted runners emerged as GitHub Actions gained popularity, allowing organizations to extend their CI/CD capabilities beyond GitHub-provided virtual machines. While GitHub Actions was introduced in 2018 with hosted runners, the need for custom environments, stringent security compliance, and cost optimization drove the development and introduction of self-hosted runners. The gh-agent application has since evolved, integrating features like automatic updates and robust service management to cater to enterprise-level CI/CD requirements.

systemctl(1), curl(1), docker(1)