prein / actions-runner-controller

Kubernetes controller for GitHub Actions self-hosted runners

Actions Runner Controller (ARC)

People

actions-runner-controller is an open-source project currently developed and maintained in collaboration with the GitHub Actions team, external maintainers @mumoshu and @toast-gear, various contributors, and the awesome community.

If you think the project is awesome and is adding value to your business, please consider directly sponsoring community maintainers and individual contributors via GitHub Sponsors.

In case you are already the employer of one of contributors, sponsoring via GitHub Sponsors might not be an option. Just support them in other means!

See the sponsorship dashboard for the former and the current sponsors.

Status

Even though actions-runner-controller is used in production environments, it is still in its early stage of development, hence versioned 0.x.

actions-runner-controller complies to Semantic Versioning 2.0.0 in which v0.x means that there could be backward-incompatible changes for every release.

The documentation is kept inline with master@HEAD, we do our best to highlight any features that require a specific ARC version or higher however this is not always easily done due to there being many moving parts. Additionally, we actively do not retain compatibly with every GitHub Enterprise Server version nor every Kubernetes version so you will need to ensure you stay current within a reasonable timespan.

About

GitHub Actions is a very useful tool for automating development. GitHub Actions jobs are run in the cloud by default, but you may want to run your jobs in your environment. Self-hosted runner can be used for such use cases, but requires the provisioning and configuration of a virtual machine instance. Instead if you already have a Kubernetes cluster, it makes more sense to run the self-hosted runner on top of it.

actions-runner-controller makes that possible. Just create a Runner resource on your Kubernetes, and it will run and operate the self-hosted runner for the specified repository. Combined with Kubernetes RBAC, you can also build simple Self-hosted runners as a Service.

Getting Started

To give ARC a try with just a handful of commands, Please refer to the Quickstart guide.

For an overview of ARC, please refer to About ARC

For more information, please refer to detailed documentation below!

Documentation

• Quickstart guide
• About ARC
• Installing ARC
• Authenticating to the GitHub API
• Deploying ARC runners
• Adding ARC runners to a repository, organization, or enterprise
• Automatically scaling runners
• Using custom volumes
• Using ARC runners in a workflow
• Managing access with runner groups
• Configuring Windows runners
• Using ARC across organizations
• Using entrypoint features
• Deploying alternative runners
• Monitoring and troubleshooting

Contributing

We welcome contributions from the community. For more details on contributing to the project (including requirements), please refer to "Getting Started with Contributing."

Troubleshooting

We are very happy to help you with any issues you have. Please refer to the "Troubleshooting" section for common issues.