Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 53 additions & 1 deletion docs/cli/mint.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Deploy and manage the OIDC token mint service. The mint exchanges GitHub Actions
| Command | Description |
|---------|-------------|
| `fullsend mint deploy` | Deploy or update the token mint (GCP or Cloudflare) |
| `fullsend mint delete` | Tear down mint infrastructure (GCP or Cloudflare) |
| `fullsend mint add-role <role>` | Register a role PEM and app ID on the mint |
| `fullsend mint remove-role <role>` | Remove a role from the mint |
| `fullsend mint enroll <org\|owner/repo>` | Register an org or repo in the mint |
Expand Down Expand Up @@ -59,7 +60,7 @@ fullsend mint deploy \
--platform cloudflare
```

Use `--preview=<alias>` for ephemeral preview deploys. This runs `wrangler versions upload --preview-alias=<alias>` instead of `wrangler deploy`, so the durable Worker script is not affected. The preview mint URL is deterministic: `https://<alias>-<worker-name>.workers.dev`. Preview teardown abandons the alias without deleting the Worker script.
Use `--preview=<alias>` for ephemeral preview deploys. This runs `wrangler versions upload --preview-alias=<alias>` instead of `wrangler deploy`, so the durable Worker script is not affected. The preview mint URL is deterministic: `https://<alias>-<worker-name>.workers.dev`. Preview teardown via `mint delete --platform=cloudflare --preview=<alias>` abandons the alias without deleting the Worker script.

If the target Worker script does not yet exist (first-time preview on a new `--worker-name`), the CLI automatically creates it with a one-time durable deploy before proceeding with the preview upload. Subsequent preview deploys skip this bootstrap step. When `--pem-dir` is set, the bootstrap deploy includes PEM secrets so the Worker is immediately usable.

Expand Down Expand Up @@ -126,6 +127,57 @@ gcloud services enable \
--project="$GCP_PROJECT"
```

## `mint delete`

Tears down mint infrastructure. This is the inverse of `mint deploy`. Use `--platform` to select the target platform (default: `gcp`).

### GCP mode (`--platform=gcp`)

Deletes all GCP mint infrastructure in order: Cloud Function, PEM secrets, service account, and WIF pool (with all providers). Non-critical resource failures (service account, WIF pool) are reported as warnings rather than hard errors.

```bash
fullsend mint delete \
--project "<GCP_PROJECT>" \
--region "us-central1"
```

### Cloudflare durable mode (`--platform=cloudflare`)

Deletes the durable Worker script and all associated bindings/secrets via `wrangler delete`.

```bash
fullsend mint delete --platform cloudflare
```

### Cloudflare preview mode (`--platform=cloudflare --preview=<alias>`)

Abandons the preview alias without deleting the durable Worker script. This is the explicit teardown for preview mints deployed with `mint deploy --preview=<alias>`.

```bash
fullsend mint delete --platform cloudflare --preview bt-run-42
```

### Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--platform` | `gcp` | Target platform: `gcp` or `cloudflare` |
| `--project` | | GCP project ID (GCP only, required) |
| `--region` | `us-central1` | GCP region for the Cloud Function (GCP only) |
| `--worker-name` | `fullsend-mint` | Cloudflare Worker script name (Cloudflare only) |
| `--preview` | | Tear down a preview mint identified by this alias (Cloudflare only) |
| `--dry-run` | `false` | Preview changes without making them |
| `--yolo` | `false` | Skip confirmation prompt |

### Required IAM roles (GCP)

| Role | Description |
|------|-------------|
| `roles/cloudfunctions.developer` | Delete the Cloud Function |
| `roles/secretmanager.admin` | Delete PEM secrets |
| `roles/iam.serviceAccountAdmin` | Delete the mint service account |
| `roles/iam.workloadIdentityPoolAdmin` | Delete the WIF pool and providers |

## `mint add-role`

