GitHub integration

Connect GitHub to a Bex workspace to discover granted repositories and build private code. GitHub repository access is separate from signing in with GitHub; a successful login does not authorize builds from every repository your account can see.

Before connecting​

Your platform operator must configure the GitHub App, its credentials and callbacks, and signed webhook delivery. Workspace admins connect installations; ordinary users do not supply the platform's GitHub App private key in a service variable. An unconfigured integration can return 503.

On a configured installation, no separate webhook is needed for every repository covered by that GitHub App. This depends on app-wide webhook setup; it is not a promise that any arbitrary Git URL will receive automatic deployments.

Connect repositories to a workspace​

Use the dashboard's GitHub connection flow in the intended workspace:

1. Start the connection as a workspace admin.
2. Install or authorize the configured GitHub App for the account and repositories you want Bex to access. Complete any organization approval GitHub requires.
3. Complete the return/authorization flow to bind the installation to Bex.
4. Check the workspace's repository list before creating a service.

The equivalent start/list API calls use an admin user's authorized OAuth access token as BEX_TOKEN and an explicit workspace ID. A machine API key has the developer role and cannot start a GitHub connection. See API authentication and permissions.

export BEX_WORKSPACE_ID='replace-with-workspace-id'
 
curl --fail-with-body --silent --show-error \
  -X POST "$BEX_API_URL/v1/git/connect?ownerId=$BEX_WORKSPACE_ID" \
  -H "Authorization: Bearer $BEX_TOKEN"
 
# Open the returned installUrl and complete the browser flow, then:
curl --fail-with-body --silent --show-error \
  "$BEX_API_URL/v1/repos?ownerId=$BEX_WORKSPACE_ID" \
  -H "Authorization: Bearer $BEX_TOKEN"

For an already installed GitHub App, the claim flow starts at POST /v1/git/claim?ownerId=… and returns claimUrl. Complete that authorization flow; an installation ID supplied by itself does not prove ownership.

A workspace can have multiple connections. Inspect them with GET /v1/git/connections?ownerId=…. Repositories shown are the grants from those connections, not an unrestricted inventory of GitHub.

Deploy and enable automatic updates​

Create a service from the repository, choose the tracked branch, and configure its build/runtime or Dockerfile. For a monorepo, check the root directory, command paths, and build filters. Private builds use installation credentials supplied by the platform; do not embed a personal token in the repository URL or Dockerfile.

Automatic deployment requires the service's auto-deploy setting, a matching repository and branch, a valid webhook delivery, and any configured build filter to allow the changed paths. A matching push can start a deployment; it does not prove the build or application will succeed. Inspect the deployment's commit and logs.

For Blueprints, use autoDeployTrigger: commit or off as appropriate. checksPass is not implemented CI gating. GitHub integration also does not imply automatic PR preview environments.

To diagnose a push against declared configuration, open the deployment-filter explorer. Paste the Blueprint, pushed branch, head-commit message and changed paths from all commits in the push. It explains auto-deploy, branch, skip-message, root-directory and build-filter gates without sending the pasted data to a server. [skip render] and [render skip] in the head-commit message skip these automatic deployments case-insensitively; [skip ci] is not that gate.

The report uses the displayed source revision and creation defaults, not live service state or a claim about the deployed platform version. Check current service settings, repository grants and webhook delivery separately. An eligible declaration is not proof that the platform will submit or finish a deployment.

Disconnect an installation​

As an admin, identify the connection and use its returned numeric installation ID with DELETE /v1/git/connections/{installationId}?ownerId=…. The old singular /v1/git/connection route is ambiguous when several installations are connected.

Removing the workspace connection can prevent later private clones and push updates. It is separate from deleting a deployed service. Review and revoke the GitHub-side installation grant as needed, especially if other workspaces use it.

Troubleshooting​

See how deploys work for deployment stages and secrets for application credentials.

See monorepo builds for root-directory and shared-source examples.