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
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ the dedicated org-level `<org>/.fullsend` config repo is deprecated

- Forge abstraction: all forge operations go through the `forge.Client` interface, keeping the rest of the codebase forge-agnostic ([ADR 0005](ADRs/0005-forge-abstraction-layer.md)).
- Installation model: ordered layer stack (install forward, uninstall reverse, analyze for status reporting) with idempotent operations. Current stack: config-repo → workflows → vendor-binary → secrets → inference → dispatch → enrollment ([ADR 0006](ADRs/0006-ordered-layer-model.md)).
- Cross-repo dispatch: enrolled repos call `.fullsend` via `workflow_call`; a dispatch workflow mints OIDC tokens exchanged at a central token mint (GCP Cloud Function) for scoped GitHub App installation tokens per agent role. App PEM secrets are stored in Secret Manager (GCF mint) or the local filesystem (standalone mint), not the config repo ([ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md)).
- Cross-repo dispatch: enrolled repos call `.fullsend` via `workflow_call`; a dispatch workflow mints OIDC tokens exchanged at a central token mint (GCP Cloud Function or Cloudflare Worker) for scoped GitHub App installation tokens per agent role. App PEM secrets are stored in Secret Manager (GCF mint), Worker secrets (CF mint), or the local filesystem (standalone mint), not the config repo ([ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md)).
- Shim workflow security: `pull_request_target` prevents PR authors from modifying the shim workflow. No long-lived secrets flow through the shim — OIDC tokens are issued by the GitHub runtime and scoped to the workflow run ([ADR 0009](ADRs/0009-pull-request-target-in-shim-workflows.md)).
- Repo maintenance: a workflow in `.fullsend` (`.github/workflows/repo-maintenance.yml`) reconciles enrollment shims in target repos when `config.yaml` changes or on manual dispatch. The CLI's `EnrollmentLayer.Install()` dispatches this workflow via `workflow_dispatch` and monitors it for completion, then reports any enrollment PRs created in target repos.
- Installer scaffold: the `WorkflowsLayer` deploys content from an embedded scaffold (`internal/scaffold/`), keeping deployable files as real files under version control rather than Go string constants.
Expand Down
42 changes: 33 additions & 9 deletions docs/cli/mint.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ sidebar_label: fullsend mint

# fullsend mint

Deploy and manage the OIDC token mint service. The mint is a GCP Cloud Function that exchanges GitHub Actions OIDC tokens for short-lived GitHub App installation tokens, enabling agents to authenticate without long-lived credentials.
Deploy and manage the OIDC token mint service. The mint exchanges GitHub Actions OIDC tokens for short-lived GitHub App installation tokens, enabling agents to authenticate without long-lived credentials. The mint can be deployed on GCP (Cloud Function) or Cloudflare (Worker).

## Commands

