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 Continue 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. If All repositories is available, keep it selected so future projects work without this step; otherwise choose repositories that include the project's. If you aren't an organization owner, you can choose only repositories you administer. 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. If you can't get App access, you can pull and push with an SSH key on your GitHub account instead: choose Use SSH instead in local folder setup, or ask your coding agent to use SSH. Create from GitHub lists only repositories the App can reach. Automatic pull request updates and follow-ups will still need App access.
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. Under GitHub App access, checkmarks show pull/push, pull requests, viewing Actions and checks, and editing workflow files where the App installation grants it. Editing workflow files is separate from starting Actions runs.

Connecting or reconnecting also turns on GitHub CLI access. Review that setting before letting terminal commands and agents use your account. The GitHub App covers pull, push, pull requests, and CLI commands within its permissions. For broader CLI use, authorize optional personal access after connecting. The App can start workflows and rerun failed CI once the repository's installation owner approves Actions read and write. Your GitHub permissions and the approved authorization scopes will still apply.

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.

Example GitHub settings showing App access and optional personal authorization under GitHub CLI access. 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 for an independent project, boxes.dev will check the machine's ownership and that your connected GitHub account can read the requested repository. You can fetch other authorized repositories and private dependencies without adding them to the project, including readable archived repositories. GitHub will enforce write permission when you push. 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 access 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.

Managed gh prefers connected personal access. Without personal access, boxes.dev checks that the App can reach every known GitHub repository in the project before supplying its credential. The description under GitHub CLI access names the access gh uses. GitHub will enforce the active credential's permissions on each command.

An unavailable GitHub CLI connection does not by itself block new Codex or Claude threads. Reconnect GitHub in Integrations → GitHub when a command requires it. A devbox startup script that uses GitHub may still need that connection to finish.

Run gh auth login to connect optional personal access from a terminal or agent. The command will show a one-time code and GitHub approval URL, then wait for approval with the account connected to boxes.dev. boxes.dev will store the authorization centrally and reuse it across your Template boxes and devboxes. Manage disconnection in Integrations → GitHub, rather than gh auth logout.

The boxes.dev GitHub App requests read and write access to Actions, Checks, Contents, Issues, Pull requests, and Workflows. This supports CI retries, publishing check results, issue changes, code pushes, pull requests, and workflow file edits. Actions access also permits starting and canceling workflows and managing their runs, logs, and artifacts. The App requests read-only access to deployments, your account's email addresses, commit statuses, and repository metadata.

You can install the App on repositories you administer unless your organization only allows owners to install apps.

For an existing installation, a repository or organization owner needs to approve permission increases in GitHub Settings → GitHub Apps → boxes.dev. Existing access will continue while approval is pending. Email access requires your own approval of the updated GitHub authorization; choose Update connection in Account or Integrations → GitHub to review and approve it.

When a supported command needs an App permission increase, managed gh will show a link where an installation owner can accept it. This includes Actions commands, issue and pull-request changes, and gh api requests that write checks or code, or read deployments. The link will match the targeted GitHub account. Email requests will link to your boxes.dev account's Update connection step instead.

The link will appear before the command runs, and the command will still run with its current access. If GitHub denies the command, retry it yourself after approval. If it succeeds, it didn't need the update, so don't run it again. If gh can't identify the target account and your installations have different grants, or permission information is unavailable, it won't choose an approval link. GitHub will still enforce the command's actual permissions; see A GitHub CLI command is denied.

When the setting is off or GitHub isn't connected, gh will use the machine's ordinary configuration, including native gh auth login behavior.

Use optional personal access

Personal access is optional, including when the App already reaches your repositories. In Integrations → GitHub, choose Connect personal access under GitHub CLI access. In Account settings, or after connecting GitHub during onboarding or project setup, choose Connect personal access under Personal GitHub CLI access (optional). You can also run gh auth login on a Template box or devbox. Copy the one-time code and approve the official GitHub CLI on GitHub using the same GitHub account connected to boxes.dev.

GitHub will request repository, read-only organization, gist, and workflow access (repo, read:org, gist, and workflow), including GitHub Actions. Your GitHub permissions and organization authorization still apply. Once connected, managed gh will prefer this access, including permission to start workflows where your account allows it. You can continue using App access without connecting personal access.

Personal access has different permissions from the App. The scopes requested here do not include account email access, and personal access cannot publish check runs. For those commands, choose Disconnect personal access to use App access after approving its required permissions.

Personal access also lets you and your agents add images and videos to pull requests, issues, and comments with gh's --attach flag. GitHub doesn't accept these uploads from the App.

After personal authorization, Integrations and project setup will check access to the project's selected repositories. If personal access can't reach one, a red warning will name it and explain that GitHub CLI commands for it will fail. Open GitHub permissions to authorize the official GitHub CLI for your organization, complete any required SSO sign-in, then choose Check again. You can also choose Disconnect personal access to return managed gh to App access. A failed check won't change credentials or block setup. The check confirms repository access; GitHub will still enforce permissions for each command, including writes.

When the App lacks the repository access a project needs, boxes.dev can also use this authorization for 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. Managed gh will return to App access. If a code expires or approval is denied, start again to get a new code. If the wrong account was used, approve with the account shown by boxes.dev.

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. Passphrase-protected SSH keys can't be copied because coding agents cannot enter the passphrase; choose to create a signing key or skip signing instead. Copied OpenPGP keys keep their passphrase; setup won't store or unlock it. Hardware and agent-only keys also 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.

During agent-driven project setup, you can also ask your coding agent to create a signing key when you don't sign locally. Set your Git name and email in the local repository first. Setup will use OpenPGP unless your Git signing format is SSH; install GnuPG on your computer for OpenPGP. It won't change signing settings on your computer. If the project mixes signed and unsigned repositories, setup will keep signing limited to the repositories that already sign.

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 machine and repository-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 the organization and account information covered by its approved permissions. 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 access 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 Integrations → GitHub.

The App can also lose access to a repository when someone removes that repository from the App's installation on GitHub, even though your GitHub connection still looks healthy. Git commands and startup scripts will then fail with an error that names the repository. Open Integrations → GitHub to give the App access again. An owner of the GitHub organization may need to approve it.

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.