|
1 | | - |
2 | 1 | # Actions Runner Controller (ARC) |
3 | 2 |
|
4 | 3 | [](https://bestpractices.coreinfrastructure.org/projects/6061) |
5 | 4 | [](https://github.com/jonico/awesome-runners) |
6 | 5 | [](https://artifacthub.io/packages/search?repo=actions-runner-controller) |
7 | 6 |
|
8 | | -GitHub Actions automates the deployment of code to different environments, including production. The environments contain the `GitHub Runner` software which executes the automation. `GitHub Runner` can be run in GitHub-hosted cloud or self-hosted environments. Self-hosted environments offer more control of hardware, operating system, and software tools. They can be run on physical machines, virtual machines, or in a container. Containerized environments are lightweight, loosely coupled, highly efficient and can be managed centrally. However, they are not straightforward to use. |
9 | | - |
10 | | -`Actions Runner Controller (ARC)` makes it simpler to run self hosted environments on Kubernetes(K8s) cluster. |
11 | | - |
12 | | -With ARC you can : |
13 | | - |
14 | | -- **Deploy self hosted runners on Kubernetes cluster** with a simple set of commands. |
15 | | -- **Auto scale runners** based on demand. |
16 | | -- **Setup across GitHub editions** including GitHub Enterprise editions and GitHub Enterprise Cloud. |
17 | | - |
18 | | -## Overview |
19 | | - |
20 | | -For an overview of ARC, please refer to "[ARC Overview](https://github.com/actions/actions-runner-controller/blob/master/docs/Actions-Runner-Controller-Overview.md)." |
21 | | - |
22 | | - |
23 | | - |
24 | | -## Getting Started |
25 | | - |
26 | | -ARC can be setup with just a few steps. |
27 | | - |
28 | | -In this section we will setup prerequisites, deploy ARC into a K8s cluster, and then run GitHub Action workflows on that cluster. |
29 | | - |
30 | | -### Prerequisites |
31 | | - |
32 | | -<details><summary><sub>Create a K8s cluster, if not available.</sub></summary> |
33 | | - <sub> |
34 | | -If you don't have a K8s cluster, you can install a local environment using minikube. For more information, see <a href="https://minikube.sigs.k8s.io/docs/start/">"Installing minikube."</a> |
35 | | - </sub> |
36 | | -</details> |
37 | | - |
38 | | -:one: Install cert-manager in your cluster. For more information, see "[cert-manager](https://cert-manager.io/docs/installation/)." |
39 | | - |
40 | | -```shell |
41 | | -kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.8.2/cert-manager.yaml |
42 | | -``` |
43 | | - |
44 | | -<sub> *note:- This command uses v1.8.2. Please replace with a later version, if available.</sub> |
45 | | - |
46 | | ->You may also install cert-manager using Helm. For instructions, see "[Installing with Helm](https://cert-manager.io/docs/installation/helm/#installing-with-helm)." |
47 | | -
|
48 | | -:two: Next, Generate a Personal Access Token (PAT) for ARC to authenticate with GitHub. |
| 7 | +## People |
49 | 8 |
|
50 | | -- Login to your GitHub account and Navigate to "[Create new Token](https://github.com/settings/tokens/new)." |
51 | | -- Select **repo**. |
52 | | -- Click **Generate Token** and then copy the token locally ( we’ll need it later). |
| 9 | +`actions-runner-controller` is an open-source project currently developed and maintained in collaboration with maintainers @mumoshu and @toast-gear, various [contributors](https://github.com/actions/actions-runner-controller/graphs/contributors), and the [awesome community](https://github.com/actions/actions-runner-controller/discussions), mostly in their spare time. |
53 | 10 |
|
54 | | -### Deploy and Configure ARC |
| 11 | +If you think the project is awesome and it's becoming a basis for your important business, consider [sponsoring us](https://github.com/sponsors/actions-runner-controller)! |
55 | 12 |
|
56 | | -1️⃣ Deploy and configure ARC on your K8s cluster. You may use Helm or Kubectl. |
| 13 | +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! |
57 | 14 |
|
58 | | -<details><summary>Helm deployment</summary> |
| 15 | +We don't currently have [any sponsors dedicated to this project yet](https://github.com/sponsors/actions-runner-controller). |
59 | 16 |
|
60 | | -##### Add repository |
| 17 | +However, [HelloFresh](https://www.hellofreshgroup.com/en/) has recently started sponsoring @mumoshu for this project along with his other works. A part of their sponsorship will enable @mumoshu to add an E2E test to keep ARC even more reliable on AWS. Thank you for your sponsorship! |
61 | 18 |
|
62 | | -```shell |
63 | | -helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller |
64 | | -``` |
| 19 | +[<img src="https://user-images.githubusercontent.com/22009/170898715-07f02941-35ec-418b-8cd4-251b422fa9ac.png" width="219" height="71" />](https://careers.hellofresh.com/) |
65 | 20 |
|
66 | | -##### Install Helm chart |
| 21 | +## Status |
67 | 22 |
|
68 | | -```shell |
69 | | -helm upgrade --install --namespace actions-runner-system --create-namespace\ |
70 | | - --set=authSecret.create=true\ |
71 | | - --set=authSecret.github_token="REPLACE_YOUR_TOKEN_HERE"\ |
72 | | - --wait actions-runner-controller actions/actions-runner-controller |
73 | | -``` |
| 23 | +Even though actions-runner-controller is used in production environments, it is still in its early stage of development, hence versioned 0.x. |
74 | 24 |
|
75 | | -<sub> *note:- Replace REPLACE_YOUR_TOKEN_HERE with your PAT that was generated previously. </sub> |
76 | | -</details> |
| 25 | +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. |
77 | 26 |
|
78 | | -<details><summary>Kubectl deployment</summary> |
| 27 | +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. |
79 | 28 |
|
80 | | -##### Deploy ARC |
| 29 | +## About |
81 | 30 |
|
82 | | -```shell |
83 | | -kubectl apply -f \ |
84 | | -https://github.com/actions/actions-runner-controller/\ |
85 | | -releases/download/v0.22.0/actions-runner-controller.yaml |
86 | | -``` |
| 31 | +[GitHub Actions](https://github.com/features/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](https://github.com/actions/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. |
87 | 32 |
|
88 | | -<sub> *note:- Replace "v0.22.0" with the version you wish to deploy </sub> |
| 33 | +**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. |
89 | 34 |
|
90 | | -##### Configure Personal Access Token |
91 | | - |
92 | | -```shell |
93 | | -kubectl create secret generic controller-manager \ |
94 | | - -n actions-runner-system \ |
95 | | - --from-literal=github_token=REPLACE_YOUR_TOKEN_HERE |
96 | | -```` |
97 | | - |
98 | | -<sub> *note:- Replace REPLACE_YOUR_TOKEN_HERE with your PAT that was generated previously.</sub> |
99 | | - |
100 | | - </details> |
101 | | - |
102 | | -2️⃣ Create the GitHub self hosted runners and configure to run against your repository. |
103 | | - |
104 | | -Create a `runnerdeployment.yaml` file and copy the following YAML contents into it: |
105 | | - |
106 | | -```yaml |
107 | | -apiVersion: actions.summerwind.dev/v1alpha1 |
108 | | -kind: RunnerDeployment |
109 | | -metadata: |
110 | | - name: example-runnerdeploy |
111 | | -spec: |
112 | | - replicas: 1 |
113 | | - template: |
114 | | - spec: |
115 | | - repository: mumoshu/actions-runner-controller-ci |
116 | | -```` |
117 | | -<sub> *note:- Replace "mumoshu/actions-runner-controller-ci" with your repository name. </sub> |
118 | | -
|
119 | | -Apply this file to your K8s cluster. |
120 | | -```shell |
121 | | -kubectl apply -f runnerdeployment.yaml |
122 | | -```` |
123 | | - |
124 | | -*🎉 We are done - now we should have self hosted runners running in K8s configured to your repository. 🎉* |
125 | | - |
126 | | -Next - lets verify our setup and execute some workflows. |
127 | | - |
128 | | -### Verify and Execute Workflows |
129 | | - |
130 | | -:one: Verify that your setup is successful: |
131 | | -```shell |
132 | | -
|
133 | | -$ kubectl get runners |
134 | | -NAME REPOSITORY STATUS |
135 | | -example-runnerdeploy2475h595fr mumoshu/actions-runner-controller-ci Running |
136 | | -
|
137 | | -$ kubectl get pods |
138 | | -NAME READY STATUS RESTARTS AGE |
139 | | -example-runnerdeploy2475ht2qbr 2/2 Running 0 1m |
140 | | -```` |
141 | | -
|
142 | | -Also, this runner has been registered directly to the specified repository, you can see it in repository settings. For more information, see "[Checking the status of a self-hosted runner - GitHub Docs](https://docs.github.com/en/actions/hosting-your-own-runners/monitoring-and-troubleshooting-self-hosted-runners#checking-the-status-of-a-self-hosted-runner)." |
143 | | -
|
144 | | -:two: You are ready to execute workflows against this self-hosted runner. For more information, see "[Using self-hosted runners in a workflow - GitHub Docs](https://docs.github.com/en/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow#using-self-hosted-runners-in-a-workflow)." |
145 | | -
|
146 | | -There is also a quick start guide to get started on Actions, For more information, please refer to "[Quick start Guide to GitHub Actions](https://docs.github.com/en/actions/quickstart)." |
147 | | -
|
148 | | -## Learn more |
149 | | -
|
150 | | -For more detailed documentation, please refer to "[Detailed Documentation](https://github.com/actions/actions-runner-controller/blob/master/docs/detailed-docs.md)." |
| 35 | +## Getting Started |
| 36 | +To give ARC a try with just a handful of commands, Please refer to the [Quickstart guide](/docs/quickstart.md). |
| 37 | + |
| 38 | +For an overview of ARC, please refer to [ARC Overview](https://github.com/actions/actions-runner-controller/blob/master/docs/Actions-Runner-Controller-Overview.md) |
| 39 | + |
| 40 | +For more information, please refer to detailed documentation below! |
| 41 | + |
| 42 | +## Documentation |
| 43 | + |
| 44 | +- [Quickstart guide](/docs/quickstart.md) |
| 45 | +- [About ARC](/docs/about-arc.md) |
| 46 | +- [Installing ARC](/docs/installing-arc.md) |
| 47 | +- [Authenticating to the GitHub API](/docs/authenticating-to-the-github-api.md) |
| 48 | +- [Deploying ARC runners](/docs/deploying-arc-runners.md) |
| 49 | +- [Adding ARC runners to a repository, organization, or enterprise](/docs/choosing-runner-destination.md) |
| 50 | +- [Automatically scaling runners](/docs/automatically-scaling-runners.md) |
| 51 | +- [Using custom volumes](/docs/using-custom-volumes.md) |
| 52 | +- [Using ARC runners in a workflow](/docs/using-arc-runners-in-a-workflow.md) |
| 53 | +- [Managing access with runner groups](/docs/managing-access-with-runner-groups.md) |
| 54 | +- [Configuring Windows runners](/docs/configuring-windows-runners.md) |
| 55 | +- [Using ARC across organizations](/docs/using-arc-across-organizations.md) |
| 56 | +- [Using entrypoint features](/docs/using-entrypoint-features.md) |
| 57 | +- [Deploying alternative runners](/docs/deploying-alternative-runners.md) |
| 58 | +- [Monitoring and troubleshooting](/docs/monitoring-and-troubleshooting.md) |
151 | 59 |
|
152 | 60 | ## Contributing |
153 | 61 |
|
|
0 commit comments