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
25 changes: 17 additions & 8 deletions docs/cli/repos.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ These flags are inherited by all `repos` subcommands:
Discovers existing fullsend installations (per-repo and per-org) and generates a `repos.yaml` manifest reflecting their current state. Supports greenfield onboarding and migration from existing installations.

```bash
fullsend repos init <org> --forge github --all --mint-url <MINT_URL> --inference-project <PROJECT>
fullsend repos init <org> --forge github --all --mint-url <MINT_URL>
```

Single-repo mode:

```bash
fullsend repos init <owner/repo> --forge github --inference-project <PROJECT>
fullsend repos init <owner/repo> --forge github
```

### Flags
Expand All @@ -50,7 +50,6 @@ fullsend repos init <owner/repo> --forge github --inference-project <PROJECT>
| `--repos` | | Comma-separated list of repos to include |
| `--all` | `false` | Include all eligible repos without prompting |
| `--mint-url` | | Token mint Cloud Run endpoint URL |
| `--inference-project` | | Default GCP project for inference |
| `--inference-region` | | GCP region for inference (default: `us-central1`) |
| `--fullsend-ref` | | Pin the fullsend workflow ref (e.g. `v0.42.0`) |
| `--concurrency` | `8` | Max parallel API calls (capped at 64) |
Expand Down Expand Up @@ -88,9 +87,11 @@ Runs in two phases:

> **Note:** GCP infrastructure (WIF pools/providers, mint registration) must be
> provisioned separately via `inference provision` and `mint enroll` before
> running `repos install`. The `forge.github.inference_project_number` field
> (numeric GCP project number) is required in the manifest for GitHub repos —
> it is used to compute WIF provider resource names deterministically.
> running `repos install`. The `--inference-project-number` flag (numeric GCP
> project number) is required for GitHub repos — it is used to compute WIF
> provider resource names deterministically. The `--inference-project` flag
> (GCP project ID) is also required for GitHub repos and is written as the
> `FULLSEND_GCP_PROJECT_ID` repo secret.

If a previous install was interrupted (guard variable set but other components missing), the command detects the partial state and repairs it automatically.

Expand All @@ -112,6 +113,8 @@ When repos are specified as positional arguments, only those repos are installed
| `--concurrency` | `4` | Max parallel operations (1-32) |
| `--roles` | `triage,coder,review,fix,retro,prioritize` | Agent roles to install |
| `--direct` | `false` | Push scaffold directly to default branch (skip PR) |
| `--inference-project` | | GCP project ID for inference (written as `FULLSEND_GCP_PROJECT_ID` secret; required for GitHub repos) |
| `--inference-project-number` | | Numeric GCP project number for WIF provider computation (required for GitHub repos) |

### Common workflows

