GitHub

Integrating with GitHub or GitHub Enterprise (EE) allows you to use it as a Git hosting provider and sign in to the workspace with your GitHub profile. The process for adding the integration is the same for both versions of GitHub, unless stated otherwise in the document.

The integration is split into two parts:

• Creating a GitHub App allows you to use GitHub as your Git provider in Buddy.
• Creating an OAuth App in GitHub allows you to use GitHub as an identity provider and sign in to Buddy using your GitHub account.

Integrating GitHub as a Git hosting provider

1. Sign in to your Buddy self-hosted instance as admin.
2. Add a new project and select GitHub as the provider.
3. Click the button to begin configuration:

Start of the configuration

4. Copy the Authorization Callback URL.
5. In GitHub, go to Developer settings → GitHub Apps and click New GitHub App.
6. Provide the name for the app and paste the callback URL copied from Buddy in step 4. Then provide your page address as the Homepage URL.

7. Enable these options:

   • Expire user authorization tokens
   • Request user authorization (OAuth) during installation
   • Redirect on update
8. Disable the webhook by unchecking the 'Active' checkbox in the Webhook section.

9. Set the repository permissions:

   • Contents: Read-only
   • Metadata: Read-only
   • Pull requests: Read-only
   • Webhooks: Read & Write
   • Commit statuses: Read & write

10. Set account permissions:

    • Email adresses: Read-only
11. Make the app public: select Any account in the Where can this GitHub App be installed? section.
12. Click Create GitHub App.
13. Click Generate a new client secret.
14. Copy the Client Secret and Client ID from GitHub. Copy the GitHub App name from your browser's address bar. Paste the details into the corresponding fields in Buddy:

GitHub App details

15. Provide the public URL of your instance.
16. Click Save changes and restart Buddy.
17. After you restart Buddy, create a new project and select GitHub as your Git hosting provider. In the popup window, click Authorize {GITHUB_APP_NAME}.

Authorizing the GitHub App

Integrating GitHub as an identity provider

1. Sign in to your Buddy self-hosted instance as admin.
2. Go to Self-Hosted Admin → 3rd-Party Apps and select your version of GitHub:

3rd-Party Apps view

3. Copy the Authorization Callback URL.
4. In GitHub, go to Developer settings → OAuth Apps and click New OAuth App.
5. Configure app details: provide the name, URL, and paste the callback URL copied from Buddy.
6. Click Register application.
7. Click Generate a new client secret.
8. Copy the Client Secret and Client ID and paste them into the corresponding fields in Buddy:

GitHub OAuth App details

9. Click Save changes and restart Buddy.

After adding this integration, you can to sign in to Buddy with your GitHub account:

Sign in with GitHub button

Webhook redirection on non-public-instances

If your instance is not publicly available, follow these instructions to ensure that webhooks from GitHub are successfully reaching Buddy:

1. Go to the settings of your GitHub App: https://$INTERNAL_BUDDY_IP_ADDRESS/settings/apps/GIT_HUB.
2. Set the Public URL of this Buddy instance to the public address of your network with a custom port.
3. On your router, redirect the public address and port to $INTERNAL_BUDDY_IP_ADDRESS:80.