Skip to main content

GitHub / GitLab connector

The forge connector is a code connector. It watches a repository branch, and when content changes it catches the repository up on the server and delivers the results as one open pull/merge request that every later delivery updates in place — never a direct push to the tracked branch.

This is the route for a team that wants a repository governed without anyone running a command. There is no pipeline in the repository, no CLI on anyone's machine, and no scheduled job. The alternative for a repository is the kapi connector, which puts the same work under a developer's own hand. Both can run side by side against one project.

note

The forge connector is not offered in the web app's add-connector dialog for static-token setups. Create it through the workspace connectors API (manage connectors permission), or install the server's GitHub App and bind repositories from a project's Connectors page (below).

What it syncs​

Content files matching the connector's glob patterns on the tracked branch. Target files land at the conventional per-locale path: a path segment or filename stem equal to the source language becomes the target language (locales/en/app.json → locales/fr/app.json); other layouts get the language suffixed to the stem.

When a run parks work for a person, the pull/merge request says so; approvals travel through the project's review queue and arrive in a later delivery.

Setup with a token​

Create the connector, then point a webhook at the server:

curl -X POST "$SERVER/api/v1/$WORKSPACE/connectors" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "forge",
    "name": "website",
    "config": {
      "repo": "https://github.com/acme/website.git",
      "branch": "main",
      "project_id": "<project-id>",
      "token": "<forge API token>",
      "webhook_secret": "<random secret>",
      "patterns": "src/locales/**/*.json"
    }
  }'

Then add a push webhook in the repository settings pointing at $SERVER/api/webhooks/forge/<connector-id> with the same secret — GitHub signs the payload (secret field), GitLab sends it as the secret token. The token needs pull/merge-request write access: a GitHub fine-grained PAT with contents + pull-requests write, or a GitLab project access token with api scope.

Optional config: forge (github | gitlab; default inferred from the repo host — self-managed GitLab included), delivery_branch (default bowrain/translations), pr_title, pr_labels.

Credentials are sealed at rest like every connector secret. Pushes to branches other than the tracked one — including the delivery branch itself — are ignored, so the connector's own deliveries never re-trigger a run.

GitHub App mode (no tokens, no per-repo webhooks)​

With a GitHub App registered for your server, connectors on GitHub need neither a token nor a webhook secret. GitHub routes every installed repository's pushes to one app endpoint, and the server mints short-lived per-installation tokens for each delivery:

{
  "type": "forge",
  "name": "website",
  "config": {
    "repo": "https://github.com/acme/website.git",
    "branch": "main",
    "project_id": "<project-id>",
    "auth": "app",
    "patterns": "src/locales/**/*.json"
  }
}

Register the app once (GitHub → Settings → Developer settings → GitHub Apps → New) with webhook URL $SERVER/api/webhooks/github-app, a webhook secret, the push event, and repository permissions Contents: read & write, Pull requests: read & write, Metadata: read. Download the private key and configure the server:

GITHUB_APP_ID=<app id>
GITHUB_APP_PRIVATE_KEY_FILE=/etc/bowrain/github-app.pem   # or GITHUB_APP_PRIVATE_KEY (PEM text)
GITHUB_APP_WEBHOOK_SECRET=<webhook secret>

Installing the app on a repository is then the only per-repo step. GitHub redirects to the server's setup page (set the app's Setup URL to $SERVER/github/setup), which lists the installation's repositories and binds each to a project with one selection — no curl, no tokens. The setup page is a complete on-ramp: a visitor who arrives without a Bowrain account signs in or creates one (the installation is preserved through login), gets a workspace if they have none, and can create a project from the repository inline. The same binding is available from a project's Connectors page ("GitHub"), and the workspace connectors API remains the automation path.

Static tokens keep working alongside app mode. GitLab always uses a project access token.

See The Bowrain GitHub App for the end-to-end walkthrough.