Add a Gemini engine that talks to Vertex AI

engine: gemini shells out to the Gemini CLI instead of Codex, so an
adopter can leave Azure. The reusable workflow takes optional Vertex
project, location, and API key, and only requires Azure for Codex.

Author: charlesgreen

.github/workflows/aixgo.yml

@@ -38,9 +38,20 @@ on:
         required: true
         type: string
       azure-openai-endpoint:
-        description: Azure OpenAI endpoint, for example https://resource.openai.azure.com.
-        required: true
+        description: Azure OpenAI endpoint, for example https://resource.openai.azure.com. Required for the default Codex engine; unused when engine is claude or gemini.
+        required: false
         type: string
+        default: ""
+      vertex-project:
+        description: Google Cloud project for Vertex AI. Required when engine is gemini.
+        required: false
+        type: string
+        default: ""
+      vertex-location:
+        description: Vertex AI location, for example us-central1.
+        required: false
+        type: string
+        default: us-central1
       model:
         description: Engine model or deployment name passed to the Aixgo CLI.
         default: gpt-5.4
@@ -53,7 +64,9 @@ on:
         type: string
     secrets:
       azure-openai-api-key:
-        required: true
+        required: false
+      vertex-api-key:
+        required: false
       github-app-private-key:
         required: true
 
@@ -104,6 +117,9 @@ jobs:
         env:
           AIXGO_AZURE_OPENAI_ENDPOINT: ${{ inputs['azure-openai-endpoint'] }}
           AIXGO_AZURE_OPENAI_API_KEY: ${{ secrets['azure-openai-api-key'] }}
+          AIXGO_VERTEX_PROJECT: ${{ inputs['vertex-project'] }}
+          AIXGO_VERTEX_LOCATION: ${{ inputs['vertex-location'] }}
+          AIXGO_VERTEX_API_KEY: ${{ secrets['vertex-api-key'] }}
           AIXGO_GH_APP_CLIENT_ID: ${{ inputs['github-app-client-id'] }}
           AIXGO_GH_APP_PRIVATE_KEY: ${{ secrets['github-app-private-key'] }}
         run: aixgo-code preflight --repo-dir . --actions
@@ -128,13 +144,21 @@ jobs:
         run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
 
       - name: Install Codex CLI
+        if: ${{ inputs['azure-openai-endpoint'] != '' }}
         run: npm install -g @openai/codex@0.146.0
 
+      - name: Install Gemini CLI
+        if: ${{ inputs['vertex-project'] != '' }}
+        run: npm install -g @google/gemini-cli@0.60.0
+
       - name: Run Aixgo
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           AIXGO_AZURE_OPENAI_ENDPOINT: ${{ inputs['azure-openai-endpoint'] }}
           AIXGO_AZURE_OPENAI_API_KEY: ${{ secrets['azure-openai-api-key'] }}
+          AIXGO_VERTEX_PROJECT: ${{ inputs['vertex-project'] }}
+          AIXGO_VERTEX_LOCATION: ${{ inputs['vertex-location'] }}
+          AIXGO_VERTEX_API_KEY: ${{ secrets['vertex-api-key'] }}
           COMMENT_BODY: ${{ inputs['comment-body'] }}
         # --base is explicit because actions/checkout never creates origin/HEAD,
         # which is the CLI's default base. The CLI resolves that case on its own
@@ -198,6 +222,9 @@ jobs:
         env:
           AIXGO_AZURE_OPENAI_ENDPOINT: ${{ inputs['azure-openai-endpoint'] }}
           AIXGO_AZURE_OPENAI_API_KEY: ${{ secrets['azure-openai-api-key'] }}
+          AIXGO_VERTEX_PROJECT: ${{ inputs['vertex-project'] }}
+          AIXGO_VERTEX_LOCATION: ${{ inputs['vertex-location'] }}
+          AIXGO_VERTEX_API_KEY: ${{ secrets['vertex-api-key'] }}
           AIXGO_GH_APP_CLIENT_ID: ${{ inputs['github-app-client-id'] }}
           AIXGO_GH_APP_PRIVATE_KEY: ${{ secrets['github-app-private-key'] }}
         run: aixgo-code preflight --repo-dir . --actions
