Connect repositories

A repository connection authorizes Devboxes to read and publish work on your Git host. Creating a project selects one repository from that connection. You need an organization owner or admin role to manage connections.

Open Credentials → Repository to manage access.

Connect GitHub

Choose Connect GitHub App and complete the GitHub installation flow. Select the repositories Devboxes may access and approve the requested permissions. Return to Devboxes to select a repository for your project.

The project import flow requires an installation configured for selected repositories. If it asks you to change the repository selection or approve updated permissions, make that change in GitHub and reload the installation.

Use a personal access token

Manual connections support GitHub, GitLab, Gitea, and Forgejo. Enter the correct host and a token that can access the repository and perform the actions your task requires.

Use the least access needed for the chosen repositories. Reading a repository, pushing a branch, and creating a pull or merge request can require different permissions. A successful connection check does not prove that every later operation is allowed.

Create the project

Open Projects → Create project and choose the connection. Search for the repository, then configure its workspace image and runner target. A repository already used by a project is identified in the picker.

Repair a connection

If a repository is missing, check its inclusion in the GitHub installation or the token's access. For a suspended or revoked installation, restore or reconnect it in GitHub. For a token that expired or lost access, update the manual connection.

Repair the connection before retrying a failed publication. Check the run's outcome first: work may exist on a branch even when a later operation failed.

Disconnecting a repository connection affects future access. It does not delete the repository from its Git host. See security for credential boundaries.