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/closed map to whatever Plane states you want)
  • PR open/reopen/close/merge → work-item state automation via [PROJ-123] brackets in title/body or proj-123-foo head-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, not create). 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 hit ErrUnsupportedEvent and 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 / assignees are 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 with id/name/color/group. v0.1.1 fixed the parser tense bug, and the very next delivery 400’d on payload decode.

  • state / labels / assignees are bare UUID strings in the REST POST /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, every forge → plane create call failed decoding the create response. The work item was created on the Plane side (external_source was even set correctly), but the bridge had no record of the Plane UUID. Plane then fired its own work_item.created webhook, and — because the loop-break marker had been silently stripped (see next point) — the bridge dutifully created a duplicate forge issue. Fix: a custom UnmarshalJSON on 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 of description_html during 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 the external_source round-trip: the bridge stamps forge:owner/repo on every create, and the inbound handler now skips any work_item.created whose external_source matches 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-Signature HMAC-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_source backstop) 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 or proj-123-foo head-branch names.
  • Plane → forge issue creation closes the bidirectional loop.
  • Distroless multi-arch image (linux/amd64, linux/arm64) at ghcr.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.