GitHub and GitLab Support Matrix
Cat Factory acts on real code through a provider-neutral source-control layer, so a workspace's repositories can live on GitHub or GitLab. GitHub is the reference implementation every engine path is built against; GitLab is an opt-in provider implementing the same interfaces.
This page is for anyone choosing a provider or running both. It states what each one can actually do today, including where GitLab is behind and why.
Both providers can be configured on one deployment at the same time. A workspace's repositories only need to resolve to the right connection.
Setting each one up
- GitHub: register a GitHub App. See Register the GitHub App.
- GitLab: opt-in and off by default. The provider works on every runtime, but the token is named per runtime: set
GITLAB_TOKEN(scopeapi) on Cloudflare and Node, orGITLAB_PATin local mode.GITLAB_API_BASEis optional on all three and points at a self-managed instance (it defaults to gitlab.com).GITLAB_CONNECTION_IDandGITLAB_WEBHOOK_SECRET(webhook delivery) are optional and apply to Cloudflare and Node. See Configuration → GitLab.
Each provider's API base also decides the web host the app links repositories, merge and pull requests, and issues to, and the host agent containers clone from. A base that names no recognisable host makes the app withhold those links rather than point at the provider's public instance, where the same namespace path is very likely somebody else's project, and a run refuses to dispatch rather than checking out whatever lives at that path.
On Cloudflare the platform passes the GitLab host to each agent container for you. On a self-hosted runner pool the harness is yours to configure: set GITHUB_ALLOWED_HOSTS to your GitLab host on the executor-harness container, or every clone is refused. That variable is the harness's allow-list of hosts it will send a clone credential to, and it defaults to github.com.
Feature parity
| Capability | GitHub | GitLab |
|---|---|---|
| Credential model | App installation: one credential scope per workspace | A per-workspace personal access token for browsing, linking and syncing repositories, over a single shared deployment token (group, personal, or OAuth PAT) that the engine itself uses |
| Multi-tenant credential isolation | Per-installation token | Isolated for repository browsing and linking; the engine's own work (clone, CI, merge) still runs on the one deployment token |
| Self-managed or on-prem instance | Yes (GitHub Enterprise Server, via a configurable API base) | Yes (GITLAB_API_BASE, any self-managed instance) |
| Repository and branch reads | Yes | Yes |
| Where agent containers clone from | github.com, or your GitHub Enterprise Server host | The instance your GITLAB_API_BASE names, including a self-managed one served under a path prefix. On a self-hosted runner pool the harness also needs that host allow-listed, see below |
| File and directory reads | Yes | Yes |
| Branch, commit, and pull/merge request writes | Yes | Yes |
| Merging a pull/merge request | Yes | Yes |
| Updating a request branch with its target | Server-side branch merge | Via merge-request rebase: GitLab has no branch-merge endpoint |
| CI status | Checks API | Pipelines |
| Requested reviewers and submitted reviews | Yes | Yes, with approvals mapped onto reviews |
| Required approval count | Branch protection | Merge-request approval rule |
| Review threads (resolve and reply) | Yes | Yes, as resolvable discussions |
| Changed files with patches | Pull files API | Merge-request diffs. No per-file line counts, so they are counted off the hunk and reported as unreported (never 0) where GitLab withheld them |
| Request head branch and head SHA | Yes | Yes |
| Publishing review findings as inline comments | Per comment, with partial success reported | Per-comment diff discussions plus a summary note, same partial-success reporting |
| Issues: read, create, close, comment | Yes | Yes |
| Issue search | Yes | Yes |
| Sub-issues (parent to child) | Yes | No native concept; callers degrade gracefully |
| Issues as a task source | Full | Imports, searches, diagnoses, backs both the recurring bug intake and the bug hunt, receives webhook push intake and in-ticket replies, and writes back (pull-request notices, the pickup claim, a parked review's questions, acknowledgements). Issue type does not narrow the search (GitLab has no "bug" type, so use labels) |
Filing a NEW issue from the tech-debt tracker step | Yes | Not yet. Pick GitHub Issues, Jira, or Linear as the workspace's filing tracker |
| Code search | Yes | No. It needs GitLab Advanced Search, and the basic API cannot supply a usable repository and URL per hit |
| Webhooks: request, issue, push, CI status | HMAC-signed | Token-header verified |
| Webhooks: connection lifecycle (removed or suspended) | Yes | Not mapped: a removed or suspended connection is not pushed live |
| Periodic reconciliation (catches missed webhooks) | Yes | Yes, on the same provider-neutral path |
| Repository provisioning | Two-app tier, with permissions introspected before the create | Single token, optimistic: the capability is discovered by attempting the create |
| Bootstrapping a new repository with an agent | Yes | Local mode only. On Cloudflare and Node the bootstrap capability reports itself unavailable rather than running against the wrong host |
| Sign-in with a pasted PAT | Yes | Yes |
| Sign-in with an OAuth browser flow | Yes | No, PAT only |
| Sign-in allow-list by login or email domain | Yes | Yes |
| Sign-in allow-list by organization or group | Against organizations | Against group full paths |
| Listing pagination cap | About 1000 items, warns on truncation | About 1000 items, warns on truncation |
Reading this table before you choose
Three rows decide most deployments:
- Credential isolation. On GitHub each workspace gets its own installation scope. On GitLab a workspace connects its own token for browsing and linking repositories, but the engine's own work (cloning, gating on CI, merging) runs on the one deployment-wide token, so a multi-tenant GitLab deployment cannot yet isolate one team's repositories from another's where it matters most.
- Code search. Several agent kinds search code to orient themselves. On GitLab those searches return nothing rather than failing, so agents fall back on reading the checkout.
- Connection-lifecycle webhooks. On GitLab, revoking access is not pushed to the platform. The periodic reconciliation still catches it, so the change lands late rather than never.
Next: Register the GitHub App to set up the reference provider, or Connect a Repository to link one to a board.