Skip to content

Multi Forge Support

Jump to bottom
Griffen Fargo edited this page Aug 2, 2026 · 3 revisions

Multi-Forge Support

As of 0.70, coco's forge-aware commands work across multiple git forges instead of GitHub only. Coco auto-detects which forge a repository lives on from its git remote and drives the matching forge CLI — so the same commands, flags, filters, and keybindings work whether you're on GitHub, GitHub Enterprise, GitLab, Bitbucket Cloud, or Bitbucket Server.

Supported Forges

Forge CLI / API Notes
GitHub gh Behavior unchanged from earlier releases
GitHub Enterprise gh Self-hosted GitHub; uses gh's host configuration
GitLab glab gitlab.com and self-hosted GitLab; PRs map to merge requests
Bitbucket Cloud Node fetch (REST API) No CLI binary required. Auth: BITBUCKET_ACCESS_TOKEN or BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD
Bitbucket Server / Data Center Node fetch (REST API) Self-hosted (the product formerly known as Stash). Requires explicit forgeHosts mapping. Auth: same env vars as Cloud
Gitea / Forgejo Node fetch (REST API) codeberg.org auto-detected; self-hosted instances use forgeHosts
Codeberg Node fetch (REST API) Auto-detected from codeberg.org remotes. Uses the same Gitea adapter. A popular GitHub alternative with growing adoption.

Forge Detection

Coco picks the forge from the host of the git remote, using these heuristics:

Remote host Detected forge
github.com GitHub
gitlab.com, or any host containing gitlab (e.g. gitlab.acme.com) GitLab
Any host containing github (e.g. github.acme.com) GitHub Enterprise
bitbucket.org Bitbucket Cloud
Any host containing bitbucket (e.g. bitbucket.corp.com) Bitbucket Cloud
codeberg.org, or any host containing gitea / forgejo / codeberg Gitea

Self-hosted vanity hosts — forgeHosts

A self-hosted instance on a vanity hostname that contains none of the known keywords (e.g. git.acme.com, code.internal.example) can't be auto-detected. Map it explicitly with the forgeHosts config key:

{
  "forgeHosts": {
    "git.acme.com": "gitlab",
    "code.internal.example": "github",
    "bb.corp.com": "bitbucket-server",
    "forge.dev": "gitea"
  }
}

Valid values: "github", "gitlab", "bitbucket", "bitbucket-server", "gitea".

Bitbucket Server / Data Center can only be reached through this map. Its REST API (/rest/api/1.0) and web UI differ enough from Bitbucket Cloud that auto-detection by hostname isn't reliable, and a self-hosted install is commonly on a *bitbucket*-named host that would otherwise resolve to Cloud.

See Configuration Overview for where forgeHosts sits in the config schema and priority order.

CLI Requirements

Coco doesn't talk to forge APIs directly for GitHub and GitLab — it shells out to the forge's official CLI. For Bitbucket (Cloud and Server) and Gitea, coco uses Node fetch against the REST API (no CLI binary required).

GitHub / GitHub Enterprise — gh 

# Install — https://cli.github.com/
brew install gh          # macOS (see the site for Windows / Linux)

# Authenticate
gh auth login

# Verify
gh auth status

GitLab — glab 

# Install — https://gitlab.com/gitlab-org/cli
brew install glab        # macOS (see the project page for Windows / Linux)

# Authenticate
glab auth login

# Verify
glab auth status

Bitbucket Cloud / Bitbucket Server — environment variables

No CLI binary needed. Set one of:

# Option 1: app password (recommended)
export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"

# Option 2: access token (repository or project-scoped)
export BITBUCKET_ACCESS_TOKEN="your-token"

App passwords need the Repositories: Read and Pull requests: Read/Write scopes. For Bitbucket Server, the same env vars authenticate against the Server REST API.

Gitea / Forgejo / Codeberg — environment variables

export GITEA_TOKEN="your-personal-access-token"

When the matching CLI or credentials are missing, coco surfaces a friendly empty state rather than a stack trace. See Troubleshooting for recovery steps.

What Works

Commands

The forge-aware commands work across all supported forges with the same flags, filters, and --json output:

Command GitHub / GHE GitLab Bitbucket Cloud / Server Gitea
coco prs Pull requests Merge requests Pull requests Pull requests
coco issues Issues Issues Issues (Cloud only) Issues
coco pr create Opens PR Opens MR (pushes branch) Opens PR Opens PR
coco issues create Creates issue Creates issue Creates issue (Cloud) Creates issue

--mine / --author @me work on every forge. See the Command Reference for the full flag list.

CI checks and PR lifecycle (0.85+)

The workstation's pull-request inspector gains a CI checks tab showing status-check results per commit. Re-run failed checks and trigger auto-merge directly from the TUI (GitHub and GitLab).

PR lifecycle transitions now include draft -> ready and reopen on all forges that support them.

TUI — the full coco ui triage workstation

The entire coco ui triage experience is multi-forge — the same keybindings regardless of forge:

  • Triage views: g P (PR / MR triage) and g i (issue triage).
  • Inspectors: body, comments, approvals, and pipeline / status-check state hydrate per cursor-rest.
  • Per-row mutating actions:
    • PRs / MRs: merge, approve, close, comment, label, assign.
    • Issues: comment, label, assign, close, reopen.

See Issue & PR Triage for the complete action-key reference and filter-preset cycling.

GitLab Specifics / Limitations

GitLab maps cleanly onto coco's model with a few differences worth knowing:

  • PRs are merge requests. Everywhere coco says "PR" on a GitLab remote, it operates on merge requests.
  • Request changes posts a note. GitLab has no native "request changes" review verb, so the request-changes action (R in the PR triage view) posts a note prefixed Requested changes: instead of a formal review event.
  • Merge strategies. Merging an MR supports squash and rebase strategies.
  • Push on create. coco pr create pushes the source branch automatically before opening the merge request.

GitHub and GitHub Enterprise behavior is unchanged from earlier releases.

Related

Clone this wiki locally