Broccoli Oss GCP Deploy

Broccoli OSS GCP Deploy

Overview

Use this skill to deploy this repo into a fresh GCP project without guessing operator-specific values. Discover the active gcloud context first, stop on missing prerequisites or permissions, and only mutate cloud state when the user has clearly asked you to deploy or set this repo up. Assume the operator may be doing this for the first time and may not yet have a project ID or know where secrets belong in GCP.

Intent rule: if the user says things like "set this up for me", "deploy this repo", or shares this repository URL and asks you to get it running, treat that as a deployment request for Broccoli. If they only provided the GitHub repo URL, clone the repo first, then use this skill from the repo checkout.

Authentication boundary: if gcloud requires interactive login or reauthentication, direct the user to complete that flow locally in their own terminal. Never ask the user to paste OAuth verification codes, one-time codes, tokens, private keys, API keys, database passwords, webhook secrets, PEM contents, or any other secret value into chat.

Project boundary: never read, copy, or infer secret values or operator inputs from a different GCP project in order to satisfy this deployment. Treat every target project as isolated unless the user explicitly instructs otherwise for a specific non-secret value. In particular, do not read Secret Manager values from another project to obtain --github-app-id, webhook secrets, API keys, database passwords, PEM contents, or similar deployment inputs.

Missing-input rule: if a required deployment input was not provided in the original prompt and cannot be discovered safely from the target project or active non-secret gcloud context, stop and ask the user for it before proceeding. For non-secret identifiers such as --github-app-id, asking in chat is allowed. For secrets, do not ask the user to send the value in chat; instead, instruct them to populate the target project's Secret Manager secret version themselves out of band and continue only after they confirm it is done. Do not keep going by guessing, reusing another project's values, or silently choosing substitutes.

Auto-discovery rule: once the target project contains the needed Secret Manager values, prefer using those target-project values directly instead of asking the operator to run helper commands themselves. Examples:

• retrieve generated webhook secrets from the target project's Secret Manager when you need them for setup guidance
• use the target project's broccoli-oss-linear-api-key to query Linear for viewer.id and candidate team ids
• use the target project's broccoli-oss-db-password to construct a local TCP DATABASE_URL for operator commands via Cloud SQL Auth Proxy

Only ask the operator for values that are not safely discoverable or that require a human choice, such as the target GitHub repository, the default branch to seed, or which GitHub App installation to use when more than one installation exists.

First-time-operator rule: if the operator does not already have a target GCP project, does not know the final project ID, or does not know where to add secrets, ask whether they want you to create the project first. If they say yes, you may run the apply step even before --github-app-id or operator-managed secret values are present. In that case the wrapper should create the project, attach billing, enable APIs, ensure Artifact Registry and Secret Manager containers exist, then stop with explicit README references for the manual GitHub/Linear/Secret Manager work.

Required Workflow

Follow these steps in order. Do not skip discovery.

1. Discover the operator context

Run the discovery script first:

python .agents/skills/broccoli-oss-gcp-deploy/scripts/discover.py

The script checks:

• local discovery prerequisite: gcloud
• active gcloud account and current project
• visible organizations, folders, and open billing accounts
• recommended parent and billing defaults
• relevant org policies that may block public Cloud Run webhooks

If discovery fails, stop and fix the reported problem before doing anything else.

If the failure is an auth or reauth error, instruct the user to run gcloud auth login <account> --no-launch-browser locally in their own terminal when the operator account is known. Continue only after they confirm it is complete. Do not relay browser login links or ask for the returned verification code in chat.

Local apply requirements are checked when they are actually needed:

• docker + docker buildx only when building images locally
• envsubst only when running deploy/bootstrap.sh
• uv for the post-deploy migration/seed/preflight steps, not for discovery
• all gcloud subprocesses must run in non-interactive mode so the wrapper fails fast instead of hanging on prompts
• for the default Cloud Build path, ensure roles/cloudbuild.builds.builder on the default build executor service account(s) present in the target project before invoking the image build; if iam.serviceAccounts.get is denied, the wrapper should still attempt the binding directly instead of treating that lookup failure as fatal

For exact discovery commands and how to interpret failures, read references/gcloud-discovery.md.

2. Confirm the resolved deployment values

By default, this skill resolves:

• project display name: besimple-broccoli-oss
• preferred project ID: besimple-broccoli-oss
• region: us-central1
• Artifact Registry location: us
• Artifact Registry repository: containers
• Cloud SQL instance: broccoli-oss-pg

If the user supplies overrides, pass them to the scripts instead of hardcoding values.

Required user-provided inputs for the full bootstrap path:

• GitHub App ID (--github-app-id)
• secret values for operator-managed Secret Manager secrets listed below, unless those values already exist in the target project

The apply step may safely generate these deployment-owned secrets if a latest version is missing:

• broccoli-oss-db-password
• broccoli-oss-gh-webhook-secret
• broccoli-oss-linear-webhook-secret

If any operator-managed secret inputs are missing, abort before bootstrap. Ask the user to provide non-secret identifiers in chat if needed, but require secret values to be populated out of band in the target project and confirmed complete before continuing.

If the operator is first-time and asks you to create the project first, it is acceptable to run --apply before --github-app-id and operator-managed secrets are ready. The wrapper should pause after project setup and point them to the README.

3. Run a non-mutating deployment plan

Before applying, run the deployment wrapper without --apply:

python .agents/skills/broccoli-oss-gcp-deploy/scripts/deploy.py --github-app-id <app-id>

This prints the resolved configuration, the required secrets, the exact repo scripts that will be invoked, and the next apply command.

When --github-app-id is missing, use the dry-run output to explain that the operator must manually follow these README sections before full bootstrap:

• README.md -> Deploy it on your GCP -> 1. Create a GitHub App
• README.md -> Deploy it on your GCP -> 3. Open Secret Manager in the right project
• README.md -> Deploy it on your GCP -> 4. Add the required secret values

Important limitation: project ID availability cannot be proven non-mutating. The authoritative check is project creation. If Google reports that the preferred ID is already in use, the wrapper may reuse that exact project only when the active operator can successfully describe it. Otherwise it must stop, report that the preferred ID is unavailable, and ask the user to choose a different project ID. Do not auto-pick a suffixed fallback.