Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 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/ADRs/0033-per-repo-installation-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,7 @@ Per-org-only flags (`--mint-project`, `--mint-region`, `--public`, etc.) are rej
4. Commits all scaffold files to the target repo via the GitHub API.
5. Sets repository variables (`FULLSEND_MINT_URL`, `FULLSEND_GCP_REGION`, `FULLSEND_GCP_AUTH_MODE`).
6. Sets repository secrets (`FULLSEND_GCP_PROJECT_ID`, and either WIF credentials or SA key JSON depending on `--gcp-auth-mode`).
7. In WIF mode, auto-provisions WIF pool/provider/service account if `--gcp-wif-provider` is omitted.
7. Auto-provisions WIF pool/provider if `--inference-wif-provider` is omitted.

Per-repo install requires only `repo` and `workflow` OAuth scopes (no `admin:org`).

Expand Down
18 changes: 7 additions & 11 deletions docs/guides/admin/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The table below lists every scope the installer may request and why. You are nev
| `admin:org` | install, uninstall, analyze | Manage organization-level Actions variables (the mint URL) |
| `delete_repo` | uninstall | Delete the `.fullsend` config repository |

The `--gcp-region` flag is required when `--gcp-project` is set. Use `global` for the broadest model availability. For a list of all available regions, see the [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude#regions).
The `--inference-region` flag defaults to `global` for the broadest model availability. For a list of all available regions, see the [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude#regions). The `--inference-wif-provider` flag is optional — when omitted, the installer auto-provisions WIF infrastructure.

## 1. Set up inference authentication with GCP Agent Platform

Expand Down Expand Up @@ -94,13 +94,13 @@ If the installer fails partway through, run `fullsend admin uninstall "$ORG_NAME

```bash
fullsend admin install "$ORG_NAME" \
--gcp-project "$GCP_PROJECT" \
--gcp-region global \
--gcp-wif-provider "$WIF_PROVIDER" \
--inference-project "$GCP_PROJECT" \
--mint-project "$GCP_PROJECT"
```

`--mint-project` specifies the GCP project where the OIDC token mint Cloud Function is deployed. It can be the same project as `--gcp-project` or a separate project. The installer automatically provisions a Cloud Function, WIF pool (`fullsend-pool`), WIF provider (`github-oidc`), and Secret Manager secrets in the mint project. A service account (`fullsend-mint`) is also created as the Cloud Function's runtime identity to access Secret Manager — this is internal infrastructure and does not require any admin setup.
When `--inference-wif-provider` is omitted, the installer auto-discovers or creates WIF infrastructure (pool `fullsend-pool`, provider `github-oidc`) in the inference project. Pass `--inference-wif-provider "$WIF_PROVIDER"` to use a pre-existing provider instead.

`--mint-project` specifies the GCP project where the OIDC token mint Cloud Function is deployed. It can be the same project as `--inference-project` or a separate project. The installer automatically provisions a Cloud Function, WIF pool (`fullsend-pool`), WIF provider (`github-oidc`), and Secret Manager secrets in the mint project. A service account (`fullsend-mint`) is also created as the Cloud Function's runtime identity to access Secret Manager — this is internal infrastructure and does not require any admin setup.

Additional mint flags:

Expand All @@ -122,9 +122,7 @@ A single token mint can serve multiple GitHub organizations. The first org deplo

```bash
fullsend admin install "$FIRST_ORG" \
--gcp-project "$GCP_PROJECT" \
--gcp-region global \
--gcp-wif-provider "$WIF_PROVIDER" \
--inference-project "$GCP_PROJECT" \
--mint-project "$GCP_PROJECT" \
--public
```
Expand All @@ -135,9 +133,7 @@ The `--public` flag creates GitHub Apps as public unlisted — they won't appear

```bash
fullsend admin install "$ADDITIONAL_ORG" \
--gcp-project "$GCP_PROJECT" \
--gcp-region global \
--gcp-wif-provider "$WIF_PROVIDER" \
--inference-project "$GCP_PROJECT" \
--mint-url "$MINT_URL"
```

Expand Down
11 changes: 5 additions & 6 deletions docs/plans/vertex-inference-provisioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,13 +168,12 @@ Test all three modes using a fake GCPClient and forge.FakeClient:
#### 3a. `internal/cli/admin.go` — New flags and wiring

Add flags to `install` command:
- `--gcp-project` (string): GCP project ID
- `--gcp-service-account` (string): existing SA name (optional)
- `--gcp-credentials-file` (string): path to pre-made key JSON file (optional)
- `--inference-project` (string): GCP project ID for inference
- `--inference-region` (string, default: `global`): GCP region for inference
- `--inference-wif-provider` (string, optional): WIF provider resource name (auto-provisioned if omitted)

The flags determine which mode is used. Validation:
- If `--gcp-credentials-file` is set, `--gcp-service-account` is ignored (mode 3).
- `--gcp-project` is required when any GCP flag is provided.
Validation:
- `--inference-project` is required when `--inference-region` or `--inference-wif-provider` is provided.

Wire the inference provider into `buildLayerStack()` — add `inference.Provider` parameter.

Expand Down
88 changes: 50 additions & 38 deletions internal/cli/admin.go
Original file line number Diff line number Diff line change
Expand Up @@ -133,9 +133,9 @@ func newInstallCmd() *cobra.Command {
var vendorBinary bool
var enrollAllFlag bool
var enrollNoneFlag bool
var gcpProject string
var gcpRegion string
var gcpWIFProvider string
var inferenceProject string
var inferenceRegion string
var inferenceWIFProvider string
var mintProvider string
var mintProject string
var mintRegion string
Expand Down Expand Up @@ -168,8 +168,8 @@ Per-repo mode (argument is owner/repo, e.g. "acme/widget"):
return fmt.Errorf("--%s is only valid for per-org installation (fullsend admin install <org>)", name)
}
}
return runPerRepoInstall(cmd.Context(), arg, agents, mintURL, gcpRegion,
gcpProject, gcpWIFProvider,
return runPerRepoInstall(cmd.Context(), arg, agents, mintURL, inferenceRegion,
inferenceProject, inferenceWIFProvider,
scaffoldCustomized, dryRun)
}

Expand Down Expand Up @@ -217,30 +217,45 @@ Per-repo mode (argument is owner/repo, e.g. "acme/widget"):
return fmt.Errorf("--skip-mint-deploy and --force-mint-deploy are mutually exclusive")
}

// Validate GCP flag dependencies.
if gcpProject == "" && (gcpRegion != "" || gcpWIFProvider != "") {
return fmt.Errorf("--gcp-wif-provider and --gcp-region require --gcp-project to be set")
// Validate inference flag dependencies.
if inferenceProject == "" && (cmd.Flags().Changed("inference-region") || inferenceWIFProvider != "") {
return fmt.Errorf("--inference-wif-provider and --inference-region require --inference-project to be set")
}
if gcpProject != "" && gcpRegion == "" {
return fmt.Errorf("--gcp-region is required when --gcp-project is set")
}
if gcpProject != "" && gcpWIFProvider == "" {
return fmt.Errorf("--gcp-wif-provider is required when --gcp-project is set")

// Auto-provision WIF when not explicitly given (idempotent: safe to re-run).
if inferenceProject != "" && inferenceWIFProvider == "" {
if dryRun {
printer.StepInfo("Would auto-provision WIF provider in project " + inferenceProject)
} else {
printer.StepStart("Provisioning WIF infrastructure for inference")
gcpClient := gcf.NewLiveGCFClient()
provisioner := gcf.NewProvisioner(gcf.Config{
ProjectID: inferenceProject,
GitHubOrgs: []string{org},
}, gcpClient)
inferenceWIFProvider, err = provisioner.ProvisionWIF(ctx)
if err != nil {
printer.StepFail("WIF provisioning failed")
return fmt.Errorf("provisioning WIF for inference: %w", err)
}
printer.StepDone("WIF infrastructure ready")
printer.StepInfo("IAM policy changes may take up to 7 minutes to propagate")
}
}

// Build inference provider from GCP flags.
// Build inference provider from flags.
var inferenceProvider inference.Provider
var inferenceProviderName string
if gcpProject != "" {
if inferenceProject != "" {
vcfg := vertex.Config{
ProjectID: gcpProject,
Region: gcpRegion,
WIFProvider: gcpWIFProvider,
ProjectID: inferenceProject,
Region: inferenceRegion,
WIFProvider: inferenceWIFProvider,
}
inferenceProvider = vertex.New(vcfg)
inferenceProviderName = "vertex"
} else {
// Preserve existing inference config if no GCP flags provided.
// Preserve existing inference config if no inference flags provided.
inferenceProviderName = loadExistingInferenceProvider(ctx, client, org)
}

Expand Down Expand Up @@ -328,9 +343,9 @@ Per-repo mode (argument is owner/repo, e.g. "acme/widget"):
cmd.Flags().BoolVar(&vendorBinary, "vendor-fullsend-binary", false, "cross-compile and upload the fullsend binary into .fullsend/bin/ for development iteration")
cmd.Flags().BoolVar(&enrollAllFlag, "enroll-all", false, "enroll all repositories without prompting")
cmd.Flags().BoolVar(&enrollNoneFlag, "enroll-none", false, "skip repository enrollment without prompting")
cmd.Flags().StringVar(&gcpProject, "gcp-project", "", "GCP project ID for Vertex AI inference")
cmd.Flags().StringVar(&gcpRegion, "gcp-region", "", "GCP region for Vertex AI (e.g. global, required with --gcp-project)")
cmd.Flags().StringVar(&gcpWIFProvider, "gcp-wif-provider", "", "full Workload Identity Federation provider resource name (e.g. projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER)")
cmd.Flags().StringVar(&inferenceProject, "inference-project", "", "GCP project ID for inference (Vertex AI)")
cmd.Flags().StringVar(&inferenceRegion, "inference-region", "global", "GCP region for inference (default: global)")
cmd.Flags().StringVar(&inferenceWIFProvider, "inference-wif-provider", "", "WIF provider resource name (optional; auto-provisioned if omitted)")
cmd.Flags().StringVar(&mintProvider, "mint-provider", "gcf", "token mint provider (gcf)")
cmd.Flags().StringVar(&mintProject, "mint-project", "", "cloud project for token mint (e.g. GCP project ID)")
cmd.Flags().StringVar(&mintRegion, "mint-region", "us-central1", "cloud region for token mint")
Expand All @@ -345,8 +360,8 @@ Per-repo mode (argument is owner/repo, e.g. "acme/widget"):
return cmd
}

func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, gcpRegion,
gcpProject, gcpWIFProvider string,
func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, inferenceRegion,
inferenceProject, inferenceWIFProvider string,
scaffoldCustomized, dryRun bool) error {
if strings.Contains(repoFullName, "://") || strings.HasPrefix(repoFullName, "www.") {
return fmt.Errorf("expected owner/repo format, got a URL — use just the owner/repo portion (e.g. acme/widget)")
Expand Down Expand Up @@ -374,11 +389,8 @@ func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, gcpRe
}
return fmt.Errorf("--mint-url must be a valid HTTPS URL (got scheme=%q)", scheme)
}
if gcpRegion == "" {
return fmt.Errorf("--gcp-region is required for per-repo installation")
}
if gcpProject == "" {
return fmt.Errorf("--gcp-project is required for per-repo installation")
if inferenceProject == "" {
return fmt.Errorf("--inference-project is required for per-repo installation")
}
roles, err := parseAgentRoles(agents)
if err != nil {
Expand Down Expand Up @@ -435,19 +447,19 @@ func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, gcpRe
}
}

needsWIFProvision := gcpWIFProvider == ""
needsWIFProvision := inferenceWIFProvider == ""

repoVars := map[string]string{
"FULLSEND_MINT_URL": mintURL,
"FULLSEND_GCP_REGION": gcpRegion,
"FULLSEND_GCP_REGION": inferenceRegion,
}

if dryRun {
printer.StepInfo("Dry run — no changes will be made")
printer.Blank()
if needsWIFProvision {
printer.StepInfo("Would provision WIF infrastructure in GCP project " + gcpProject)
printer.StepInfo(fmt.Sprintf(" Service account: fullsend-mint@%s.iam.gserviceaccount.com", gcpProject))
printer.StepInfo("Would provision WIF infrastructure in GCP project " + inferenceProject)
printer.StepInfo(fmt.Sprintf(" Service account: fullsend-mint@%s.iam.gserviceaccount.com", inferenceProject))
printer.StepInfo(" WIF pool: fullsend-pool")
printer.StepInfo(fmt.Sprintf(" WIF provider: %s", gcf.BuildRepoProviderID(owner, repo)))
printer.StepInfo(fmt.Sprintf(" Repo restriction: %s/%s", owner, repo))
Expand Down Expand Up @@ -476,12 +488,12 @@ func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, gcpRe
if needsWIFProvision {
printer.StepStart("Provisioning WIF infrastructure")
provisioner := gcf.NewProvisioner(gcf.Config{
ProjectID: gcpProject,
ProjectID: inferenceProject,
GitHubOrgs: []string{owner},
Repo: owner + "/" + repo,
}, gcf.NewLiveGCFClient())
var provErr error
gcpWIFProvider, provErr = provisioner.ProvisionWIF(ctx)
inferenceWIFProvider, provErr = provisioner.ProvisionWIF(ctx)
if provErr != nil {
printer.StepFail("WIF provisioning failed")
return fmt.Errorf("provisioning WIF: %w", provErr)
Expand All @@ -492,8 +504,8 @@ func runPerRepoInstall(ctx context.Context, repoFullName, agents, mintURL, gcpRe
}

repoSecrets := map[string]string{
"FULLSEND_GCP_PROJECT_ID": gcpProject,
"FULLSEND_GCP_WIF_PROVIDER": gcpWIFProvider,
"FULLSEND_GCP_PROJECT_ID": inferenceProject,
"FULLSEND_GCP_WIF_PROVIDER": inferenceWIFProvider,
}

printer.StepStart("Writing per-repo scaffold files")
Expand Down Expand Up @@ -1352,7 +1364,7 @@ func printAnalysis(ctx context.Context, stack *layers.Stack, printer *ui.Printer

// loadExistingInferenceProvider reads the inference provider name from
// an existing config.yaml in .fullsend, if available. This prevents
// re-installs without --gcp-project from silently erasing the inference section.
// re-installs without --inference-project from silently erasing the inference section.
func loadExistingInferenceProvider(ctx context.Context, client forge.Client, org string) string {
data, err := client.GetFileContent(ctx, org, forge.ConfigRepoName, "config.yaml")
if err != nil {
Expand Down
47 changes: 24 additions & 23 deletions internal/cli/admin_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,20 @@ func TestInstallCmd_Flags(t *testing.T) {
require.NotNil(t, vendorBinaryFlag, "expected --vendor-fullsend-binary flag")
assert.Equal(t, "false", vendorBinaryFlag.DefValue)

wifProviderFlag := cmd.Flags().Lookup("gcp-wif-provider")
require.NotNil(t, wifProviderFlag, "expected --gcp-wif-provider flag")
inferenceProjectFlag := cmd.Flags().Lookup("inference-project")
require.NotNil(t, inferenceProjectFlag, "expected --inference-project flag")

inferenceRegionFlag := cmd.Flags().Lookup("inference-region")
require.NotNil(t, inferenceRegionFlag, "expected --inference-region flag")
assert.Equal(t, "global", inferenceRegionFlag.DefValue)

inferenceWIFProviderFlag := cmd.Flags().Lookup("inference-wif-provider")
require.NotNil(t, inferenceWIFProviderFlag, "expected --inference-wif-provider flag")

// Old GCP flags should have been removed.
assert.Nil(t, cmd.Flags().Lookup("gcp-project"), "--gcp-project flag should have been renamed to --inference-project")
assert.Nil(t, cmd.Flags().Lookup("gcp-region"), "--gcp-region flag should have been renamed to --inference-region")
assert.Nil(t, cmd.Flags().Lookup("gcp-wif-provider"), "--gcp-wif-provider flag should have been renamed to --inference-wif-provider")

// --gcp-wif-sa-email removed (direct WIF, no intermediate SA)
wifSAEmailFlag := cmd.Flags().Lookup("gcp-wif-sa-email")
Expand Down Expand Up @@ -96,39 +108,39 @@ func TestInstallCmd_Flags(t *testing.T) {

func TestInstallCmd_PerRepoRequiresMintURL(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--gcp-region", "us-central1"})
cmd.SetArgs([]string{"admin", "install", "acme/widget"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "--mint-url is required for per-repo installation")
}

func TestInstallCmd_PerRepoRequiresGCPRegion(t *testing.T) {
func TestInstallCmd_PerRepoRequiresInferenceProject(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--mint-url", "https://mint.example.com"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "--gcp-region is required for per-repo installation")
assert.Contains(t, err.Error(), "--inference-project is required for per-repo installation")
}

func TestInstallCmd_PerRepoRejectsInvalidFormat(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/", "--mint-url", "https://mint.example.com", "--gcp-region", "us-central1"})
cmd.SetArgs([]string{"admin", "install", "acme/", "--mint-url", "https://mint.example.com", "--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "repo must be in owner/repo format")
}

func TestInstallCmd_PerRepoRejectsMultiSlash(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/team/repo", "--mint-url", "https://mint.example.com", "--gcp-region", "us-central1"})
cmd.SetArgs([]string{"admin", "install", "acme/team/repo", "--mint-url", "https://mint.example.com", "--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "invalid repo name")
}

func TestInstallCmd_PerRepoRejectsNonHTTPSMintURL(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--mint-url", "http://mint.example.com", "--gcp-region", "us-central1"})
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--mint-url", "http://mint.example.com", "--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "--mint-url must be a valid HTTPS URL")
Expand All @@ -144,22 +156,12 @@ func TestInstallCmd_PerOrgRejectsPerRepoFlags(t *testing.T) {

func TestInstallCmd_PerRepoRejectsPerOrgFlags(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--mint-url", "https://mint.example.com", "--gcp-region", "us-central1", "--mint-project", "my-project"})
cmd.SetArgs([]string{"admin", "install", "acme/widget", "--mint-url", "https://mint.example.com", "--inference-project", "my-project", "--mint-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "--mint-project is only valid for per-org installation")
}

func TestInstallCmd_PerRepoRequiresGCPProject(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "acme/widget",
"--mint-url", "https://mint.example.com",
"--gcp-region", "us-central1"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "--gcp-project is required for per-repo installation")
}

func TestParseAgentRoles(t *testing.T) {
tests := []struct {
input string
Expand Down Expand Up @@ -1067,8 +1069,7 @@ func TestInstallCmd_PerRepoRejectsInvalidRole(t *testing.T) {
cmd.SetArgs([]string{"admin", "install", "acme/widget",
"--agents", "triage,INVALID",
"--mint-url", "https://mint.example.com",
"--gcp-region", "us-central1",
"--gcp-project", "my-project"})
"--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "invalid role name")
Expand All @@ -1078,7 +1079,7 @@ func TestInstallCmd_PerRepoRejectsOwnerWithDots(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", "my.org/widget",
"--mint-url", "https://mint.example.com",
"--gcp-region", "us-central1"})
"--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "invalid owner name")
Expand All @@ -1098,7 +1099,7 @@ func TestInstallCmd_PerRepoRejectsURL(t *testing.T) {
cmd := newRootCmd()
cmd.SetArgs([]string{"admin", "install", tc.input,
"--mint-url", "https://mint.example.com",
"--gcp-region", "us-central1"})
"--inference-project", "my-project"})
err := cmd.Execute()
require.Error(t, err)
assert.Contains(t, err.Error(), "expected owner/repo format, got a URL")
Expand Down
Loading