Onboard a project into Plane + Forgejo bridge + Woodpecker

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

Prerequisites

1. Platform services running on VPS:

bash scripts/bootstrap-plane-platform.sh

1. local/.env filled (copy from local/.env.example):

2. PLANE_API_KEY — Plane → Profile → Personal Access Tokens

3. PLANE_WORKSPACE_SLUG — workspace URL slug
4. FORGEJO_API_TOKEN — Forgejo personal access token (packages + repo admin)
5. PFB_FORGE_WEBHOOK_SECRET / PFB_PLANE_WEBHOOK_SECRET — openssl rand -hex 32

6. DEFECTDOJO_API_KEY — DefectDojo → User → API v2 Key (for CI scan uploads)

7. Python 3 + PyYAML: pip install pyyaml

8. 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 (wearlab)

bash scripts/onboard-project.sh \
  --profile fullstack \
  --forgejo-owner alex \
  --repo wearlab-main \
  --plane-prefix WEAR \
  --plane-name "WearLab"

BioScanCheck (paused)

bioscan/bioscancheck is not deployed. Historical onboard docs and scripts under local/*bioscancheck* are kept for reference only.

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 + DefectDojo secrets
App repo	Copy notify-plane-ci.sh, upload-defectdojo.sh, gitleaks.toml

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

After onboard

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

Cursor + Plane MCP

Register in .cursor/mcp.json — see MCP overview and Cursor agent setup.

For app repos (portfolio, aifeatures-site, static-sftp profile), copy Cursor bootstrap from templates/cursor-app/:

# From infra-devops after onboard
cp -r templates/cursor-app/rules/* ../<app>/.cursor/rules/
cp templates/cursor-app/hooks.json ../<app>/.cursor/hooks.json
# Edit ci-red-pipeline.mdc repo slug, then:
bash local/gen-portfolio-mcp-json.sh      # portfolio
bash local/gen-aifeatures-mcp-json.sh     # aifeatures-site

Replace REPLACE_* placeholders in ci-red-pipeline.mdc. Merge AGENTS.md.snippet and docs-AI_CONTEXT.md.snippet into the app repo.

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.