Github
In order to offer Github login, you will need to set up an OAuth application in Github that will authorize reading Github user data. To offer reading from/writing to Github repositories, you need to create a Github App in Github. In this guide, we assume you are setting up a Github integration for a Porter instance running on porter.example.com
. Let's get started!
Setting Up Github Login
Step 1: Github OAuth Application Creation
info
Note: you can view the most up-to-date instructions for creating a Github OAuth app in the Github documentation.
Navigate to your organization settings page (alternately, you can navigate to your personal settings page) and select Developer Settings in the sidebar. Go to OAuth Apps and select New OAuth App. You can fill it in with the following fields:
- Application name: Porter
- Homepage URL: https://getporter.dev
- Authorization callback URL:
https://<your-domain>/api/oauth/github/callback
The registration form should look something like this:
After creating the OAuth application, select "Generate a new client secret" and store the secret value somewhere. You will need this for the next step.
Step 2: Update Porter Environment Variables
Add the following Github credentials to your Porter instance:
GITHUB_CLIENT_ID=<your-github-client-id>
GITHUB_CLIENT_SECRET=<your-github-client-secret>
info
Note: if you ever want to enable Github login, you can set the environment variable GITHUB_LOGIN_ENABLED=false
.
Restart the Porter instance, and you will be given the option to log in with Github!
Setting Up Github Repository Integrations
Step 1: Github App Creation
Navigate to your organization settings page (alternately, you can navigate to your personal settings page) and select Developer Settings in the sidebar. Go to Github Apps and select New Github App. You should use the following settings:
- Callback URL:
<protocol>://<your-domain>/api/oauth/github-app/callback
- The Request user authorization (OAuth) during installation checkbox should be checked.
- Webhook URL:
<protocol>://<your-domain>/api/integrations/github-app/webhook
- Webhook secret: generate a random webhook secret for your domain, for example by running
cat /dev/urandom | base64 | head -c 32
. - Permissions:
- Repository Permissions:
Actions
:Read and Write
- Contents: Read and Write
- Metadata: Read-Only
- Secrets: Read and Write
- Workflows: Read and Write
- Organization Permissions:
- Members: Read-Only
- User Permissions:
- Email Addresses: Read-Only
- Repository Permissions:
Step 2: Downloading a Private Key
After creating the Github App, generate a new private key for your app. Put this private key either somewhere in your filesystem, or mount it into the container if using Kubernetes or Swarm to deploy.
Step 3: Update Porter Environment Variables
Add the following Github credentials to your Porter instance:
GITHUB_APP_CLIENT_ID=<github-app-id>
GITHUB_APP_CLIENT_SECRET=<github-secret>
GITHUB_APP_WEBHOOK_SECRET=<webhook-secret>
GITHUB_APP_NAME=<github-app-name>
GITHUB_APP_ID=<github-app-id>
GITHUB_APP_SECRET_PATH=<path-to-secret>
Troubleshooting
Checking Github App Credentials
Make sure that all of the credentials and config values you're passing in to the Porter instance match those in the Github app's settings.
Webhook Failures
If your Github app is connected properly and is showing the correct accounts on the Porter dashboard, but the repos aren't displaying on the Porter dashboard, you can check that the webhooks have been delivered properly from the Advanced tab of the Github app's settings. From there, you can view recent webhook deliveries and ensure that they were delivered successfully. If they were not delivered successfully, you can redeliver them or debug the request from this tab.
Deleting and Reinstalling
If you've migrated the Porter instance to use a new database, or the Github app is otherwise not working, you can try to delete the Github app from your repositories and reinstall it. You must do this by navigating to the installation in each account that the Github app is installed. For organizations, you will be able to uninstall the Github app from Settings > Github App in your organization view on Github. For personal accounts, you can uninstall the Github app from Settings > Applications in your personal settings view.