Self-hosted GitHub integration

Local deployment

You will need to create a GitHub app to self-host a GitHub integration.

1. Follow steps 1 to 7 in GitHub's docs on creating an app.
2. Add your callback URL: https://localhost/integrations?source=github.
3. Un-toggle the expiration of user tokens, and toggle Request user authorization (OAuth) during installation.

4. Set up the repository permissions. Allow Read Only access to:

• Repository Permissions:
  • Contents
  • Discussions
  • Issues
  • Metadata
  • Pull Requests
• Organisation permissions:
  • Events
  • Members
  • Projects
• User permissions:
  • Email addresses
  • Followers
  • Starring
  • Watching

5. Click on Create GitHub app at the bottom of the page.
6. Set up environment variables in backend/.env.override.local:

• App ID -> CROWD_GITHUB_APP_ID
• Client ID -> CROWD_GITHUB_CLIENT_ID
• Generate a client secret -> CROWD_GITHUB_CLIENT_SECRET

7. Get the private key to the environment:

• Generate a private key

• Convert it into a base64 encoded one-liner using https://www.base64encode.org/ or with a bash command cat key.pem | base64 -w 0:

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA4+dAC4eHchsLra6dUtFbZSHpAD9iaQxXTfc+CpBTumvY7klf
CE4Q6M+VQ86WLusiBPV/p20QDcQIshht69sRdBxWJyGEK6thoKHMU+MD48TdMaQj
...

LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUcvQUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQnVZd2dnYmlBZ0VBQW9JQmdRREYvKysxdzgwREEwUU4KWkZnQisveVFIY1MxdkRyQ2svdmY5ZnV1QXZLb3BnYWZyOHQ1NnJWVlR4SUpiZ2ZIaVh1cC9qUWJwRzRyM1Y5ZQp4N2NjSzN4Sjgyd...

• Add it to the environment in backend/.env.override.local -> CROWD_GITHUB_PRIVATE_KEY

Your app is not set up! Now you can set up your GitHub integration through your deployment of crowd.dev! For more information on how to set up the integration, see GitHub integration.

📘

Webhooks in local

We currently do not have good support for GitHub webhooks in our local environment. When deploying integrations locally, it will give you a GitHub URL. You can use this temporarily (see the next section on how to set up webhooks). However, when you restart your local environment the URL will change.

8. Add the GitHub installation URL to the frontend environment variables in frontend/.env.override.local:

• VUE_APP_GITHUB_INSTALLATION_URL="https://github.com/apps/{your-app-name}/installations/new"

Production app

To have a production GitHub app, you must create a new one and repeat all the steps. The difference is that the redirect URL will instead be your production URL, and the environment variables will be copied to your .env.prod. When deploying to production, you can also set up webhooks.

Setting up webhooks

1. Set a random, long string to the CROWD_GITHUB_WEBHOOK_SECRET environment variable.
2. Re-deploy the api service.
3. Navigate to your GitHub app settings. In the General section, navigate to the Webhook section.
4. Copy the following settings (replacing the URL with the URL of you api service instance webhook URL for example https://app.test.com/api/webhhoks/github and the secret with your secret):

4. Click on Save Changes.

5. Navigate to Permissions and Events on the left-side panel and scroll down to Subscribe to Events. Toggle the following:

• Issues
• Issue comment
• Pull request
• Star
• Watch
• Fork
• Discussion comment

Done! After connecting the integration, new events will automatically be added to your crowd. dev deployment.