Skip to main content

Documentation Index

Fetch the complete documentation index at: https://paper.brimble.io/llms.txt

Use this file to discover all available pages before exploring further.

Brimble supports three git providers as deployment sources: GitHub, GitLab, and Bitbucket. Each one connects to your account separately. Once connected, you can deploy any repo your account has access to. You can also deploy from a pre-built Docker image instead; see Deploy from a Docker image. That path doesn’t require a git provider connection.

​
Provider summary

ProviderAuth modelPush deploysPR previewsCommit statusWebhook setup
GitHubGitHub App installYesYesYesHandled by the App install
GitLabOAuthYesYes (merge requests)YesAuto-registered per repo on connect
BitbucketOAuthYesYes (pull requests)YesAuto-registered per repo on connect
The auth model is the main difference. GitHub uses an App install at the org or user level, you authorize Brimble’s GitHub App once and it covers every repo you grant it access to. GitLab and Bitbucket use OAuth: you authorize Brimble, Brimble holds a token, and uses it per-repo.

​
Connect a provider

You connect providers from the new-project flow or from your account settings.
  1. In the dashboard, click New project, then pick the source: GitHub, GitLab, or Bitbucket.
  2. If you haven’t connected this provider yet, you’re sent to the provider’s authorization screen.
  3. GitHub: install the Brimble GitHub App and pick which repos or organizations to grant access to. You can change the repo list later from GitHub’s app settings.
  4. GitLab, Bitbucket: authorize Brimble through OAuth. Brimble gets read access to your repos.
  5. You’re redirected back to Brimble. Pick the repo, pick the branch, and continue with the project setup.
Once connected, the provider stays linked to your account. Future projects can pick from the same authorized repos without re-authorizing.

​
Multiple accounts per provider

You can connect more than one account on the same provider, useful when you have a personal GitHub plus a work GitHub, or several GitLab groups. Each shows up as a separate source when you create a project, and you pick the right one per project.

​
What happens on push

When you push a commit to a project’s tracked branch, Brimble’s webhook fires and a build kicks off automatically. The build uses the latest commit on that branch. See Builds for the pipeline. Brimble registers webhooks differently per provider:
  • GitHub: the GitHub App receives webhook events directly. There’s no per-repo webhook configuration on your side.
  • GitLab: Brimble adds a project hook to the repo with push_events, merge_requests_events, and tag_push_events enabled. You’ll see it under your project’s Settings → Webhooks in GitLab.
  • Bitbucket: Brimble adds a repository webhook with repo:push, pullrequest:created, pullrequest:updated, pullrequest:fulfilled, and pullrequest:rejected enabled. Visible in the repo’s Settings → Webhooks in Bitbucket.
Don’t delete the webhook from the provider side. If you do, push events stop reaching Brimble and deploys won’t trigger automatically. To re-register, disconnect and reconnect the provider, or contact support.

​
What happens on a PR or merge request

Pull requests and merge requests open against your tracked branch trigger a preview deployment. The preview runs at its own hostname so you can vet changes before merging.
  • GitHub: PR opened → preview build. PR updated → preview rebuild. PR closed → preview torn down. Brimble posts the preview URL as a commit status check on the PR.
  • GitLab: Same flow keyed off merge request events. open opens the preview, close and merge tear it down.
  • Bitbucket: Same flow keyed off pull request events. pullrequest:created opens the preview, pullrequest:fulfilled and pullrequest:rejected tear it down.
PR previews are gated by plan, see Plans and pricing.

​
Commit status

Brimble updates the commit status on the provider when a deploy starts and when it finishes. You’ll see green check or red X marks next to commits in the provider’s UI. The status links back to the deployment in Brimble.

​
Disconnect or revoke access

To disconnect a provider entirely:
  • GitHub: uninstall the Brimble GitHub App from your account or organization in GitHub → Settings → Applications. Brimble loses access to the repos that App could see.
  • GitLab, Bitbucket: revoke Brimble’s OAuth token in the provider’s authorized-apps settings. The next attempt to deploy from a repo behind that token fails until you reconnect.
After disconnecting, projects deployed from that provider keep their existing deployments running, but new pushes won’t trigger builds. Reconnect to resume.

​
Private repos and organizations

All three providers support private repos. The auth flow grants Brimble exactly the access scope you authorize:
  • GitHub App: per-repo or per-org, granular.
  • GitLab OAuth: scopes granted at authorization time.
  • Bitbucket OAuth: workspace-level access.
Organization owners may need to approve Brimble’s access on GitHub before members can connect org repos. That’s an org-side setting, not a Brimble one.

​
Switching a project’s source

A project’s git source is set at creation. To switch a project from GitHub to GitLab (or any other combination), create a new project from the new source and migrate. Domains and environment variables can be moved over from the old project.

​
Troubleshooting

“Repository not found” or “Authentication failed” during clone. The provider connection has expired or been revoked. Reconnect the provider from your account settings or reinstall the GitHub App. Pushed a commit but no build kicked off. Either the push didn’t go to the tracked branch (check your project’s branch in Configuration), the provider’s webhook was deleted on their side, or the auto-deploy toggle is off in Configuration. Re-register the webhook by disconnecting and reconnecting the provider. PR opened but no preview deployment. PR previews are plan-gated. Confirm your plan allows them; see Plans and pricing. Also confirm the PR targets the tracked branch. Submodule clone fails. Brimble authenticates with the parent repo’s credentials. If a submodule lives in a different repo or different provider, Brimble can’t authenticate to it. Switch submodule URLs to ones reachable with the same credentials, or vendor the submodule.

​
Next steps

Last modified on May 9, 2026