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.
Success
GitHub App and OAuth App are independent of each other – you can configure only the part you need for your setup.

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:

Image loading...Start of the configurationStart of the configuration

  1. Copy the Authorization Callback URL.
  2. In GitHub, go to Developer settings → GitHub Apps and click New GitHub App.
  3. 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.
  4. Enable these options:

    • Expire user authorization tokens
    • Request user authorization (OAuth) during installation
    • Redirect on update
  5. Disable the webhook by unchecking the 'Active' checkbox in the Webhook section.
  6. Set the repository permissions:

    • Contents: Read-only
    • Metadata: Read-only
    • Pull requests: Read-only
    • Webhooks: Read & Write
    • Commit statuses: Read & write
  7. Set account permissions:

    • Email adresses: Read-only
  8. Make the app public: select Any account in the Where can this GitHub App be installed? section.
  9. Click Create GitHub App.
  10. Click Generate a new client secret.
  11. 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:
Tip
The GitHub App name is the last part of the URL: https://github.com/settings/apps/{GITHUB_APP_NAME}

Image loading...GitHub App detailsGitHub App details

  1. Provide the public URL of your instance.
  2. Click Save changes and restart Buddy.
  3. 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}.

Image loading...Authorizing the GitHub AppAuthorizing 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 Admin3rd-Party Apps and select your version of GitHub:

Image loading...3rd-Party Apps view3rd-Party Apps view

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

Image loading...GitHub OAuth App detailsGitHub OAuth App details

  1. Click Save changes and restart Buddy.

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

Image loading...Sign in with GitHub buttonSign 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.
Last update:
Sep 24, 2024