Registers a GitHub App role on the mint by uploading its PEM key and recording the app ID.
Expand Down
1 change: 1 addition & 0 deletions docs/guides/dev/cli-internals.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ fullsend
│ └── repos <org> [repo...] # Disable agent on repos
├── mint # Token mint management
│ ├── deploy # Deploy/update mint Cloud Function
│ ├── delete # Tear down mint infrastructure
│ ├── add-role <role> # Register role PEM + ROLE_APP_IDS entry
│ ├── remove-role <role> # Remove role from mint
│ ├── enroll <org|owner/repo> # Register org/repo in mint
Expand Down
23 changes: 12 additions & 11 deletions docs/guides/getting-started/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ For organizations that separate GCP and GitHub responsibilities across teams, fu
| GitHub Maintainer | `fullsend github sync-scaffold <org>` | Update workflow templates to current CLI version |
| GitHub Maintainer | `fullsend github uninstall <org>` | Remove GitHub configuration (org-level only) |
| GCP Admin (Mint) | `fullsend mint deploy` | Deploy the token mint Cloud Function |
| GCP Admin (Mint) | `fullsend mint delete` | Tear down mint infrastructure (inverse of deploy) |
| GCP Admin (Mint) | `fullsend mint add-role <role>` | Register a role PEM and app ID on the mint |
| GCP Admin (Mint) | `fullsend mint remove-role <role>` | Remove a role from the mint (deletes PEM secret by default) |
| GCP Admin (Mint) | `fullsend mint enroll <org\|owner/repo>` | Register an org or repo in the mint (does not grant Agent Platform access — use `inference provision`) |
Expand All @@ -126,17 +127,17 @@ The typical handoff: a GCP admin runs `mint deploy` + `mint enroll` + `inference

When using the split-responsibility workflow, each standalone command requires a subset of IAM roles. Use this table to request only what you need.

| IAM Role | `inference provision` | `inference deprovision` | `inference status` | `mint deploy` | `mint add-role` | `mint remove-role` | `mint enroll` | `mint unenroll` | `mint status` |
|----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `roles/iam.workloadIdentityPoolAdmin` | x | x | | x | | | x | x | |
| `roles/resourcemanager.projectIamAdmin` | x | | | \* | | | | | |
| `roles/iam.serviceAccountAdmin` | | | | x | | | | | |
| `roles/secretmanager.admin` | | | | \* | \*\* | \*\*\* | | | |
| `roles/cloudfunctions.developer` | | | | x | | | | | |
| `roles/cloudfunctions.viewer` | | | | | x | x | x | x | x |
| `roles/run.admin` | | | | x | x | x | x | x | |
| `roles/iam.workloadIdentityPoolViewer` | | | x† | | | | | | |
| `roles/secretmanager.viewer` | | | | | § | | | | x |
| IAM Role | `inference provision` | `inference deprovision` | `inference status` | `mint deploy` | `mint delete` | `mint add-role` | `mint remove-role` | `mint enroll` | `mint unenroll` | `mint status` |
|----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `roles/iam.workloadIdentityPoolAdmin` | x | x | | x | x | | | x | x | |
| `roles/resourcemanager.projectIamAdmin` | x | | | \* | | | | | | |
| `roles/iam.serviceAccountAdmin` | | | | x | x | | | | | |
| `roles/secretmanager.admin` | | | | \* | x | \*\* | \*\*\* | | | |
| `roles/cloudfunctions.developer` | | | | x | x | | | | | |
| `roles/cloudfunctions.viewer` | | | | | | x | x | x | x | x |
| `roles/run.admin` | | | | x | | x | x | x | x | |
| `roles/iam.workloadIdentityPoolViewer` | | | x† | | | | | | | |
| `roles/secretmanager.viewer` | | | | | | § | | | | x |

\* `roles/resourcemanager.projectIamAdmin` and `roles/secretmanager.admin` are required for `mint deploy` only when using `--pem-dir` (first-time bootstrap). Standard deploys without `--pem-dir` do not need these roles.

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/infrastructure/infrastructure-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This guide provides implementation details for fullsend's infrastructure compone

## Token Mint (OIDC)

> Managed by: `fullsend mint deploy`, `fullsend mint enroll`, `fullsend mint unenroll`, `fullsend mint status`, `fullsend mint add-role`, `fullsend mint remove-role`, `fullsend mint workflow-host`, `fullsend mint token`
> Managed by: `fullsend mint deploy`, `fullsend mint delete`, `fullsend mint enroll`, `fullsend mint unenroll`, `fullsend mint status`, `fullsend mint add-role`, `fullsend mint remove-role`, `fullsend mint workflow-host`, `fullsend mint token`

The mint exchanges GitHub OIDC tokens for scoped GitHub App installation tokens. This eliminates long-lived PATs from the system. The mint can be deployed on GCP (Cloud Function) or Cloudflare (Worker) — see `fullsend mint deploy --platform`.

Expand Down
21 changes: 11 additions & 10 deletions docs/guides/infrastructure/mint-administration.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ This guide covers deploying and managing the fullsend token mint. The mint is th
| Command | Description |
|---------|-------------|
| `mint deploy` | Deploy or update the token mint (GCP Cloud Function or Cloudflare Worker) |
| `mint delete` | Tear down mint infrastructure (Cloud Function, secrets, SA, WIF pool or Worker) |
| `mint add-role` | Add an agent role (PEM secret + `ROLE_APP_IDS` entry) |
| `mint remove-role` | Remove an agent role from the mint (deletes PEM secret by default) |
| `mint enroll` | Register an org or repo in `ALLOWED_ORGS` and configure WIF |
Expand Down Expand Up @@ -52,16 +53,16 @@ Pass this URL as `--mint-url` when running `fullsend github setup`, or set the `

