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. Under Repository 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.

GitHub account, repository access, and optional personal CLI authorization in Integrations. 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 ordinary 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. GitHub will enforce the active credential's permissions on each command.

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, organization members, your account's email addresses, commit statuses, and repository metadata.

For an existing installation, a repository or organization owner needs to approve repository and organization 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 and organization members. The link will match the targeted GitHub account. Email requests will link to your boxes.dev account's Update connection step instead.

The command will still run with its current access; after approval, retry it yourself. 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. Choose Enable under Full GitHub CLI access (optional) in Account settings, in Integrations → GitHub, or after connecting GitHub during onboarding or project setup. You can also run gh auth login on a managed machine. 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.

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. 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 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 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.