| Command | Description |
|---------|-------------|
| `fullsend mint deploy` | Deploy or update the mint Cloud Function |
| `fullsend mint deploy` | Deploy or update the token mint (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 All @@ -20,7 +20,11 @@ Deploy and manage the OIDC token mint service. The mint is a GCP Cloud Function

## `mint deploy`

Deploys or updates the token mint Cloud Function, creating the service account, WIF pool, and Secret Manager secrets as needed.
Deploys or updates the token mint. Use `--platform` to select the target platform (default: `gcp`).

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

Deploys the mint as a GCP Cloud Function, creating the service account, WIF pool, and Secret Manager secrets as needed.

```bash
fullsend mint deploy \
Expand All @@ -43,16 +47,36 @@ fullsend mint deploy \
--public
```

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

Deploys the mint as a Cloudflare Worker running the mintcore WASM module with a thin TypeScript adapter.

```bash
fullsend mint deploy \
--platform cloudflare
```

Use `--preview` for ephemeral test deploys (supports teardown). Use `--worker-name` to target a specific Worker script name.

Required environment variables:
- `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account identifier
- `CLOUDFLARE_API_TOKEN` — API token with Workers write permission

### Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--project` | | GCP project ID |
| `--region` | `us-central1` | Cloud region for the function |
| `--pem-dir` | | Directory containing role PEM files (first-time bootstrap) |
| `--public` | `false` | Deploy public mint (`ALLOWED_ORGS=*`, permissive WIF) |

### Required IAM roles
| `--platform` | `gcp` | Target platform: `gcp` or `cloudflare` |
| `--project` | | GCP project ID (GCP only) |
| `--region` | `us-central1` | Cloud region for the function (GCP only) |
| `--pem-dir` | | Directory containing role PEM files (GCP only, first-time bootstrap) |
| `--public` | `false` | Deploy public mint (GCP only) |
| `--source-dir` | | Path to local mint source (default: embedded) |
| `--dry-run` | `false` | Preview changes without making them |
| `--worker-name` | `fullsend-mint` | Cloudflare Worker script name (Cloudflare only) |
| `--preview` | `false` | Deploy as ephemeral preview Worker (Cloudflare only) |

### Required IAM roles (GCP)

| Role | Description |
|------|-------------|
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Guides for organization owners and repository administrators who manage fullsend

Advanced guides for platform operators who deploy and manage the GCP-side infrastructure (token mint, WIF, secrets).

- [Mint service administration](infrastructure/mint-administration.md) — Deploying and managing the token mint Cloud Function
- [Mint service administration](infrastructure/mint-administration.md) — Deploying and managing the token mint (GCP or Cloudflare)
- [Standalone mint](infrastructure/standalone-mint.md) — Running the token mint as a standalone HTTP server without GCP
- [Infrastructure reference](infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets deployment details
- [Enabling fullsend on private repositories](infrastructure/private-repositories.md) — Additional guardrails and configuration for private repos
Expand Down
4 changes: 2 additions & 2 deletions docs/guides/infrastructure/infrastructure-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

This guide provides implementation details for fullsend's infrastructure components: the OIDC token mint, Workload Identity Federation (WIF), and secrets deployment. For basic installation instructions, see the [Getting Started guides](../getting-started/).

## Token Mint (OIDC) — GCF Cloud Function
## 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 token`

The mint is a GCP Cloud Function that exchanges GitHub OIDC tokens for scoped GitHub App installation tokens. This eliminates long-lived PATs from the system.
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`.

### Mint Architecture

Expand Down
6 changes: 3 additions & 3 deletions docs/guides/infrastructure/mint-administration.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Mint service administration

This guide covers deploying and managing the fullsend token mint Cloud Function. The mint is the OIDC token exchange service that lets GitHub Actions workflows authenticate as GitHub Apps — it is infrastructure that serves all enrolled organizations and repositories.
This guide covers deploying and managing the fullsend token mint. The mint is the OIDC token exchange service that lets GitHub Actions workflows authenticate as GitHub Apps — it is infrastructure that serves all enrolled organizations and repositories. The mint can be deployed on GCP (Cloud Function) or Cloudflare (Worker).

| Command | Description |
|---------|-------------|
| `mint deploy` | Deploy or update the mint Cloud Function and GCP infrastructure |
| `mint deploy` | Deploy or update the token mint (GCP Cloud Function or Cloudflare 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 |
| `mint unenroll` | Remove an org or repo from the mint |
| `mint status` | Inspect mint health, enrolled orgs, and PEM secrets |
| `mint token` | Exchange a GitHub Actions OIDC token for an installation token |

> **This guide is for platform operators** who deploy, manage, or troubleshoot the token mint Cloud Function. If you are an end user setting up fullsend for your organization, see [Getting Started](../getting-started/) instead — the mint is typically deployed once by a platform operator, and organizations are enrolled as needed.
> **This guide is for platform operators** who deploy, manage, or troubleshoot the token mint. If you are an end user setting up fullsend for your organization, see [Getting Started](../getting-started/) instead — the mint is typically deployed once by a platform operator, and organizations are enrolled as needed.

## Hosted mint

Expand Down
Loading
Loading