Connect a repository

Connecting a repository gives CBX Guard two things — and they're deliberately separate:

1. IaC context (always, read-only). On connect, CBX Guard indexes the Terraform, Helm, Kubernetes, and GitOps config in the repo. This is the infrastructure-context graph the engine reasons over.
2. The merge gate (optional, opt-in). Separately, you can enable a PR/MR check that posts a verdict on each change. This is the only part that ever writes to your repository, and it's always a second, explicit step.

That separation is the read-only-first principle: every connection starts from the least privilege that still works, and every step that writes is opt-in. See Concepts.

---

GitLab

GitLab offers two customer paths. Which one fits depends on your GitLab tier and whether you'd like CBX Guard to provision a bot for you or bring your own.

Option A — OAuth (GitLab Premium and above)

The fast path. Click Connect GitLab, consent once, and CBX Guard provisions a durable service account ("CBX Guard") scoped to the top-level group of the repos you connect:

1. Click Connect GitLab in the Console and approve the OAuth consent screen.
2. Connect a repository. CBX Guard finds-or-creates a cbx-guard-bot service account at that group, mints a token for it, and grants it the membership it needs to read the group and open the gate MR.
3. From then on, every action is authored by the bot — so it keeps working after the person who connected it leaves.

Option B — Bot token (any tier, including Free)

The universal floor. You bring a token for a user that acts as the CBX Guard bot:

1. Create (or choose) a GitLab user to act as the CBX Guard bot and add it to the groups/projects you want watched, with Maintainer access.
2. As that user, create a Personal Access Token with the api scope.
3. Paste the token into the Console.

CBX Guard validates the token, confirms its scope, and uses it for every read and for the gate MR. Because it's your token, you control its lifetime — and revoking it in GitLab cuts access immediately.

---

GitHub

GitHub mirrors the same two paths under a single CBX Guard app.

Option A — Install the GitHub App (recommended)

Install the CBX Guard GitHub App once and pick the repositories it can see. CBX Guard then operates as a first-class cbx-guard[bot] identity, with short-lived installation tokens it mints on demand and a webhook that can post the cbxguard/policy check-run:

1. Click Install GitHub App in the Console — you'll be taken to GitHub's install screen.
2. Choose All repositories or a specific selection, and confirm. (If you're not an org admin, GitHub records the install as a request for an admin to approve.)
3. GitHub returns you to the Console, which confirms the installation and indexes the selected repos.

You manage which repositories CBX Guard can access from GitHub's installation settings at any time.

The GitHub App requests Contents: read, Pull requests: read, Checks: write, and Metadata: read — read everywhere except the check-run it posts when you enable the gate.

Option B — Bot token (any tier)

The symmetric twin of GitLab's bot token. Create a GitHub machine user or a fine-grained PAT granting Contents: read and Pull requests: read/write, then paste it into the Console. CBX Guard validates it and uses it for every read and for the gate.

---

Connection types

After connecting, every repository shows its current connection type, so it's always clear what CBX Guard can do:

---

Disconnecting

Disconnecting a repository drops CBX Guard's access and removes any gate it added. CBX Guard is honest about what it can and can't revoke:

• A token you created and pasted is yours — CBX Guard drops it on its side, and you revoke it in GitLab/GitHub.
• A credential CBX Guard provisioned (an OAuth service-account token, or the GitHub App installation) is revoked by CBX Guard, or by uninstalling the app from your provider.

---

Next steps