Skip to main content

Connect GitHub with OAuth

OAuth is the legacy method to access your GitHub repositories. This feature might be deprecated in the following releases. Semaphore recommends using GitHub App instead of the method described here.

Overview​

Semaphore supports two types of ways to access your GitHub repositories:

  • OAuth App: this connection is provides Single-Sign On (SSO) access to your Semaphore account. It is established during the Semaphore account creation process.
  • GitHub App: an optional type of connection providing additional features such as fine-grained control and per-repository permissions.

You can create and revoke access to both types of connections at any time.

OAuth vs GitHub app​

The OAuth App authorizes Semaphore to impersonate GitHub using your access credentials. This means you need to have admin-level access to the GitHub repository to connect it with Semaphore.

In addition, with OAuth, you can't control access on a per-repository level. Instead, you can only grant or revoke access to repositories based on their visibility, i.e. if they are public or private. It also means that if you delete your GitHub account, Semaphore loses access to all repositories.

Semaphore recommends using the GitHub App whenever possible as it provides two benefits:

  • Granular permissions: you can grant Semaphore access to individual repositories, giving you control over which data Semaphore has access to.
  • No personal tokens: since it does not rely on a personal access token, you can offboard people from the GitHub organization without the connection with Semaphore.

How to sign up using GitHub​

If you are creating a new Semaphore account, you can sign in with GitHub to create the connection automatically.

Follow these steps to create a Semaphore account using GitHub:

  1. Log in to your GitHub account
  2. Navigate to the Semaphore login page
  3. Select Log in with GitHub
  4. Grant access to the Semaphore OAuth App in GitHub
  5. Finish the Semaphore setup

How to authorize OAuth App​

The connection between Semaphore and GitHub should be configured automatically when you sign up. However, this connection can be severed for different reasons. If you don't see your repositories when trying to create a project, follow these steps:

  1. Navigate to your Semaphore account page
  2. Click on Grant public access or Grant private access to grant access to only public or all of your repositories on GitHub Connecting Semaphore to your Git provider
  3. Press Authorize semaphoreci Authorize access to GitHub account

The possible connection status is:

  • Not Connected: the account is not connected. Log out and back into Semaphore to grant access to your GitHub account
  • Email only: Semaphore is connected to your repositories via the GitHub App only. The OAuth App has not been authorized
  • Public repositories: Semaphore can connect to all your public repositories via OAuth App
  • Connected: Semaphore can connect to all your public and private repositories via OAuth App

If your GitHub account is fully disconnected, log out of Semaphore and try to log in again. You will be prompted to give Semaphore access to GitHub.

Connect repositories via OAuth​

To connect a GitHub repository with Semaphore using OAuth, you must have admin access to the GitHub repository.

To create a connection using OAuth, follow these steps:

  1. Create a new project
  2. Select the GitHub Personal Token tab Selecting the personal token tab
  3. Choose Public repositories or All repositories OAuth permission options
  4. Select a repository from the list and finish the project setup

You can only use this method on repositories you have admin-level access to (unavailable repositories are greyed out).

note

Depending on the GitHub organization settings, its owner may need to authorize OAuth App within the organization.

If you have given full access to Semaphore but only see your personal repositories, it might mean that the GitHub organization's owner hasn't granted Semaphore access to the organization yet.

See also​