Onboard a project into Plane + Forgejo bridge + Woodpecker¶

Automates what used to be manual steps in New app and Team workflow.

Prerequisites¶

Platform services running on VPS:

bash scripts/bootstrap-plane-platform.sh

local/.env filled (copy from local/.env.example):
PLANE_API_KEY — Plane → Profile → Personal Access Tokens
PLANE_WORKSPACE_SLUG — workspace URL slug
FORGEJO_API_TOKEN — Forgejo personal access token (packages + repo admin)
PFB_FORGE_WEBHOOK_SECRET / PFB_PLANE_WEBHOOK_SECRET — openssl rand -hex 32
Python 3 + PyYAML: pip install pyyaml
Per-app deploy secrets: local/projects/<repo>.env — Woodpecker only via onboard-project.sh

Onboard portfolio (pilot)¶

cd infra-devops
cp local/projects/portfolio.env.example local/projects/portfolio.env
# edit portfolio.env with SFTP credentials

bash scripts/onboard-project.sh \
  --profile static-sftp \
  --forgejo-owner rafael.gonzalez.albes \
  --repo portfolio \
  --plane-prefix PORT \
  --plane-name "Portfolio"

Onboard full-stack app (bioscancheck)¶

bash scripts/onboard-project.sh \
  --profile fullstack \
  --forgejo-owner bioscan \
  --repo bioscancheck \
  --plane-prefix BIOS \
  --plane-name "BioScanCheck"

What the script does¶

Step	Action
Plane	Create/find project, apply kanban states + CI labels
Bridge	Append repo link to `plane/bridge/config.yaml`
Forgejo	External tracker URL + webhook to bridge
Woodpecker	Activate repo, set Plane + deploy secrets
App repo	Copy `scripts/notify-plane-ci.sh`

Report written to local/projects/<repo>.onboard-report.txt.

After onboard¶

Sync infra to VPS: bash scripts/sync-to-server.sh
On VPS deploy with SOPS: bash scripts/deploy-platform.sh
Ensure app .woodpecker.yml includes notify steps (templates/woodpecker-notify-plane.yml)
Push branch feature/PORT-1-test and verify Plane comment

Cursor + Plane MCP¶

Register in .cursor/mcp.json — see MCP overview.

One-time Plane workspace webhook¶

Workspace Settings → Webhooks:

URL: https://bridge.rafaelgonzalezalbes.com/plane/webhook
Secret: same as PFB_PLANE_WEBHOOK_SECRET in secrets/plane-bridge.enc.env (sops edit)

Kanban (all projects)¶

Backlog → Ready → In Progress → In Review → CI Green → QA → Done

Branch: feature/{PREFIX}-{N}-slug
Close: fixes {PREFIX}-{N} on merge

Troubleshooting¶

Issue	Fix
`PyYAML required`	`pip install pyyaml`
Plane 401	Regenerate PAT, check `PLANE_API_URL`
Woodpecker secrets fail	Regenerate Forgejo token with `all` scopes
No Plane comment on CI	Branch must contain `PORT-N`; check Woodpecker secrets
Bridge not syncing	Restart bridge container; verify webhook in Forgejo

Via MCP¶

Use the infra-ops MCP tool onboard_project with the same flags, or ask Cursor to run onboard-project.sh through that tool.