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.

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 On-Premises instance as admin.
  2. Add a new project and select GitHub as the provider.
  3. Click the button to begin configuration:

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 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 user 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:

The GitHub App name is the last part of the URL: https://github.com/settings/apps/{GITHUB_APP_NAME}

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

Authorizing the GitHub AppAuthorizing the GitHub App

Integrating GitHub as an identity provider

  1. Sign in to your Buddy On-Premises instance as admin.
  2. Go to On-Premises Admin3rd-Party Apps and select your version of GitHub:

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:

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:

Sign in with GitHub buttonSign in with GitHub button