Skip to main content
Version: 1.47

GitHub integration

The GitHub integration uses a GitHub App to give your developers access to private GitHub repositories. With it:

  • Your users select a repository from a list, instead of typing the full repository URL.
  • Everyone in your cluster gets read-only access to private repositories.
  • You control access to Okteto and to the repositories for the whole organization, or per repository.
  • Pipelines use an app-scoped token instead of a shared SSH key.

Configuration Steps​

Setting up the GitHub integration takes steps in GitHub and in your Okteto instance. In GitHub:

  1. Create the GitHub App
  2. Generate a private key for the GitHub App

In your Okteto instance:

  1. Add the GitHub App configuration to Okteto
  2. Verify your installation

Once you complete these steps, your Okteto instance authenticates with the GitHub App when it clones repositories in Okteto pipelines.

Creating the GitHub App​

  1. In the upper-right corner of any page in GitHub, select your profile icon > Organizations.
  2. Click the settings of the organization where you want to create the app.
  3. In the left navigation, select Developer settings > GitHub Apps.
  4. Select New GitHub App.
  5. Complete the following fields as follows:
  6. Uncheck the Expire user authorization tokens option.
  7. Check the Request user authorization (OAuth) during installation option.
  8. In the Post Installation section, check the Redirect on update option.
  9. In the Webhook section, uncheck the Active option.
  10. In the Repository permissions section, set the Contents permission to Read-only.
  11. In the Organization permissions section, set the Members permission to Read-only.
  12. In the Account permissions section, set the Email addresses permission to Read-only.
  13. In the Where can this GitHub App be installed? section, select the Any account option. This lets your users install the app in their own GitHub accounts and deploy their personal repositories in your Okteto instance.
  14. Click the Create GitHub App button.
  15. On the next screen, copy the App Id and Client Id values. You add them to your Okteto configuration in Adding the GitHub App Configuration to Okteto.

GitHub's developer guide covers creating a GitHub App in more detail.

Generating a private key for the GitHub App​

After you create the GitHub App, generate a client secret and a private key to authenticate to it:

  1. In the upper-right corner of any page in GitHub, select your profile icon > Organizations.
  2. Click the settings of the organization where you created the app.
  3. In the left navigation, select Developer settings > GitHub Apps.
  4. Select the GitHub App.
  5. In the Client secrets section, click the Generate a new client secret button. Copy the value and save it somewhere safe: GitHub doesn't display it again. You add it to your Okteto configuration in Adding the GitHub App Configuration to Okteto.
  6. In the Private keys section, at the bottom of the page, click the Generate a private key button. A file with the private key is saved to your computer.

Adding the GitHub App Configuration to Okteto​

Add the values you generated in GitHub to your Helm configuration file:

github:
enabled: true
appId: "${YOUR_APP_ID}"
clientId: ${YOUR_CLIENT_ID}
clientSecret: ${YOUR_CLIENT_SECRET}
installationUrl: https://github.com/apps/${YOUR_GITHUB_APP_NAME}/installations/new
appPrivateKey: |
-----BEGIN RSA PRIVATE KEY-----
......
.....
-----END RSA PRIVATE KEY-----

You can also store the clientSecret and the appPrivateKey in a secret.

  • appId, clientId, and clientSecret are the values of the GitHub App you created.
  • appPrivateKey is the private key you generated.

If you use GitHub as your authentication provider, you can also use your GitHub App's appId and clientId values in the auth.github section of your Helm configuration file.

After you update your Helm configuration file, run the following command to reconfigure your Okteto instance:

helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto

For a new installation, run the following command instead:

helm install okteto okteto/okteto -f config.yaml --namespace=okteto

Verifying your installation​

If the installation succeeded, the Deploy Dev Environment dialog shows a GitHub tab.

The Deploy Dev Environment dialog with the GitHub tab selected and a list of repositories

When you select it, you see the repositories that your GitHub App can access. From private repositories explains how to deploy a private repository.