Authenticating with a GitHub Application

You can configure your Okteto Enterprise instance to use a GitHub Application to authenticate your users as well as give them access to private GitHub repositories.

There are several reasons for considering this approach including:

• Your users can select a repo from a list, instead of having to type the full repository URL.
• Give everyone on your cluster read-only access to private repositories.
• Control access to Okteto and the repositories at the Organization level, or per repository.
• The pipelines use an app-scoped token, instead of a shared user.

Setting up a GitHub Application requires several steps in both GitHub and your Okteto Enterprise instance. Complete the following steps in GitHub:

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

Then, complete the following steps in your Okteto Enterprise instance:

1. Add the GitHub App information to your Helm configuration file
2. Reconfigure your Okteto Enterprise instance
3. Add or Remove private repositories
4. Verify your installation

Once this configuration has been completed, your Okteto Enterprise instance will use the GitHub Application you authenticate during the clone repository step of any Okteto pipelines.

Creating the GitHub App

1. In the upper-right corner of any page in GitHub, select your profile icon > Organizations.
2. Click on the settings of the organization you want to use to create the application.
3. In the left navigation, select Developer settings > GitHub Apps.
4. Select New GitHub App.
5. Complete the following fields as follows:
   • GitHub App Name: enter an appropriate name for your application (e.g. okteto-$YOUR_GITHUB_ORGANIZATION)
   • Homepage URL: https://okteto.$SUBDOMAIN
   • Callback URL: https://okteto.$SUBDOMAIN
6. Uncheck the Expire user authorization tokens option.
7. Check the Request user authorization (OAuth) during installation option.
8. On the Post Installation section, check the Redirect on update option.
9. On the Webhook section, uncheck the Active option.
10. On the Repository permissions section, set the Contents permission to Read-only.
11. On the Organization permissions section, set the Members permission to Read-only.
12. On the User permissions section, set the Email addresses permission to Read-only.
13. On the Where can this GitHub App be installed? section, select the Any account option. This will allow your users to install the application in their own GitHub account and deploy personal repositories in your Okteto Enterprise instance.
14. Press the Create GitHub App button.
15. On the next screen, copy the values of App Id and Client Id, you'll need to pass those to your Okteto Enterprise instance in a future step.

See Creating a GitHub App for more information on creating a GitHub App from GitHub’s Developer guide.

Generating a private key for the GitHub App

After you have created the GitHub App, you will need to generate a private key for authenticating to the GitHub App.

To generate a private key authenticating to the GitHub App:

1. In the upper-right corner of any page in GitHub, select your profile icon > Organizations.
2. Click on the settings of the organization you want to use to create the application.
3. In the left navigation, select Developer settings > GitHub Apps.
4. Select the GitHub App.
5. On the Client secrets section, press the Generate a new client secret button. Copy the value and save it in a safe place, since it won't be displayed again. You'll need to pass those to your Okteto Enterprise instance in a future step.
6. On the Private keys section (it's at the bottom of the page), press the Generate a private key button. A file with the private key will be saved in your computer.

Adding the GitHub App information to your Helm configuration file

Add the values we generated in the previous steps to your existing 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-----

clientID and clientSecret refers to the values of the GitHub App you just created.

appPrivateKey is the private key you generated.

You can also use the appId and clientId values of your GitHub application in the auth.github section of your Helm configuration file if you're using GitHub as your authentication provider.

Reconfiguring your Okteto Enterprise instance

Once you have updated your Helm configuration file, run the following command to reconfigure your Okteto Enterprise instance:

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

If you're doing this as part of a fresh install, then run the following command:

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

Adding or removing private repositories

You can update or revoke the permissions over your private repositories or organizations by going to the Integrations tab in the Settings page of your Okteto Enterprise instance.

Click on the Configure GitHub button to add or remove repositories. This will open a configuration dialog from GitHub. From there, you'll be able to add or remove repositories from any organization you belong to.

If you select repositories from a different organization (or user account) than the one you used to create the GitHub Application, GitHub will prompt you to install the application in the GitHub organization. Only organization administrators can complete this action.

Verifying your installation

If the installation was successful, you should now see a GitHub option in the Deploy from Git dialog.

When you click on it, you should see the list of repositories that you added in the previous step. This document has further information on how to deploy a private repository.