Plane is a self-hostable project tracker — the open-source bit of it ships under AGPL and the company makes its money on a Commercial Edition plus a handful of paid integrations. Two of those paid integrations are the GitHub and GitLab connectors that keep issues and PRs in sync with your tracker. They live in a closed-source service called silo, distributed as a binary out of artifacts.plane.so and not present in the makeplane/plane repo at all.
That’s fine if you use GitHub or GitLab. If you self-host on Forgejo or Gitea — as I do, in the same homelab Plane runs in — there’s no first-party path forward. makeplane/plane#1495 has been open since 2023 asking for native Forgejo support; nothing has moved. A third-party paid plugin exists; for what it does, I’d rather just write the daemon myself.
So I wrote plane-forge-bridge (PFB). MIT, Go, single static binary. Repo: github.com/hstern/plane-forge-bridge.
What it does
PFB sits between Plane and any Gitea-API-compatible forge (I run it against Forgejo; the integration tests cover Gitea too). Two HTTP webhook endpoints, two REST clients, no database, no on-disk state. The whole thing is one process and a YAML config.
Bidirectional, per-link:
- Issues create / update / close / reopen ↔ work items, with title, description, state, assignee, and label sync
- Comments both ways (edit and delete deferred to a later version)
- Labels both ways with auto-create on either side
- State mapping per repo-to-project link (your forge
open/closedmap to whatever Plane states you want) - PR open/reopen/close/merge → work-item state automation via
[PROJ-123]brackets in title/body orproj-123-foohead-branch names - Plane → forge issue creation closes the loop (a work item created on the Plane side mints a matching forge issue)
Identity resolution is config-first, email-match second, bridge bot as fallback. The email match defeats Gitea/Forgejo’s <id>+<login>@noreply.localhost placeholder by re-resolving through the user-search API when the webhook ships a noreply address.
Image: ghcr.io/hstern/plane-forge-bridge:0 (rolling major) or :0.1.4 (current).
Where I spent most of the time
The naive description of this project (“a webhook bridge”) undersells the bit that turned out to actually be hard, which is that the Plane wire shape on the public API does not match the wire shape on its webhooks, and neither matches what the docs imply. Four bugs in the same week, each a different facet of “the testdata I hand-wrote didn’t survive contact with real Plane”:
Past-tense action verbs (
created, notcreate). The first v0.1 release shipped a parser that only recognised the present-tense form because that’s what the docs page showed. Real Plane sends past-tense. Every webhook 204’d silently because the parser hitErrUnsupportedEventand logged at DEBUG. The default log level is INFO. Plane saw 204 and stopped retrying. The bridge looked healthy from both sides; nothing flowed.state/labels/assigneesare objects in webhooks. I had them typed as bare UUID strings to match my reading of the REST surface. Real Plane CE 1.3 ships them as nested objects withid/name/color/group. v0.1.1 fixed the parser tense bug, and the very next delivery 400’d on payload decode.state/labels/assigneesare bare UUID strings in the RESTPOST /issues/response, even though the webhook delivery for the same work item ships them as objects. So once I’d typed them as objects to handle the webhook, everyforge → planecreate call failed decoding the create response. The work item was created on the Plane side (external_sourcewas even set correctly), but the bridge had no record of the Plane UUID. Plane then fired its ownwork_item.createdwebhook, and — because the loop-break marker had been silently stripped (see next point) — the bridge dutifully created a duplicate forge issue. Fix: a customUnmarshalJSONon the ref types that accepts both shapes.The loop-break marker is non-functional on description echoes. PFB’s design assumes every outbound write ends with
<!-- pfb:src=<forge|plane>,evt=<id> -->, and inbound events carrying that marker are dropped before any work happens. Comment bodies preserve the marker. Plane’s ProseMirror sanitizer strips HTML comments out ofdescription_htmlduring issue creation. POST<p>x</p>\n\n<!-- pfb:src=forge,evt=42 -->and GET back<div><p>x</p>\n\n</div>. Verified by probe against my own Plane instance. The marker check that was supposed to be the durable defence against echoes was a no-op for the path that mattered most. The actual durable defence turned out to be theexternal_sourceround-trip: the bridge stampsforge:owner/repoon every create, and the inbound handler now skips anywork_item.createdwhoseexternal_sourcematches that prefix.
The whole class of bug has the same root cause: I had testdata that didn’t match real Plane, and a recording stub in the e2e harness that happily agreed with the testdata, so CI never saw the divergence. The structural fix landed alongside the last bug: a new CI job that brings up a real Plane CE container (api + worker + postgres + redis + rabbitmq + minio), seeds it through Django ORM, and runs the actual bridge image against it.
Plane CE has no headless signup flow — the human path goes through Django sessions, CSRF, and the workspace onboarding UI, none of which are great to drive from a script. The seed bypasses all of that by creating Instance (with is_setup_done=True), User, InstanceAdmin, Workspace, Project, default states, and an APIToken directly through the ORM inside the plane-api container. It’s idempotent, takes ~90 seconds on a cold image cache, and now gates every release.
Architecture notes I’m pleased with
- Stateless process. No database, no on-disk state. Config + env vars in, HTTP out. The bridge can be killed and restarted at any point; the loop-break marker is the durable defence, the in-memory LRU is the optimization.
- One forge package speaks both Forgejo and Gitea. They share the v1 REST API and the webhook payload format (
X-Gitea-SignatureHMAC-SHA256,X-Gitea-Event). CI proves the contract by running e2e against both images as a matrix on every PR. - HMAC verified at the handler boundary before the body is parsed, constant-time compare, reject on missing header. The forge/plane parse layers don’t have to second-guess provenance.
- The bridge is the single writer of its own outbound calls. No retry loop that could double-write before the loop-break check on the return path; idempotency relies on the marker (or, on the description side, the
external_sourcebackstop) being present on the first write.
Configuration
config.yaml looks like this. The file names environment variables that hold the secrets; it doesn’t store the secrets themselves, so it’s safe to commit alongside infrastructure code.
listen: "0.0.0.0:8080"
log_level: info
forge:
base_url: https://forge.example.com
token_env: PFB_FORGE_TOKEN
webhook_secret_env: PFB_FORGE_WEBHOOK_SECRET
plane:
base_url: https://plane.example.com/api/v1
workspace_slug: my-workspace
api_key_env: PFB_PLANE_API_KEY
webhook_secret_env: PFB_PLANE_WEBHOOK_SECRET
bridge_bot:
forge_username: plane-bridge
plane_member_id: 00000000-0000-0000-0000-000000000000
links:
- forge_repo: acme/widget
plane_project_id: 9e06069d-f7af-4e3e-a4ba-82dc594af17d
project_identifier: PFB
state_map:
open: Backlog
closed: Done
pr_state_map:
opened: "In Progress"
merged: "Done"
closed: "Cancelled"
users:
alice: 4f8c2b15-...
bob: 7a1e83df-...
Register webhooks on both sides pointing at the bridge with matching HMAC secrets, and you’re done. JSON-structured logs (one line per accepted webhook, with kind, delivery_id, and the resulting outbound action) tell you exactly what’s happening.
What ships today
- Issue and comment sync both ways, with labels and state mapping.
- PR-driven state automation via
[PROJ-123]bracket refs in titles/bodies orproj-123-foohead-branch names. - Plane → forge issue creation closes the bidirectional loop.
- Distroless multi-arch image (
linux/amd64,linux/arm64) atghcr.io/hstern/plane-forge-bridge. - CI matrix with three legs: Forgejo 15, Gitea 1.22, and real Plane CE v1.3.1 — all three required for publish.
Out of v0.1 (on the roadmap): comment edit/delete identity persistence, plane work-item update/delete reverse lookup, PR review state automation, and the OAuth identity handshake (only needed for multi-tenant deployments where forge and Plane emails diverge).
If you self-host Plane against Forgejo or Gitea and want issues to flow without standing up a closed-source connector, give it a try and tell me what’s broken.