Gitpod works well with public and private repositories from github.com.

​
Registering a GitHub Integration

As an organization owner, you can configure Gitpod with github.com via the following steps: On Gitpod’s Dashboard:
  1. Navigate to the Organization settings using the organization dropdown in the top left corner.
  2. Select Git Providers and click New Git Provider.
  3. Choose GitHub as the provider type and enter github.com as the provider hostname.
  4. Copy the redirect URL from the form and follow the instructions below to create a corresponding OAuth app on GitHub.
On GitHub:
  1. Select an organization or user account under which the OAuth app should be created (this does not limit the repositories that can be used with Gitpod).
  2. Go to the organization’s or user’s settings page, and select Developer settings > OAuth Apps.
  3. Select New OAuth App and fill in the form with the following details:
    • Application name: Gitpod (or any other name you prefer)
    • Homepage URL: your Gitpod instance URL
    • Authorization callback URL: the redirect URL copied from Gitpod
  4. Click Register application to create the OAuth app.

GitHub OAuth App creation screen

After doing the above, you will receive a Client ID and a Client Secret from GitHub. Copy these values into the corresponding fields in Gitpod hit Activate to test the connection.

​
Connecting Your GitHub Account

The first time every member of your organization starts a workspace from GitHub, they will be prompted to connect GitHub to their Gitpod account, via a “Authorize Gitpod” prompt. Gitpod uses the name and email from your GitHub account ID to create a new Gitpod user account. This is sufficient to start a Gitpod workspace on a public repository.

GitHub prompt for Gitpod OAuth App permissions with user:email scope

​
Starting Workspaces

To start a new workspace after logging into Gitpod, use Ctrl/Cmd + O or click on the New Workspace button in your Gitpod Dashboard. This will prompt for a repository URL, or suggest recent repositories opened with your account. Additionally, for an even more seamless workflow with GitHub, refer to our [browser extension](/classic/user/configure/user-settings/browser extension).

​
Granting additional GitHub OAuth permissions

GitHub requires repo scope permissions to open a workspace on a private repository, or to push code changes from a workspace back to your repository. You can grant these additional permissions for GitHub under User Settings > Git Providers using the context menu on the right.

Gitpod settings for GitHub integration permissions

​
Errors with private repositories on GitHub organizations

If you encounter errors setting up a Gitpod project on a private repository in a GitHub org, you may need to approve the Gitpod OAuth app for 3rd party access to the org.
  1. In the OAuth app configuration, look for the org in question in the lower section of the page under Organization access.
  2. Click on the Grant button. If you don’t have direct permission to authorize 3rd-party integrations, you can hit Request to notify the org admin to approve the request.
For more details, see Issue #8076.