Expand Down Expand Up @@ -211,7 +214,7 @@ Returns a non-zero exit code when drift exists (variables differ from manifest o

## `repos sync`

Reconcile configuration drift for installed repos by writing variables and secrets to match the manifest's desired state. Variables are only written when drift is detected; secrets are always written for convergence since their values cannot be read back.
Reconcile configuration drift for installed repos by writing variables to match the manifest's desired state. Variables are only written when drift is detected. Secrets are written once at install time and are not managed by sync.

```bash
fullsend repos sync
Expand Down Expand Up @@ -249,7 +252,7 @@ With `--json`, the output schema depends on mode:

### Scope

Sync reconciles variables (`FULLSEND_MINT_URL`, `FULLSEND_GCP_REGION`) and secrets (`FULLSEND_GCP_PROJECT_ID`). It does **not** touch scaffold shim version (`@ref`) or harness files — use `repos upgrade` for those.
Sync reconciles variables (`FULLSEND_MINT_URL`, `FULLSEND_GCP_REGION`). Secrets are written once at install time and are not managed by sync. Sync does **not** touch scaffold shim version (`@ref`) or harness files — use `repos upgrade` for those.

## `repos add`

Expand All @@ -272,6 +275,12 @@ fullsend repos add acme/new-api --forge github --dry-run
| `--concurrency` | `4` | Max parallel operations (1-32, used with `--install`) |
| `--direct` | `false` | Push scaffold directly to default branch (used with `--install`) |
| `--roles` | `triage,coder,review,fix,retro,prioritize` | Agent roles to install (used with `--install`) |
| `--inference-region` | | Per-repo GCP inference region override |
| `--fullsend-ref` | | Per-repo fullsend workflow ref override |
| `--mint-url` | | Per-repo mint URL override |
| `--allowed-remote-resources` | | Per-repo allowed remote resources override |
| `--inference-project` | | GCP project ID for inference (install-time only, used with `--install`) |
| `--inference-project-number` | | Numeric GCP project number for WIF (install-time only, used with `--install`) |

Duplicate entries are silently skipped. Glob patterns (e.g. `acme/*`) are allowed as manifest entries.

Expand Down
19 changes: 14 additions & 5 deletions docs/guides/dev/cli-internals.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,6 @@ fullsend
│ │ ├── --forge <type> # Forge type: github or gitlab (required)
│ │ ├── --forge-url <url> # Forge instance URL (required for gitlab)
│ │ ├── --mint-url <url> # Token mint Cloud Run endpoint URL
│ │ ├── --inference-project <id> # Default GCP project for inference
│ │ ├── --inference-region <region> # GCP region for inference (default: us-central1)
│ │ ├── --fullsend-ref <ref> # Pin the fullsend workflow ref (e.g. v0.42.0)
│ │ ├── --force # Overwrite output file if it exists
Expand All @@ -57,15 +56,23 @@ fullsend
│ │ ├── --dry-run # Preview without making changes
│ │ ├── --concurrency <int> # Max parallel operations (1-32, default: 4)
│ │ ├── --roles <list> # Agent roles (default: triage,coder,review,fix,retro,prioritize)
│ │ └── --direct # Push scaffold to default branch (skip PR)
│ │ ├── --direct # Push scaffold to default branch (skip PR)
│ │ ├── --inference-project <id> # GCP project ID for inference (install-time only)
│ │ └── --inference-project-number <num> # Numeric GCP project number for WIF (install-time only)
│ ├── add <repos...> # Add repo entries to manifest
│ │ ├── -f, --manifest <path> # Path to repos.yaml (default: repos.yaml)
│ │ ├── --forge <type> # Forge type: github or gitlab (required)
│ │ ├── --dry-run # Preview without making changes
│ │ ├── --install # Also install fullsend on the added repos
│ │ ├── --concurrency <int> # Max parallel operations (1-32, default: 4)
│ │ ├── --direct # Push scaffold to default branch (skip PR)
│ │ └── --roles <list> # Agent roles to install (used with --install)
│ │ ├── --roles <list> # Agent roles to install (used with --install)
│ │ ├── --inference-region <region> # Per-repo GCP inference region override
│ │ ├── --fullsend-ref <ref> # Per-repo fullsend workflow ref override
│ │ ├── --mint-url <url> # Per-repo mint URL override
│ │ ├── --allowed-remote-resources <list> # Per-repo allowed remote resources override
│ │ ├── --inference-project <id> # GCP project ID for inference (install-time only)
│ │ └── --inference-project-number <num> # Numeric GCP project number for WIF (install-time only)
│ ├── remove <repos...> # Remove repo entries from manifest
│ │ ├── -f, --manifest <path> # Path to repos.yaml (default: repos.yaml)
│ │ ├── --dry-run # Preview without making changes
Expand Down Expand Up @@ -295,9 +302,11 @@ Both per-org and per-repo modes share the same core pipeline. The code follows t
│ │ Phase 6: Set secrets & variables │ │
│ │ │ │
│ │ Both modes write the same credential set: │ │
│ │ Secrets: FULLSEND_GCP_PROJECT_ID │ │
│ │ Secrets (install-time only, not managed by sync): │ │
│ │ FULLSEND_GCP_PROJECT_ID │ │
│ │ FULLSEND_GCP_WIF_PROVIDER │ │
│ │ Variables: FULLSEND_GCP_REGION │ │
│ │ Variables (managed by sync): │ │
│ │ FULLSEND_GCP_REGION │ │
│ │ FULLSEND_MINT_URL │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────┐ │ │
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/getting-started/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ For organizations that separate GCP and GitHub responsibilities across teams, fu
| Platform Admin | `fullsend repos uninstall <repos...>` | Tear down fullsend from repos (workflow, variables, secrets) without modifying manifest |
| Fleet Admin | `fullsend repos status` | Compare `repos.yaml` manifest against actual per-repo state (drift detection) |
| Fleet Admin | `fullsend repos diff` | Show configuration drift between manifest and actual forge state |
| Platform Admin | `fullsend repos sync` | Reconcile configuration drift for installed repos (variables and secrets) |
| Platform Admin | `fullsend repos sync` | Reconcile configuration drift for installed repos (variables only) |
| Platform Admin | `fullsend repos upgrade [repos...]` | Upgrade scaffold shim ref across manifest repos |

| Developer | `fullsend agent add <url-or-path>` | Register an agent in config (URL auto-pinned to commit SHA) |
Expand Down
35 changes: 14 additions & 21 deletions docs/guides/getting-started/repo-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,13 @@ Generate a `repos.yaml` manifest by discovering existing installations:

```bash
fullsend repos init <org> --forge github --all \
--mint-url <MINT_URL> \
--inference-project <GCP_PROJECT>
--mint-url <MINT_URL>
```

For a single repo:

```bash
fullsend repos init <owner/repo> --forge github --inference-project <GCP_PROJECT>
fullsend repos init <owner/repo> --forge github
```

For GitLab, provide the instance URL with `--forge-url` (required for
Expand All @@ -50,16 +49,15 @@ fullsend repos init <org> --forge gitlab \
Instead of `--all`, specify a subset of repos with `--repos`:

```bash
fullsend repos init acme --forge github --repos acme/api,acme/web \
--inference-project <GCP_PROJECT>
fullsend repos init acme --forge github --repos acme/api,acme/web
```

`--repos` and `--all` are mutually exclusive.

If a `repos.yaml` file already exists, pass `--force` to overwrite it:

```bash
fullsend repos init <org> --forge github --all --force --inference-project <GCP_PROJECT>
fullsend repos init <org> --forge github --all --force
```

The command discovers per-repo and per-org installations, extracts
Expand All @@ -79,8 +77,6 @@ version: 1
forge:
github:
mint_url: https://mint.example.com
inference_project: my-project
inference_project_number: "123456789"
inference_region: us-central1
fullsend_ref: v2.5.0
gitlab:
Expand Down Expand Up @@ -221,16 +217,13 @@ state:
fullsend repos diff -f repos.yaml
```

The `diff` command checks **variables and managed secrets only** — it
The `diff` command checks **variables only** — it
compares `FULLSEND_MINT_URL` and `FULLSEND_GCP_REGION` variables against
the manifest and checks that `FULLSEND_GCP_PROJECT_ID` (the only managed
secret) exists. Because GitHub secrets are not readable, diff can only
detect missing secrets — it cannot detect value mismatches. The WIF
provider secret (`FULLSEND_GCP_WIF_PROVIDER`) is write-once at install
time and is not managed by diff/sync. Diff does not check the scaffold
workflow ref (`@ref`). To detect ref drift, use `repos status` (which
includes the ref in its output) or run `repos upgrade --dry-run` to
preview which repos would be upgraded.
the manifest. Secrets (`FULLSEND_GCP_PROJECT_ID`, `FULLSEND_GCP_WIF_PROVIDER`)
are write-once at install time and are not managed by diff/sync. Diff does
not check the scaffold workflow ref (`@ref`). To detect ref drift, use
`repos status` (which includes the ref in its output) or run
`repos upgrade --dry-run` to preview which repos would be upgraded.

Use `--json` for machine-readable output:

Expand Down Expand Up @@ -260,8 +253,9 @@ Use `--json` for machine-readable output:
fullsend repos sync -f repos.yaml --json
```

Sync reconciles variables and secrets. It does **not** touch the scaffold
shim version (`@ref`) — use `repos upgrade` for that.
Sync reconciles variables only. Secrets are written once at install time
and are not managed by sync. Sync does **not** touch the scaffold shim
version (`@ref`) — use `repos upgrade` for that.

### Adding repos

Expand Down Expand Up @@ -364,8 +358,7 @@ can use the following workflow.

```bash
fullsend repos init <org> --forge github --all \
--mint-url <MINT_URL> \
--inference-project <GCP_PROJECT>
--mint-url <MINT_URL>
```

This discovers all enrolled repos and writes `repos.yaml`.
Expand Down
Loading
Loading