@@ -222,13 +249,21 @@ jobs:
         run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
 
       - name: Install Codex CLI
+        if: ${{ inputs['azure-openai-endpoint'] != '' }}
         run: npm install -g @openai/codex@0.146.0
 
+      - name: Install Gemini CLI
+        if: ${{ inputs['vertex-project'] != '' }}
+        run: npm install -g @google/gemini-cli@0.60.0
+
       - name: Address review feedback
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           AIXGO_AZURE_OPENAI_ENDPOINT: ${{ inputs['azure-openai-endpoint'] }}
           AIXGO_AZURE_OPENAI_API_KEY: ${{ secrets['azure-openai-api-key'] }}
+          AIXGO_VERTEX_PROJECT: ${{ inputs['vertex-project'] }}
+          AIXGO_VERTEX_LOCATION: ${{ inputs['vertex-location'] }}
+          AIXGO_VERTEX_API_KEY: ${{ secrets['vertex-api-key'] }}
           COMMENT_BODY: ${{ inputs['comment-body'] }}
         run: |
           if [ -n "${COMMENT_BODY}" ]; then

CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes are recorded here and summarized again in the matching
 GitHub release notes for each tag.
 
+## Unreleased
+
+- **Gemini on Vertex AI** (`engine: gemini`). The loop, roles, and gate are
+  unchanged. The adapter shells out to the Gemini CLI (`gemini -p`) and reads
+  `AIXGO_VERTEX_PROJECT`, `AIXGO_VERTEX_LOCATION` (default `us-central1`), and
+  `AIXGO_VERTEX_API_KEY`. Azure credentials are not required on this path.
+- The reusable workflow accepts optional `vertex-project`, `vertex-location`,
+  and `vertex-api-key`, and the Azure endpoint/key are no longer required
+  inputs. A Codex adopter who already passes them is unchanged. A Gemini
+  adopter omits Azure and passes the Vertex values instead. The workflow
+  installs `@google/gemini-cli@0.60.0` when `vertex-project` is set.
+
 ## v0.5.0
 
 **Breaking. The binary is `aixgo-code`, not `aixgo`.** The Aixgo framework's

cmd/aixgo-code/main.go

