Connect GitHub

Connect GitHub so you can pull and push project code, create pull requests, and let agents use GitHub from your devboxes.

Connect and grant repository access

1. In the desktop app, open Integrations → GitHub and connect your GitHub account. You can also manage the connection in Account settings, or connect it on the Connect your accounts page when you first set up the desktop app.
2. Give boxes.dev access to your repositories on GitHub. When project setup finds a repository that boxes.dev can't access yet, choose Connect on GitHub. For a repository in your personal account, GitHub will open with that account already selected. For an organization's repository, choose the organization on GitHub. Keep All repositories selected so future projects work without this step, or choose repositories that include the project's. Code on your devboxes can use the granted access. If the organization requires an owner's approval, GitHub will send your request to an organization owner. If the organization isn't listed, copy the request that setup provides and send it to an owner.
3. Return to boxes.dev. If a project repository is missing, use Manage repos or the displayed repository-access action to grant access on GitHub, then return and choose Check again if needed.

The connection page will tell you if your account needs reconnecting. For missing repository access, follow the grant or approval action shown there.

Connecting or reconnecting also turns on GitHub CLI in devboxes. Review that setting before letting terminal commands and agents use your account.

You can connect the same GitHub account to separate personal and work boxes.dev accounts. Connect it from each account; their saved credentials and settings remain separate. To replace the GitHub identity within one boxes.dev account, disconnect its current GitHub connection first.

Connect GitHub from the project's integration page. Select the image to enlarge it.

Understand automatic Git access

New projects with supported GitHub repositories use automatic HTTPS pull and push access by default: git pull and git push work on the Template box and devboxes without registering an SSH key. Before providing Git with a credential, boxes.dev will check that the repository belongs to the project and that your connected GitHub account still has write access. The remote URL contains no token.

GitHub will attribute pushes to your connected account, so your repository permissions and branch rules apply. The author, committer, email, and signature on each commit come from Git configuration.

Existing projects keep the access method chosen during setup. Connecting GitHub won't convert an SSH project to HTTPS. SSH keys on your devboxes retain the permissions granted at the Git host; remove unused keys from GitHub yourself, including after deleting a boxes.dev project.

Allow the GitHub CLI

Integrations → GitHub → GitHub CLI in devboxes lets terminal commands and coding agents use commands such as gh pr, gh run, and gh api with your connected account. The setting applies across your projects and is separate from automatic Git pull and push access.

It's enabled whenever you connect or reconnect GitHub. During desktop setup, you can clear Allow GitHub CLI in devboxes under Finalize Bundle → GitHub access, or turn it off later in Integrations.

boxes.dev needs access to every known GitHub repository in the project before it can manage the CLI identity there. The boxes.dev GitHub App normally provides that access; when your organization can't approve the App for a repository, authorizing personal access is the supported way to supply it. One App or personal authorization must cover every known GitHub repository in the project; their grants aren't combined. While that access remains unavailable, boxes.dev issues no managed credential for that project, and the CLI uses any ordinary GitHub login configured on that machine. The same happens when the setting is off or GitHub isn't connected.

While boxes.dev manages the CLI identity, don't use gh auth login, gh auth logout, or other commands that change the account. GitHub Actions log commands also need the connection's Actions permission.

Use personal access when App approval is unavailable

If your organization can't approve the boxes.dev GitHub App for a project repository, open Integrations → GitHub → Use personal access. Copy the one-time code and approve the official GitHub CLI on GitHub.

When the App lacks the repository access a project needs, boxes.dev can use this authorization, subject to your GitHub permissions. It supports the GitHub CLI, eligible existing HTTPS Git remotes, and explicit pull-request actions. It won't change an SSH remote or add GitHub App webhooks. Automatic pull-request follow-ups still need App access to receive events.

Use Disconnect personal access to remove this authorization separately from your main GitHub connection.

Choose commit identity and signing

Open Account → Git identity to review the name and email boxes.dev supplies on your ordinary Template boxes and devboxes. By default, these come from your connected GitHub account: its profile name, or username if no name is set, and private no-reply email. This default follows your GitHub connection.

To choose another name and email, edit and save them here or during Team Template setup. Only an explicit edit saves an override; accepting the displayed GitHub default during setup will leave it automatic. A saved override will stay the same when you reconnect GitHub or change your login profile. Without GitHub connected, enter an identity or use the project's Git settings.

Git uses the most specific configuration available:

1. Repository-local user.name and user.email take precedence in that repository.
2. Global Git identity imported during setup or edited on the machine takes precedence over the boxes.dev account setting.
3. The account setting supplies values when those more specific settings are absent.

Account edits will reach active machines automatically; sleeping machines will receive the latest value after their next normal wake. Stop supplying identity will remove only the boxes.dev default. Imported global and repository-local configuration will remain, and the default will stay off until you configure it again.

Commit signing is separate from both authorship and GitHub access. When local setup detects signing, you can skip it, create a signing key, or explicitly copy supported signing material to the Template box. Copied protected keys keep their passphrase; setup won't store or unlock it. Hardware and agent-only keys can't be copied. Register the public signing key with the Git host if you want a Verified badge. A signing key alone doesn't grant pull or push access.

Set your preferred merge method

Choose Preferred merge method in Integrations → GitHub or Account settings to set how pull requests created from boxes.dev should merge. Repository permissions and branch rules still apply.

Understand credential access and disconnection

Code running on a Template box or devbox can read a GitHub credential supplied to that machine. The project and write-access checks on automatic Git operations control when boxes.dev supplies a credential; they don't narrow what a supplied credential can reach. The App credential can access repositories available to both your account and the App, which may include repositories outside the current project, and a personal-access credential follows the GitHub CLI permissions you approved on GitHub. Selecting project repositories doesn't narrow either credential.

Disconnecting GitHub or losing repository access will stop new credentials after existing cached access checks expire. App access tokens already received by a process can remain usable until their eight-hour expiry. Disconnecting will also stop pull-request actions until you reconnect, and it disconnects personal access as well. Manage the App's repository grants separately through Manage repos.

Disconnect personal access removes the stored authorization and asks GitHub to revoke it. A personal-access token doesn't always expire on its own, so a copy already read by a process can remain usable until that revocation completes.

Turning off GitHub CLI in devboxes will stop new managed CLI credentials and clear its local cache on connected machines. It won't revoke credentials already held by running processes or offline machines, and it doesn't disable automatic Git pull and push access. It also doesn't remove a gh login or SSH key you configured on a machine yourself; remove those from the machine or from GitHub.

Repair a blocked operation

If you revoke the boxes.dev App's authorization on GitHub, reconnect from each affected boxes.dev account. Removing or suspending an App installation will affect its repositories while other installations remain available; restore needed repository access through Manage repos.

boxes.dev refreshes expiring credentials automatically. If refresh access has also expired, reconnect GitHub when prompted. Temporary GitHub outages are retried without treating the connection as revoked.

Follow the reconnect, repository-access, Workflows-permission, or write-access action shown in Git/Review; see Commit, push, and open a pull request for that workflow. If a recognized project checkout is missing its automatic access configuration, choose Fix GitHub access when offered.

For a pull conflict, resolve the merge or rebase in Terminal before retrying the push.