GitHub
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:
- Navigate to the Organization settings using the organization dropdown in the top left corner.
- Select
Git Providers
and clickNew Git Provider
. - Choose
GitHub
as the provider type and entergithub.com
as the provider hostname. - Copy the redirect URL from the form and follow the instructions below to create a corresponding OAuth app on GitHub.
On GitHub:
- 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).
- Go to the organization’s or user’s settings page, and select
Developer settings
>OAuth Apps
. - 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
- Application name:
- Click
Register application
to create the OAuth app.
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.
Starting Workspaces
To start a new workspace after logging into Gitpod, use 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](/docs/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.
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.
- In the OAuth app configuration, look for the org in question in the lower section of the page under
Organization access
. - Click on the
Grant
button. If you don’t have direct permission to authorize 3rd-party integrations, you can hitRequest
to notify the org admin to approve the request.
For more details, see Issue #8076.