@@ -30,6 +30,7 @@ import (
 	"github.com/aixgo-dev/code/internal/engine"
 	"github.com/aixgo-dev/code/internal/engine/claude"
 	"github.com/aixgo-dev/code/internal/engine/codex"
+	"github.com/aixgo-dev/code/internal/engine/gemini"
 	forge2 "github.com/aixgo-dev/code/internal/forge"
 	"github.com/aixgo-dev/code/internal/forge/dryrun"
 	forgegh "github.com/aixgo-dev/code/internal/forge/gh"
@@ -115,8 +116,11 @@ flags (both commands):
   --state-dir   where worktrees and the generated config live
 
 environment (engine settings; never committed to a repo):
-  AIXGO_AZURE_OPENAI_ENDPOINT   e.g. https://<resource>.openai.azure.com
+  AIXGO_AZURE_OPENAI_ENDPOINT   e.g. https://<resource>.openai.azure.com (codex)
   AIXGO_AZURE_OPENAI_API_KEY    the key, read by name and never written to disk
+  AIXGO_VERTEX_PROJECT          Google Cloud project (gemini / Vertex)
+  AIXGO_VERTEX_LOCATION         Vertex location, default us-central1
+  AIXGO_VERTEX_API_KEY          Vertex API key, read by name and never written to disk
 `, buildinfo.Version)
 }
 
@@ -165,10 +169,30 @@ var selftestWorkflowTemplate string
 // Azure endpoint when the engine needs one. It is the single implementation:
 // `prepare` calls it before a run, and `preflight` calls it so a workflow can
 // fail early without a second copy of these rules written in shell.
+func usesAzure(cfg *config.Config) bool {
+	if cfg == nil {
+		return true
+	}
+	switch cfg.Engine {
+	case "claude", "gemini":
+		return false
+	}
+	return true
+}
+
 func engineEnv(cfg *config.Config) (string, error) {
 	if cfg != nil && cfg.Engine == "claude" {
 		return "", nil
 	}
+	if cfg != nil && cfg.Engine == "gemini" {
+		if err := requireSet("AIXGO_VERTEX_PROJECT", sectionVariable); err != nil {
+			return "", err
+		}
+		if err := requireSet("AIXGO_VERTEX_API_KEY", sectionSecret); err != nil {
+			return "", err
+		}
+		return "", nil
+	}
 	if err := requireSet("AIXGO_AZURE_OPENAI_ENDPOINT", sectionVariable); err != nil {
 		return "", err
 	}
@@ -246,9 +270,15 @@ func newVCS(self string) *vcsgit.Git {
 // the sandbox start rather than widening it. A run that still cannot sandbox
 // stops and a human finishes the work; it never falls back to running
 // unconfined. See docs/faq.md and the self-test.
-func newRunner(cfg *config.Config, codexHome string) engine.Runner {
+func newRunner(cfg *config.Config, codexHome, model string) engine.Runner {
 	if cfg.Engine == "claude" {
-		return claude.New()
+		return &claude.Runner{Model: model}
+	}
+	if cfg.Engine == "gemini" {
+		if model == "" || model == "gpt-5.4" {
+			model = "gemini-2.5-pro"
+		}
+		return &gemini.Runner{Model: model}
 	}
 	r := codex.New(codexHome)
 	if mode := os.Getenv("AIXGO_SANDBOX"); mode != "" {
@@ -602,7 +632,7 @@ func prepare(name string, argv []string) (*commonFlags, []string, error) {
 	}
 
 	codexHome := filepath.Join(*stateDir, "codex-home")
-	if cfg.Engine != "claude" {
+	if usesAzure(cfg) {
 		if _, err := codex.WriteConfig(codexHome, codex.ProviderConfig{
 			Model:   *model,
 			BaseURL: endpoint + "/openai/v1",
@@ -638,7 +668,7 @@ func prepare(name string, argv []string) (*commonFlags, []string, error) {
 	}
 
 	deps := app.Deps{
-		Runner: newRunner(cfg, codexHome),
+		Runner: newRunner(cfg, codexHome, *model),
 		// Self, when set, filters the agent's own review feedback out of the fix
 		// loop. Empty for local runs, where the operator is a human, not the bot.
 		Forge:                  forgeForLoop,

cmd/aixgo-code/main_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/aixgo-dev/code/internal/domain"
 	"github.com/aixgo-dev/code/internal/engine/claude"
 	"github.com/aixgo-dev/code/internal/engine/codex"
+	"github.com/aixgo-dev/code/internal/engine/gemini"
 	forge2 "github.com/aixgo-dev/code/internal/forge"
 	"github.com/aixgo-dev/code/internal/forge/dryrun"
 	forgefake "github.com/aixgo-dev/code/internal/forge/fake"
@@ -462,6 +463,25 @@ func TestEngineEnvSkipsAzureForClaude(t *testing.T) {
 	}
 }
 
+func TestEngineEnvRequiresVertexForGemini(t *testing.T) {
+	t.Setenv("AIXGO_AZURE_OPENAI_ENDPOINT", "")
+	t.Setenv("AIXGO_AZURE_OPENAI_API_KEY", "")
+	t.Setenv("AIXGO_VERTEX_PROJECT", "")
+	t.Setenv("AIXGO_VERTEX_API_KEY", "")
+	if _, err := engineEnv(&config.Config{Engine: "gemini"}); err == nil || !strings.Contains(err.Error(), "AIXGO_VERTEX_PROJECT") {
+		t.Fatal("gemini without a project must name AIXGO_VERTEX_PROJECT")
+	}
+	t.Setenv("AIXGO_VERTEX_PROJECT", "simplycubed-agents")
+	if _, err := engineEnv(&config.Config{Engine: "gemini"}); err == nil || !strings.Contains(err.Error(), "AIXGO_VERTEX_API_KEY") {
+		t.Fatal("gemini without a key must name AIXGO_VERTEX_API_KEY")
+	}
+	t.Setenv("AIXGO_VERTEX_API_KEY", "k")
+	got, err := engineEnv(&config.Config{Engine: "gemini"})
+	if err != nil || got != "" {
+		t.Fatalf("engineEnv(gemini) = %q, %v", got, err)
+	}
+}
+
 func TestPreflightCmd(t *testing.T) {
 	t.Run("reports ok when config and engine settings are present", func(t *testing.T) {
 		t.Setenv("AIXGO_AZURE_OPENAI_ENDPOINT", "https://r.openai.azure.com")
@@ -487,6 +507,20 @@ func TestPreflightCmd(t *testing.T) {
 		}
 	})
 
+	t.Run("allows gemini with Vertex settings and no Azure", func(t *testing.T) {
+		t.Setenv("AIXGO_AZURE_OPENAI_ENDPOINT", "")
+		t.Setenv("AIXGO_AZURE_OPENAI_API_KEY", "")
+		t.Setenv("AIXGO_VERTEX_PROJECT", "simplycubed-agents")
+		t.Setenv("AIXGO_VERTEX_API_KEY", "k")
+		var out bytes.Buffer
+		if err := preflightCmd([]string{"--repo-dir", repoWithConfigBody(t, "gate: make check\nengine: gemini\nappName: acme-code\n")}, &out); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !strings.Contains(out.String(), "preflight ok") {
+			t.Fatalf("output = %q", out.String())
+		}
+	})
+
 	// The whole point of preflight is naming what is wrong, so each failure
 	// asserts the message identifies the thing the operator has to fix.
 	t.Run("names the missing config", func(t *testing.T) {
@@ -673,6 +707,24 @@ func TestPrepare(t *testing.T) {
 		}
 	})
 
+	t.Run("allows gemini with Vertex settings and skips codex config", func(t *testing.T) {
+		t.Setenv("AIXGO_AZURE_OPENAI_ENDPOINT", "")
+		t.Setenv("AIXGO_AZURE_OPENAI_API_KEY", "")
+		t.Setenv("AIXGO_VERTEX_PROJECT", "simplycubed-agents")
+		t.Setenv("AIXGO_VERTEX_API_KEY", "k")
+		stateDir := t.TempDir()
+		c, _, err := prepare("run", []string{"--repo-dir", repoWithConfigBody(t, "gate: make check\nengine: gemini\nappName: acme-code\n"), "--state-dir", stateDir})
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if _, ok := c.deps.Runner.(*gemini.Runner); !ok {
+			t.Fatalf("expected the Gemini runner, got %#v", c.deps.Runner)
+		}
+		if _, err := os.Stat(filepath.Join(stateDir, "codex-home", "config.toml")); !errors.Is(err, os.ErrNotExist) {
+			t.Fatalf("gemini runs must not render a codex config, stat err = %v", err)
+		}
+	})
+
 	t.Run("rejects an unknown flag", func(t *testing.T) {
 		if _, _, err := prepare("run", []string{"--nope"}); err == nil {
 			t.Fatal("expected an error for an unknown flag")
@@ -1017,15 +1069,30 @@ func TestCommandCmdRejectsABodyFlagWithNoValue(t *testing.T) {
 // Engine selection is a documented config key and had no test. The default
 // matters most: an existing repository must keep the engine it already had.
 func TestNewRunnerSelectsTheEngine(t *testing.T) {
-	if _, ok := newRunner(&config.Config{}, t.TempDir()).(*codex.Runner); !ok {
+	if _, ok := newRunner(&config.Config{}, t.TempDir(), "").(*codex.Runner); !ok {
 		t.Fatal("the default engine must be codex")
 	}
-	if _, ok := newRunner(&config.Config{Engine: "claude"}, t.TempDir()).(*claude.Runner); !ok {
+	if _, ok := newRunner(&config.Config{Engine: "claude"}, t.TempDir(), "").(*claude.Runner); !ok {
 		t.Fatal("engine: claude must select the Claude adapter")
 	}
+	g, ok := newRunner(&config.Config{Engine: "gemini"}, t.TempDir(), "").(*gemini.Runner)
+	if !ok {
+		t.Fatal("engine: gemini must select the Gemini adapter")
+	}
+	if g.Model != "gemini-2.5-pro" {
+		t.Fatalf("gemini default model = %q, want gemini-2.5-pro", g.Model)
+	}
+	g2, _ := newRunner(&config.Config{Engine: "gemini"}, t.TempDir(), "gpt-5.4").(*gemini.Runner)
+	if g2.Model != "gemini-2.5-pro" {
+		t.Fatalf("the Codex default must not be forwarded to Gemini: %q", g2.Model)
+	}
+	g3, _ := newRunner(&config.Config{Engine: "gemini"}, t.TempDir(), "gemini-2.5-flash").(*gemini.Runner)
+	if g3.Model != "gemini-2.5-flash" {
+		t.Fatalf("an explicit gemini model must be kept: %q", g3.Model)
+	}
 	// An unrecognised engine falls back rather than failing later with an
 	// error that says nothing about the cause.
-	if _, ok := newRunner(&config.Config{Engine: "nope"}, t.TempDir()).(*codex.Runner); !ok {
+	if _, ok := newRunner(&config.Config{Engine: "nope"}, t.TempDir(), "").(*codex.Runner); !ok {
 		t.Fatal("an unknown engine must fall back to the default")
 	}
 }
@@ -1034,15 +1101,15 @@ func TestNewRunnerSelectsTheEngine(t *testing.T) {
 // widen it themselves. Nothing in this repository sets it, so the test asserts
 // both that the default is untouched and that an explicit value is honoured.
 func TestNewRunnerHonoursTheSandboxOverride(t *testing.T) {
-	r, ok := newRunner(&config.Config{}, t.TempDir()).(*codex.Runner)
+	r, ok := newRunner(&config.Config{}, t.TempDir(), "").(*codex.Runner)
 	if !ok {
 		t.Fatal("expected the codex runner")
 	}
 	if r.Sandbox != "workspace-write" {
 		t.Fatalf("the sandbox must stay on by default, got %q", r.Sandbox)
 	}
 	t.Setenv("AIXGO_SANDBOX", "read-only")
-	r2, _ := newRunner(&config.Config{}, t.TempDir()).(*codex.Runner)
+	r2, _ := newRunner(&config.Config{}, t.TempDir(), "").(*codex.Runner)
 	if r2.Sandbox != "read-only" {
 		t.Fatalf("an explicit sandbox mode must be honoured, got %q", r2.Sandbox)
 	}

docs/setup.md

@@ -18,7 +18,8 @@ You need:
 - Go installed locally so you can run `go install`
 - `gh` authenticated against the repository you want to onboard
 - write access on that repository
-- an Azure OpenAI endpoint and API key
+- model credentials: an Azure OpenAI endpoint and API key (Codex, the default),
+  or a Vertex AI project and API key (`engine: gemini`)
 
 ## Install and configure
 
@@ -276,6 +277,22 @@ engine: claude
 aixgo-code run owner/repo#123 --repo-dir .
 ```
 
+To use Gemini on Vertex AI instead, set `engine: gemini` and the Vertex
+variables. The reusable workflow installs the Gemini CLI when
+`vertex-project` is passed, and does not need Azure:
+
+```yaml
+gate: make check
+engine: gemini
+```
+
+```sh
+export AIXGO_VERTEX_PROJECT="<project>"
+export AIXGO_VERTEX_LOCATION="us-central1"   # optional, this is the default
+export AIXGO_VERTEX_API_KEY="<key>"
+aixgo-code run owner/repo#123 --repo-dir .
+```
+
 ### GitHub Actions
 
 For the hosted-in-your-GitHub path, the caller workflow in your repository
@@ -293,9 +310,12 @@ passes:
 The reusable workflow installs the CLI, exports the endpoint and key for the
 job, and runs `aixgo-code run` or `aixgo-code address`.
 
-That hosted path is still Codex-on-Azure only. The reusable workflow installs
-the Codex CLI, not the Claude CLI, and its inputs and secrets still require the
-Azure endpoint and API key.
+The hosted path follows `.github/aixgo.yml` `engine:`. Codex (the default)
+still needs the Azure endpoint and key, and the workflow installs the Codex
+CLI. `engine: gemini` needs `vertex-project`, `vertex-location`, and
+`vertex-api-key` instead, and the workflow installs the Gemini CLI. Claude
+is still a local-CLI path; the reusable workflow does not install the Claude
+CLI.
 
 ## Watching it run before it writes