Connect a repository

Connect GitHub once, then create Projects for its repositories. Install the devboxes GitHub App, or connect a GitHub account or a GitHub Enterprise Server with an access token.

Owners and admins connect repositories.

Connect with an access token

To do it yourself:

Create an access token on GitHub for the account that devboxes should act as. Give it read and write access to the repositories' contents and pull requests. devboxes opens one pull request per task that publishes commits.

{
  "organizationId": "<organization id>",
  "host": "github.com",
  "token": "<access token>"
}

devboxes invoke repositories.connect --input @connection.json

Delete connection.json afterwards. For a GitHub Enterprise Server, use its host name, for example github.example.com.

The result contains the connection's id and the account that the token belongs to. Connecting the same host again replaces the token.

Connect GitHub with the devboxes GitHub App

In devboxes, open Settings > Repositories and select Install the GitHub app. If the App is already installed on your GitHub account, select It's already installed. GitHub opens in a new tab and returns you there to devboxes, which connects the installation. When the App is installed on several accounts you own, devboxes asks which one to connect.

You can install the GitHub App on all of an account's repositories or only on the ones you choose. devboxes uses a token for one repository at a time. To connect an installation, you must own the GitHub account it is installed on. For an installation on a GitHub organization, you must be an owner of that organization. A repository admin who is not an organization owner cannot connect it, because the connection also covers repositories that the installation gains later. If the organization has not yet approved the App's permission to read organization members, devboxes links to the installation's GitHub settings, where an organization owner approves it.

To start the connection from the CLI:

{ "organizationId": "<organization id>" }

devboxes invoke repositories.github-connect-start --input @organization.json

Open the installationUrl from the result and install the App on your repositories. If the App is already installed, open the authorizationUrl instead. devboxes accepts a GitHub account that is linked to your devboxes account: the one you signed up with, or one you link in the dashboard under Account and security. When your devboxes account has no linked GitHub account, devboxes asks you to sign in to devboxes in that browser first, and then accepts the GitHub account you authorize there.

Then read how the connection went, with the attemptId from the result:

{ "organizationId": "<organization id>", "attemptId": "<attempt id>" }

devboxes invoke repositories.github-connect-status --input @attempt.json

To connect one of installations, add its id to the input:

{ "organizationId": "<organization id>", "attemptId": "<attempt id>", "installationId": "<id>" }

devboxes invoke repositories.github-connect-complete --input @choose.json

Find a repository

List your connections:

devboxes invoke repositories.connections --input @organization.json

List the repositories that one connection can reach:

{
  "organizationId": "<organization id>",
  "connection": { "kind": "manual", "id": "<connection id>" },
  "page": 1
}

devboxes invoke repositories.catalog --input @catalog.json

Use "kind": "github-app" for a GitHub App connection. A repository in the result has a fullName, for example my-org/web-app, which you use when you create a Project.

Disconnect

Remove a connection with repositories.disconnect. devboxes deletes the stored token.