- **GCP IAM roles** — the user running mint commands authenticates via ADC (`gcloud auth application-default login`). The required roles depend on the command:

| IAM Role | `mint deploy` | `mint add-role` | `mint remove-role` | `mint enroll` | `mint unenroll` | `mint status` |
|----------|:---:|:---:|:---:|:---:|:---:|:---:|
| `roles/iam.serviceAccountAdmin` | x | | | | | |
| `roles/iam.workloadIdentityPoolAdmin` | x | | | x | x | |
| `roles/resourcemanager.projectIamAdmin` | \* | | | | | |
| `roles/secretmanager.admin` | \* | \*\* | \*\*\* | | | |
| `roles/cloudfunctions.developer` | x | | | | | |
| `roles/cloudfunctions.viewer` | | x | x | x | x | x |
| `roles/run.admin` | x | x | x | x | x | |
| `roles/secretmanager.viewer` | | § | | | | x |
| IAM Role | `mint deploy` | `mint delete` | `mint add-role` | `mint remove-role` | `mint enroll` | `mint unenroll` | `mint status` |
|----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `roles/iam.serviceAccountAdmin` | x | x | | | | | |
| `roles/iam.workloadIdentityPoolAdmin` | x | x | | | x | x | |
| `roles/resourcemanager.projectIamAdmin` | \* | | | | | | |
| `roles/secretmanager.admin` | \* | x | \*\* | \*\*\* | | | |
| `roles/cloudfunctions.developer` | x | x | | | | | |
| `roles/cloudfunctions.viewer` | | | x | x | x | x | x |
| `roles/run.admin` | x | | x | x | x | x | |
| `roles/secretmanager.viewer` | | | § | | | | x |

\* `roles/resourcemanager.projectIamAdmin` and `roles/secretmanager.admin` are required for `mint deploy` only when using `--pem-dir` (first-time bootstrap). Standard deploys without `--pem-dir` do not need these roles.

Expand Down
3 changes: 2 additions & 1 deletion internal/cli/mint.go
Original file line number Diff line number Diff line change
Expand Up @@ -371,10 +371,11 @@ and mint short-lived tokens via OIDC.
The mint can be deployed on GCP (Cloud Function) or Cloudflare (Worker).
Use 'fullsend mint deploy --platform' to select the target platform.

Infrastructure subcommands (deploy, enroll, unenroll, status, add-role, remove-role) require
Infrastructure subcommands (deploy, delete, enroll, unenroll, status, add-role, remove-role) require
platform-specific access. The 'token' subcommand requires only GitHub Actions OIDC.`,
}
cmd.AddCommand(newMintDeployCmd())
cmd.AddCommand(newMintDeleteCmd())
cmd.AddCommand(newMintEnrollCmd())
cmd.AddCommand(newMintUnenrollCmd())
cmd.AddCommand(newMintStatusCmd())
Expand Down
Loading
Loading