Repositories

Configuring a repository is an optional way to collaboratively add configuration and refine the experience of working with a repository in Gitpod. Specifically, you can change Prebuild settings to improve workspace start performance, and other configurations such as setting up environment variables which will be accessible to all users with access to the repository in your organization.

How are Repository settings useful?

Improved workspace start performance - Enabling prebuilds will help to speed up the time to open a workspace in Gitpod by running predefined installation tasks in the .gitpod.yml file asynchronously ahead of time. Prebuilds work similarly to Continuous Integration (CI) systems by responding to an SCM trigger (webhook) and remotely executing instructions.
Highlighting configured repositories - When you add a repository to Gitpod, you are signalling to members of your Organization that the repository is configured and “ready-to-code”. Such a repository allows you to collaborate together to improve your developer experience.
Add dynamic configuration - With repositories, you can attach environment variables to be used in your .gitpod.yml configuration. It can be useful to centrally manage your environment variables, as opposed to manually handling the distribution of environment variables to all the users of a Gitpod Organization.
Limit available workspace classes - Limiting workspace classes can be useful to avoid unexpected costs or to ensure that workspaces have the resources they need.
Limit available workspace editors - Limiting available workspace editors on the workspace creation page to match the preferred workflow or setup for a repository.

How does a configured repository relate to a repository’s `.gitpod.yml`?

The repository entity is complimentary to a repository .gitpod.yml definition. For instance, you can access the repository’s environment variables from within the scripts in your .gitpod.yml. The init and before tasks in your .gitpod.yml signal to Gitpod that those specific tasks can be ran as a Prebuild, if Prebuilds are enabled.

How repositories behave in Gitpod

Repositories are associated with an Organization - A configured repository is created within a single Gitpod Organization so that when Prebuilds are enabled, the costs can be attributed to it.
All Organization members create and edit all repositories - All members of an Organization can see all configured repositories, and all members can update any setting on any single one.
Repositories are shown regardless of SCM Authorization - All configured repositories are viewable regardless of whether the user has access to the underlying repository on the respective SCM (e.g. GitHub). That said, an error will be shown when trying to start workspaces on such a repository.

Managing configured repositories

Viewing a configured repository

Ensure that you are looking at the correct Organization using the Organization switcher in the top left of the dashboard.
Once, you click on the Organization switcher, you will be able to see Repositories in the dropdown list. Click on /repositories to view all the addded repositories in the Organization.

Adding a repository

Configured repositories are created in the current Organization. Ensure you are looking at the correct Organization using the Organization switcher in the top left of the dashboard.
Once you click on the Organization switcher, you will be able to see Repository settings in the dropdown list. Click on /repositories to view all the configured repositories in the Organization. You can add a new repository by clicking on the Add Repository button on the top right.

Configuring a repository

All Organization members can perform the following actions via the repository’s settings:

Renaming a repository

You can choose any name up to 100 characters (defaults to the repository name)
Because one git repository can be assigned to multiple Gitpod Repositories (e.g. for developing inside of a monorepo), the name of the Gitpod Repository can be used to distinguish between them. It is recommended to use a name that is unique and descriptive.

Configure Prebuilds

Members can enable/disable them (disabled by default), select prebuild filters (e.g. by introducing branch pattern matching), and change the associated workspace class for Prebuilds to run prebuilds on machines with different resources.
- To enable Prebuilds, the user must have permissions allowing them to create webhooks on the repository.

Add, edit or remove Environment Variables for the repository

Optionally, these variables can be configured to only be visible during prebuilds.

Limit available Workspace Classes for the repository

Members can limit available workspace classes in repository settings.
By default, workspace classes defined at the organization-level are available to repositories.
The repository-level setting takes precedence over the organization-level setting.

Limit available Workspace Editors for the repository

Members can limit available workspace editors in repository settings.
By default, workspace editors defined at the organization-level are available to repositories.
The repository-level setting takes precedence over the organization-level setting.
It only affects the editor selection on workspace creation page.

Remove a repository

Go to the /repositories list page.
Click on View for the repository you wish to delete.
Select Remove Repository. This will only remove the repository from your Gitpod organization and will not delete your SCM (e.g., GitHub) repository.

FAQs

The “Add a repository” page is not finding the repositories I expect?

If you are struggling to find your repositories, try reconnecting your git provider under /integrations and make sure you give Gitpod read access to the repositories you want to add.