{"meta":{"title":"Authenticating ARC to the GitHub API","intro":"Authenticate Actions Runner Controller to the GitHub API.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/how-tos","title":"How-tos"},{"href":"/en/actions/how-tos/manage-runners","title":"Manage runners"},{"href":"/en/actions/how-tos/manage-runners/use-actions-runner-controller","title":"Actions Runner Controller"},{"href":"/en/actions/how-tos/manage-runners/use-actions-runner-controller/authenticate-to-the-api","title":"Authenticate to the API"}],"documentType":"article"},"body":"# Authenticating ARC to the GitHub API\n\nAuthenticate Actions Runner Controller to the GitHub API.\n\nYou can authenticate Actions Runner Controller (ARC) to the GitHub API by using a GitHub App or by using a personal access token (classic).\n\n> \\[!NOTE]\n> You cannot authenticate using a GitHub App for runners at the enterprise level. For more information, see [Managing access to self-hosted runners using groups](/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#about-runner-groups).\n\n## Authenticating ARC with a GitHub App\n\n1. Create a GitHub App that is owned by an organization. For more information, see [Registering a GitHub App](/en/apps/creating-github-apps/creating-github-apps/creating-a-github-app). Configure the GitHub App as follows.\n\n   1. For \"Homepage URL,\" enter `https://github.com/actions/actions-runner-controller`.\n\n   2. Under \"Permissions,\" click **Repository permissions**. Then use the dropdown menus to select the following access permissions.\n      * **Administration:** Read and write\n\n        > \\[!NOTE]\n        > `Administration: Read and write` is only required when configuring Actions Runner Controller to register at the repository scope. It is not required to register at the organization scope.\n\n      * **Metadata:** Read-only\n\n   3. Under \"Permissions,\" click **Organization permissions**. Then use the dropdown menus to select the following access permissions.\n      * **Self-hosted runners:** Read and write\n\n2. After creating the GitHub App, on the GitHub App's page, note the value for \"App ID\". You will use this value later.\n\n3. Under \"Private keys\", click **Generate a private key**, and save the `.pem` file. You will use this key later.\n\n4. In the menu at the top-left corner of the page, click **Install app**, and next to your organization, click **Install** to install the app on your organization.\n\n5. After confirming the installation permissions on your organization, note the app installation ID. You will use it later. You can find the app installation ID on the app installation page, which has the following URL format:\n\n   `https://github.com/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID`\n\n6. Register the app ID, installation ID, and the downloaded `.pem` private key file from the previous steps to Kubernetes as a secret.\n\n   To create a Kubernetes secret with the values of your GitHub App, run the following command.\n\n   > \\[!NOTE]\n   > Create the secret in the same namespace where the `gha-runner-scale-set` chart is installed. In this example, the namespace is `arc-runners` to match the quickstart documentation. For more information, see [Get started with Actions Runner Controller](/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller#configuring-a-runner-scale-set).\n\n   ```bash copy\n   kubectl create secret generic pre-defined-secret \\\n      --namespace=arc-runners \\\n      --from-literal=github_app_id=123456 \\\n      --from-literal=github_app_installation_id=654321 \\\n      --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'\n   ```\n\n   Then using the `githubConfigSecret` property in your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, pass the secret name as a reference.\n\n   ```yaml\n   githubConfigSecret: pre-defined-secret\n   ```\n\nFor additional Helm configuration options, see [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) in the ARC repository.\n\n## Authenticating ARC with a personal access token (classic)\n\nARC can use personal access tokens (classic) to register self-hosted runners.\n\n1. Create a personal access token (classic) with the required scopes. The required scopes are different depending on whether you are registering runners at the repository or organization level. For more information on how to create a personal access token (classic), see [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic).\n\n   The following is the list of required personal access token scopes for ARC runners.\n\n   * Repository runners: `repo`\n   * Organization runners: `admin:org`\n\n2. To create a Kubernetes secret with the value of your personal access token (classic), use the following command.\n\n   > \\[!NOTE]\n   > Create the secret in the same namespace where the `gha-runner-scale-set` chart is installed. In this example, the namespace is `arc-runners` to match the quickstart documentation. For more information, see [Get started with Actions Runner Controller](/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller#configuring-a-runner-scale-set).\n\n   ```bash copy\n   kubectl create secret generic pre-defined-secret \\\n      --namespace=arc-runners \\\n      --from-literal=github_token='YOUR-PAT'\n   ```\n\n3. In your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, pass the secret name as a reference.\n\n   ```yaml\n   githubConfigSecret: pre-defined-secret\n   ```\n\n   For additional Helm configuration options, see [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) in the ARC repository.\n\n## Authenticating ARC with a fine-grained personal access token\n\nARC can use fine-grained personal access tokens to register self-hosted runners.\n\n1. Create a fine-grained personal access token with the required scopes. The required scopes are different depending on whether you are registering runners at the repository or organization level. For more information on how to create a fine-grained personal access token, see [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token).\n\n   The following is the list of required personal access token scopes for ARC runners.\n\n   * Repository runners:\n     * **Administration:** Read and write\n\n   * Organization runners:\n     * **Administration:** Read\n     * **Self-hosted runners:** Read and write\n\n2. To create a Kubernetes secret with the value of your fine-grained personal access token, use the following command.\n\n   > \\[!NOTE]\n   > Create the secret in the same namespace where the `gha-runner-scale-set` chart is installed. In this example, the namespace is `arc-runners` to match the quickstart documentation. For more information, see [Get started with Actions Runner Controller](/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller#configuring-a-runner-scale-set).\n\n   ```bash copy\n   kubectl create secret generic pre-defined-secret \\\n      --namespace=arc-runners \\\n      --from-literal=github_token='YOUR-PAT'\n   ```\n\n3. In your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, pass the secret name as a reference.\n\n   ```yaml\n   githubConfigSecret: pre-defined-secret\n   ```\n\n   For additional Helm configuration options, see [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) in the ARC repository.\n\n## Authenticating ARC with vault secrets\n\n> \\[!NOTE]\n> Vault integration is currently available in public preview with support for Azure Key Vault.\n\nStarting with gha-runner-scale-set version 0.12.0, ARC supports retrieving GitHub credentials from an external vault. Vault integration is configured per runner scale set. This means you can run some scale sets using Kubernetes secrets while others use vault-based secrets, depending on your security and operational requirements.\n\n### Enabling Vault Integration\n\nTo enable vault integration for a runner scale set:\n\n1. **Set the `githubConfigSecret` field** in your `values.yaml` file to the name of the secret key stored in your vault. This value must be a string.\n2. **Uncomment and configure the `keyVault` section** in your `values.yaml` file with the appropriate provider and access details.\n3. **Provide the required certificate** (`.pfx`) to both the controller and the listener. You can do this by:\n   \\*Rebuilding the controller image with the certificate included, or\n   \\*Mounting the certificate as a volume in both the controller and the listener using the `listenerTemplate` and `controllerManager` fields.\n\n### Secret Format\n\nThe secret stored in Azure Key Vault must be in JSON format. The structure depends on the type of authentication you are using:\n\n#### Example: GitHub Token\n\n```json\n{\n  \"github_token\": \"TOKEN\"\n}\n```\n\n#### Example: GitHub App\n\n```json\n{\n  \"github_app_id\": \"APP_ID_OR_CLIENT_ID\",\n  \"github_app_installation_id\": \"INSTALLATION_ID\",\n  \"github_app_private_key\": \"PRIVATE_KEY\"\n}\n```\n\n### Configuring `values.yaml` for Vault Integration\n\nThe certificate is stored as a .pfx file and mounted to the container at /akv/cert.pfx. Below is an example of how to configure the keyVault section to use this certificate for authentication:\n\n```yaml\nkeyVault:\n  type: \"azure_key_vault\"\n  proxy:\n    https:\n      url: \"PROXY_URL\"\n      credentialSecretRef: \"PROXY_CREDENTIALS_SECRET_NAME\"\n    http: {}\n    noProxy: []\n  azureKeyVault:\n    clientId: <AZURE_CLIENT_ID>\n    tenantId: <AZURE_TENANT_ID>\n    url: <AZURE_VAULT_URL>\n    certificatePath: \"/akv/cert.pfx\"\n```\n\n### Providing the Certificate to the Controller and Listener\n\nARC requires a `.pfx` certificate to authenticate with the vault. This certificate must be made available to both the controller and the listener components during controller installation.\nYou can do this by mounting the certificate as a volume using the `controllerManager` and `listenerTemplate` fields in your `values.yaml` file:\n\n```yaml\nvolumes:\n  - name: cert-volume\n    secret:\n      secretName: my-cert-secret\nvolumeMounts:\n  - mountPath: /akv\n    name: cert-volume\n    readOnly: true\n\nlistenerTemplate:\n  volumeMounts:\n    - name: cert-volume\n      mountPath: /akv/certs\n      readOnly: true\n  volumes:\n    - name: cert-volume\n      secret:\n        secretName: my-cert-secret\n```\n\nThe code below is an example of a scale set `values.yml` file.\n\n```yaml\nlistenerTemplate:\n  spec:\n    containers:\n      - name: listener\n        volumeMounts:\n          - name: cert-volume\n            mountPath: /akv\n            readOnly: true\n    volumes:\n      - name: cert-volume\n        secret:\n          secretName: my-cert-secret\n```\n\n## Legal notice\n\nPortions have been adapted from <https://github.com/actions/actions-runner-controller/> under the Apache-2.0 license:\n\n```text\nCopyright 2019 Moto Ishizawa\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```"}