Mint Enroll

Mint Service Enrollment

Enroll a new GitHub repository into the fullsend token mint using go run ./cmd/fullsend mint from this checkout. The mint is a stateless service (deployed on GCP Cloud Function or Cloudflare Worker) that exchanges GitHub OIDC JWTs for scoped GitHub App installation tokens.

Follow these steps in order. Do not skip steps.

Always ask the operator for the GCP project ID. Do not infer it from gcloud config get-value project — the local config may point at the wrong project.

Always run the CLI from this checkout via go run. From the repo root:

go run ./cmd/fullsend <subcommand> …

Do not use a fullsend binary from mise, $PATH, go install, or another checkout. A stale CLI can rewrite hosted-mint env vars with obsolete merge logic (this previously dropped e2e/fix from ALLOWED_ROLES and broke e2e). See Running the fullsend CLI.

Setup

STOP — ask the operator for these values before proceeding:

• GCP_PROJECT — the GCP project ID where the mint is deployed. Do not infer from gcloud config get-value project.
• MINT_REGION — the Cloud region (default: us-central1). Confirm with the operator if unsure.
• TARGET — the GitHub repo (acme/widget) to enroll. mint enroll accepts only owner/repo; a bare org is rejected with an error.

GCP_PROJECT="<your-gcp-project-id>"
MINT_REGION="us-central1"   # default; change if deployed elsewhere

Verify the operator has the required IAM roles: Workload Identity Pool Admin, Cloud Functions Viewer, Cloud Run Admin. Secret Manager Admin is only needed for initial PEM bootstrap (mint deploy --pem-dir), not for enrollment. Enrollment does not grant any IAM roles; Vertex AI access for a repo is provisioned separately via fullsend inference provision.

Verify credentials and that this checkout's CLI builds:

gcloud auth list --filter=status:ACTIVE --format="value(account)"
go run ./cmd/fullsend --version

Constraints

• No concurrent enrollment — two operators enrolling simultaneously will race on env var reads/writes. Coordinate enrollment operations serially.
• Always verify app installation — the mint cannot produce tokens for GitHub Apps that are not installed on the target org. Confirm installation before the repo admin triggers a workflow.
• Use --dry-run first — especially for new operators or unfamiliar environments. Dry run previews all changes without applying them.
• Do not enroll .fullsend repos — <org>/.fullsend config repos belonged to the removed per-org installation mode and do not call the mint. Enroll each repository that runs fullsend workflows instead.

Shared App Model

The fullsend-ai org maintains public GitHub Apps shared across orgs.

PEM keys and app IDs are tied to the role, not the org. Secrets use role-only naming (fullsend-{role}-app-pem) — one secret per role, shared across orgs on the mint. ROLE_APP_IDS uses the same model: one GitHub App ID per role (e.g., coder → 123456), shared by all enrolled repos. PEMs and app IDs must already exist (from mint deploy --pem-dir or go run ./cmd/fullsend admin install <owner/repo>); enrollment does not create, copy, or modify PEM secrets or app ID mappings.

Apps must be installed on the target org before the mint can produce tokens. An org admin installs via https://github.com/apps/{slug}/installations/new or by running go run ./cmd/fullsend admin install <owner/repo>.

Enrollment Steps

1. Triage

Determine the target repository:

TARGET="<github-org>/<repo-name>"

Validate the target is a valid owner/repo name before proceeding.

2. Pre-check current state

Run mint status --project to see the current mint state, enrolled repos, Cloud Run revision info, and PEM health — this is the enrollment/admin pre-check step and must be run with --project, since only GCP-based mode reports PEM health, Cloud Run revision info, and template divergence. If FULLSEND_MINT_URL is set in the environment, pass --mint-url= (empty) to force GCP-based mode — otherwise the CLI errors with "ambiguous mode":

go run ./cmd/fullsend mint status --mint-url= --project="$GCP_PROJECT" --region="$MINT_REGION"

When FULLSEND_MINT_URL is already configured, mint status --mint-url is available as a lighter diagnostics command (no GCP IAM roles required), but it only reports version, commit, org, roles, and workflow-host repos — it does not show PEM health, Cloud Run revision info, or the health summary, so it does not replace the --project pre-check above:

go run ./cmd/fullsend mint status --mint-url="$FULLSEND_MINT_URL"

If the mint is not deployed yet, deploy it first:

go run ./cmd/fullsend mint deploy --project="$GCP_PROJECT" --region="$MINT_REGION"

Check the status output for:

• Health: should be "healthy" or "degraded" (not "not-installed")
• Template divergence: if the service template diverges from the traffic-serving revision, enrollment will fix this (the CLI uses REVISION-pinned traffic routing)
• Existing enrollment: if the target repo is already listed in the per-repo WIF repos, re-enrollment is safe — the CLI merges entries idempotently

For an org-level drill-down into PEM status (accepts org name only, not owner/repo — use just the owner portion of the target):

go run ./cmd/fullsend mint status "<github-org>" --mint-url= --project="$GCP_PROJECT" --region="$MINT_REGION"

STOP — show the status output to the operator. Confirm the mint is healthy and the enrollment target is correct before proceeding.

3. Enroll

Preview the enrollment first with --dry-run:

go run ./cmd/fullsend mint enroll "$TARGET" \
  --project="$GCP_PROJECT" \
  --region="$MINT_REGION" \
  --dry-run

STOP — show the dry-run output to the operator and wait for explicit confirmation before running the actual enrollment.

If the preview looks correct and the operator confirms, run the actual enrollment:

go run ./cmd/fullsend mint enroll "$TARGET" \
  --project="$GCP_PROJECT" \
  --region="$MINT_REGION"

The CLI performs the following automatically:

1. Discovers the existing mint infrastructure and verifies shared role→app-id mappings exist
2. Adds the repo to Cloud Run service env var PER_REPO_WIF_REPOS using REVISION-pinned traffic routing
3. Creates a dedicated WIF provider for the repo

On a public mint (PER_REPO_WIF_REPOS=*) the command reports public mode and exits successfully without changing configuration.