cicd-pipeline

Production Deployment — CI/CD Pipeline

**Best for:** Production applications, teams requiring staging → production promotion.

**Prerequisites:** 1. Project must NOT be in a gitignored folder 2. User must provide staging and production GCP project IDs 3. GitHub repository name and owner

**Steps:** 1. If prototype, first add Terraform/CI-CD files using the Agents CLI (see `/google-agents-cli-scaffold` for full options):

   agents-cli scaffold enhance . --cicd-runner github_actions

2. Ensure you're logged in to GitHub CLI:

   gh auth login  # (skip if already authenticated)

3. Run infra cicd:

   agents-cli infra cicd \
     --staging-project YOUR_STAGING_PROJECT \
     --prod-project YOUR_PROD_PROJECT \
     --repository-name YOUR_REPO_NAME \
     --create

4. Push code to trigger deployments

Key `infra cicd` Flags

| Flag | Required | Description | |------|----------|-------------| | `--staging-project` | Yes | GCP project ID for staging environment | | `--prod-project` | Yes | GCP project ID for production environment | | `--repository-name` | Yes | GitHub repository name | | `--create` | No | Create a new GitHub repository. Omit to use an existing one (the command verifies the repository exists either way) | | `--repository-owner` | No | GitHub repo owner. Defaults to your `gh` CLI user — set this when creating under (or pointing to) a GitHub organization or another user's account | | `--cicd-project` | No | Separate GCP project for CI/CD infrastructure. Defaults to prod project | | `--region` | No | GCP region. Auto-detected or defaults to `us-east1` | | `--local-state` | No | Store Terraform state locally instead of in GCS (see `references/terraform-patterns.md`) |

Run `agents-cli infra cicd --help` for the full flag reference (Cloud Build options, dev project, region, etc.).

Choosing a CI/CD Runner

| Runner | Pros | Cons | |--------|------|------| | **github_actions** (Default) | No PAT needed, uses `gh auth`, WIF-based, fully automated | Requires GitHub CLI authentication | | **google_cloud_build** | Native GCP integration | Requires `--github-pat` and `--github-app-installation-id` in programmatic mode (or `-i` for interactive OAuth flow) |

Cloud Build Example

agents-cli infra cicd \
  --staging-project YOUR_STAGING_PROJECT \
  --prod-project YOUR_PROD_PROJECT \
  --repository-name YOUR_REPO_NAME \
  --create \
  --github-pat YOUR_PAT \
  --github-app-installation-id YOUR_APP_ID

How Authentication Works (WIF)

Both runners use **Workload Identity Federation (WIF)** — GitHub/Cloud Build OIDC tokens are trusted by a GCP Workload Identity Pool, which grants `cicd_runner_sa` impersonation. No long-lived service account keys needed. Terraform in `infra cicd` creates the pool, provider, and SA bindings automatically. If auth fails, re-run `terraform apply` in the CI/CD Terraform directory.

CI/CD Pipeline Stages

The pipeline has three stages:

1. **CI (PR checks)** — Triggered on pull request. Runs unit and integration tests. 2. **Staging CD** — Triggered on merge to `main`. Builds container, deploys to staging, runs load tests. > **Path filter:** Staging CD only triggers when relevant paths change — the agent directory (`app/**` by default), `tests/**`, `deployment/**`, or `uv.lock`. The first push after `infra cicd` won't trigger staging CD unless one of these changes. If nothing happens after pushing, this is why. 3. **Production CD** — Triggered after successful staging deploy via `workflow_run`. Might require **manual approval** before deploying to production. > **Approving:** Go to GitHub Actions → the production workflow run → click "Review deployments" → approve the pending `production` environment. This is GitHub's environment protection rules, not a custom mechanism.

**IMPORTANT**: `infra cicd` creates infrastructure but doesn't deploy automatically. Terraform configures all required GitHub secrets and variables (WIF credentials, project IDs, service accounts). Push code to trigger the pipeline:

git add . && git commit -m "Initial agent implementation"
git push origin main

To approve production deployment:

# GitHub Actions: Approve via repository Actions tab (environment protection rules)

# Cloud Build: Find pending build and approve
gcloud builds list --project=PROD_PROJECT --region=REGION --filter="status=PENDING"
gcloud builds approve BUILD_ID --project=PROD_PROJECT

Non-GitHub Providers (GitLab, Bitbucket, etc.)

The `agents-cli infra cicd` command only supports GitHub. It requires the `gh` CLI, uses the Terraform `github` provider, and both CI/CD runners (GitHub Actions, Cloud Build) assume a GitHub source repo.

For other git providers, use the scaffolded Terraform as a starting point: 1. Run `agents-cli scaffold enhance` to generate the Terraform and CI/CD files 2. Replace the `github` provider and resources in `deployment/terraform/cicd/` with your provider's equivalents 3. Adapt the CI/CD pipeline files (e.g., replace `.github/workflows/` with `.gitlab-ci.yml`) 4. Run `terraform apply` directly instead of `agents-cli infra cicd`