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:

```bash
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](./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