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://app.localhost/settings?activeTab=integrations&source=github.
  3. Un-toggle the expiration of user tokens, and toggle Request user authorization (OAuth) during installation.
23062306
  1. 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
  1. Click on Create GitHub app at the bottom of the page.
  2. Set up environment variables in backend/.env:
  • App ID -> GITHUB_APP_ID
  • Client ID -> GITHUB_CLIENT_ID
  • Generate a client secret -> GITHUB_CLIENT_SECRET
22722272
  1. Get the private key to the environment:
  • Generate a private key
19461946
  • Convert it into a one-liner using \n:
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA4+dAC4eHchsLra6dUtFbZSHpAD9iaQxXTfc+CpBTumvY7klf
CE4Q6M+VQ86WLusiBPV/p20QDcQIshht69sRdBxWJyGEK6thoKHMU+MD48TdMaQj
...
-----BEGIN RSA PRIVATE KEY---\nMIIEpAIBAAKCAQEA4+dAC4eHchsLra6dUtFbZSHpAD9iaQxXTfc+CpBTumvY7klf\nCE4Q6M+VQ86WLusiBPV/p20QDcQIshht69sRdBxWJyGEK6thoKHMU+MD48TdMaQj\n...
  • Add it to the environment in backend/.env -> 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.

  1. Add the GitHub installation URL to the frontend environment variables in frontend/.env:
  • 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. In your backend/.env.prod set a random, long string to the GITHUB_WEBHOOK_SECRET environment variable.
  2. Re-deploy the integrations micro-service and copy the webhook URL displayed in the console.
  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 generated URL and the secret with your secret):
20082008
  1. Click on Save Changes.

  2. 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.


Did this page help you?