Heads up! On October 1, we introduced Gitpod Flex. You can swap between documentation by using the switcher in the left navigation bar.

GitHub

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

The first time you login to Gitpod with GitHub, you will be prompted to “Authorize Gitpod” to access your GitHub account. This creates a connection between Gitpod and your GitHub account, and installs an OAuth App in your GitHub settings.

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 CtrlCmd + O or click on the New Workspace button in https://gitpod.io/workspaces. This will prompt for a repository URL, or suggest recent repositories opened with your account.

You can also start a Gitpod workspace using a GitHub repository URL. Simply point your browser to the repository URL prefixed with gitpod.io/# as described in Getting started.

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 at https://gitpod.io/integrations using the context menu on the right.

Gitpod settings for GitHub integration permissions

Errors with private repositories on GitHub orgs

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 https://github.com/settings/connections/applications/484069277e293e6d2a2a.
  2. Look for the org in question in the lower section of the page under ‘Organization access’.
  3. Click on the Grant button.

For more details, see Issue #8076.

Was this helpful?