Repository connections
The two ways an organization reaches its Git repositories, and how to check, rotate, and remove them.
Devboxes imports projects from Git repositories and pushes each run's
work back to them. It reaches those repositories through organization-wide
connections under Manage → Credentials → Repository — every project in the
organization draws from the same connections. Only owners and admins can add,
check, rotate, or delete one; everyone else sees Organization credentials are limited to owners and admins.
Choose a connection
| GitHub App installation | Manual host + token | |
|---|---|---|
| Providers | GitHub on github.com | GitHub, GitLab, Gitea, Forgejo |
| Self-hosted hosts | No | Yes — any host, e.g. git.example.com |
| Setup | Authorize the app in a popup | Save a host and a personal access token |
| What a run pushes with | A short-lived token scoped to the one repository | The stored personal access token |
| Refresh | Reconnect the app | Rotate the token |
Prefer a GitHub App installation for github.com: a run gets a short-lived, repository-scoped token instead of a long-lived one. Use a manual connection for GitLab, Gitea, Forgejo, or a self-hosted GitHub host.
A manual connection stores one personal access token for the whole organization. Anyone who can create a project can import any repository that token reaches, and every run against those projects authenticates with it. Scope the token to the repositories you use, and rotate it when a member leaves.
Connect the GitHub App
- On the Repository tab, click Connect GitHub App. A popup opens GitHub's authorization page for the devboxes-ai app.
- Authorize the app. If you have not installed it yet, GitHub shows its install page first — pick the repositories to grant, then continue.
- If your GitHub user can reach more than one installation, the popup asks you to Choose a GitHub installation. Click one.
- The popup shows GitHub App connected and closes itself; the Repository tab reloads on its own. If the tab stays open, return to Devboxes and click Reload installation.
Each installation lists as Connected, Suspended, or Revoked, and the state mirrors GitHub on its own: uninstalling the app marks its connections Revoked, and suspending the installation marks them Suspended. New runs against a revoked or suspended connection are rejected with a message that names the fix, and the affected project pages show the same warning with a Reinstall GitHub App action. Unsuspending or reinstalling the GitHub App restores runs.
Use Manage GitHub App to change which repositories it grants, then Reload installation to pick them up. A Revoked installation has no token to rotate — click Reinstall GitHub App to re-authorize it. A failed attempt shows GitHub was not connected with the reason; each attempt is single-use and expires 15 minutes after you start it, so restart from Connect GitHub App.
Add and maintain a manual connection
- Next to Manual repository credentials, click Add manual PAT.
- Choose a Provider, enter the Host alone (
github.com,gitlab.com, or a self-hosted host likegit.example.com), and paste a Personal access token. - Save. Devboxes validates the token against the host before storing it; a rejected token is not saved and the dialog shows why.
You keep one active token per provider and host — saving another token for a host you already connected replaces the stored one.
Each row shows a Health state: Not checked, Healthy with the last check time, or Failed with the error. Click Check to re-verify the token now, or Rotate to replace an expired or revoked one. Before swapping in a new token — on rotate or a replacing re-save — Devboxes confirms it still reaches every attached project. Delete removes the connection. These actions are refused while it is in use:
| Message | Cause | Fix |
|---|---|---|
Repository credential does not reach attached projects. | A new token can't read a project already using the connection | Widen the token's scope and retry — the response names the projects |
Repository credential is still used by projects. | Deleting a connection with projects attached | Detach or delete those projects first |
Repository credential is used by active runs. | A queued or running run holds the connection | Let the run finish, then retry |
Import a repository into a project
You pick a connection and import a repository while creating a project. On the repository step, Continue with GitHub uses a GitHub App installation, and Use manual Git host opens an inline form to add a host and token. Once you have saved manual connections, switch between them from the dropdown and search by name to filter the list.
A repository that already backs a project shows a disabled Import button with
the tooltip This repository is already used by <project>. When a GitHub App
installation has gone stale, the step offers Reconnect to GitHub. Devboxes
re-checks the connection before it creates the project; if the repository is no
longer reachable, creation stops with Repository is not available for this GitHub App. or Repository is not available for this repository credential.
The same Credentials screen also holds organization environment variables and model-provider keys.
Next: Creating a project — pairing a repository with a runner image.