---
title: "Golden-Path Recipes"
slug: onboarding-golden-paths
section: Developer Onboarding
status: stable
description: "Pre-approved, \"just follow these steps\" processes for the tasks that come up repeatedly."
last-updated: 2026-10-07
---

# Golden-Path Recipes

Pre-approved, "just follow these steps" processes for the tasks that come up repeatedly. Following the recipe is almost always faster than reasoning it out from scratch — and avoids the specific mistakes past attempts already made.

## Overview

Every row below corresponds to a task type Alliance engineers do often enough that the *right* process is already documented and battle-tested. Deviating from a recipe isn't forbidden, but it means you're now responsible for rediscovering the gotchas the recipe already encodes.

## Recipes

| Task | Follow this process |
| --- | --- |
| Add or change a form field | Change it in `form-engine-portable`, then **tag a `v*` release** — publishing only triggers on the tag, not on merge to `main`. Bump both `BackOfficePrototype` and `PPPToo` to the new published version and verify each consumer picked it up. |
| Add a new MCP server | Deploy it to Cloud Run in the dedicated `alliance-mcp-services` GCP project — never as a Manus-hosted built-in connector, and never a per-environment variant (there should be exactly one instance of any given MCP server). Register it behind the Alliance MCP Gateway so it's reachable as a role-gated tool. |
| Add or modify an n8n workflow | Apply the change live via the n8n API first, verify zero crashes in post-fix executions, then fetch the updated workflow JSON and commit it to the `n8n-workflows` repo. Push with a GitHub App token — a personal OAuth token lacks write access for this. |
| Add a new role or permission | Define the permission key, gate the relevant route, and wire the role into BackOfficePrototype's RBAC model rather than checking ad hoc conditions in the handler. |
| Provision or reset a Globus/BackOffice user | Use the standard provisioning workflow — Cloud SQL proxy access, a DB upsert, MFA disable if needed, credential generation, and delivery via Teams DM. Never hand-edit the database directly outside this flow. |
| Deploy a change to BackOfficePrototype | Sandbox branching model (since 2026-10-06), all through GitHub Actions: cut `feature/<asana-gid>-*` from `main` (a push deploys it to a `globus-dev-N` pool slot), merge it by PR into the current `release/*` branch (deploys to a `globus-qa-N` pool slot), then the release → `main` PR runs the GKE Gateway blue-green cutover. Never push to `development` or `qa` (dead rails), and never Cloud Build for this repo. |
| Reset a portal login | If the Keycloak account already exists, it's a password reset. If it doesn't (a staff member who was never provisioned), it's a provisioning task first — check which situation you're in before picking a process, since they're not interchangeable. |

## When No Recipe Exists

If you're about to touch a production-adjacent system (real applicant data, a shared credential, a live deploy pipeline) and there's no recipe here for what you're doing, that's a signal to ask before improvising — not a gap to quietly fill in with your best guess. If the same ad hoc task comes up more than once, that's the point to propose it as a new recipe on this page.