How to Set Up CI/CD Pipelines with agents-cli infra cicd: Complete Guide

The agents-cli infra cicd command provisions complete CI/CD infrastructure including GitHub repositories, Terraform backends, and either GitHub Actions or Google Cloud Build runners in a single operation.

The agents-cli tool from the google/agents-cli repository provides a unified way to deploy agent projects with production-grade CI/CD pipelines. By running agents-cli infra cicd, you can automatically configure staging and production environments, manage secrets, and establish automated testing and deployment workflows without manual infrastructure setup.

What agents-cli infra cicd Provisions

The agents-cli infra cicd command orchestrates six core infrastructure components through approximately 880 lines of logic in src/google/agents/cli/infra/cmd_cicd.py:

• GitHub repository: Creates or configures a remote repository and adds the appropriate Git remote to your local checkout
• Terraform backend: Provisions a GCS bucket (<project>-terraform-state) for remote state management and generates backend.tf configuration files
• CI/CD runner: Auto-detects and configures GitHub Actions or Google Cloud Build based on the presence of wif.tf/github.tf files
• Secrets management: Stores GitHub PATs in Secret Manager when using Cloud Build as the runner
• Terraform variables: Generates env.tfvars with project IDs, regions, repository information, and runner-specific configurations
• Environment provisioning: Runs terraform plan (default) or terraform apply (with --apply) to create staging, production, and optional dev environments

The resulting pipeline automatically runs tests on pull requests, deploys to staging on merges to main, and provides manual approval gates for production deployments.

Architecture and Implementation

Command Registration in main.py

The CLI registers the infra command group lazily in src/google/agents/cli/main.py. The cicd subcommand loads dynamically to avoid heavy imports until needed:

infra_group.add_lazy_command(
    "google.agents.cli.infra.cmd_cicd:setup_cicd",
    "Set up CI/CD pipelines and Terraform infrastructure for your agent project."
)

The setup_cicd() Execution Flow

The setup_cicd() function in src/google/agents/cli/infra/cmd_cicd.py executes an 11-step workflow:

1. Project root detection – chdir_project_root() ensures execution from the repository root
2. Mode determination – Supports interactive prompts or non-interactive flag-based configuration
3. Region resolution – Reads deployment/terraform/cicd/vars/env.tfvars for region values, defaulting to us-east1
4. Runner detection – Analyzes existing Terraform files to choose between GitHub Actions or Cloud Build when --cicd-runner is omitted
5. GitHub CLI validation – Verifies gh installation, authentication status, and required OAuth scopes (repo, workflow)
6. Repository handling – Creates new repositories with --create or validates existing ones, then configures Git remotes
7. Backend initialization – Creates the GCS state bucket and writes backend.tf for both CI/CD and single-project directories
8. Secret provisioning – Creates the github-pat secret in Secret Manager for Cloud Build authentication
9. Variable injection – Populates env.tfvars with project IDs, region, repository metadata, and runner flags
10. Terraform execution – Runs terraform plan or terraform apply across the CI/CD and optional dev configurations
11. Summary output – Displays repository URLs, runner dashboard links, and state file locations

Helper utilities in src/google/agents/cli/infra/_cicd_utils.py provide the ProjectConfig dataclass, command runners, and GitHub connection logic used throughout this flow.

Prerequisites

Before running agents-cli infra cicd, ensure you have:

• Python 3.11+ with uv or pip installed
• Git and GitHub CLI (gh) installed and authenticated (gh auth login)
• Google Cloud projects for staging, production, and optionally a dedicated CICD project
• IAM permissions to create GCS buckets, Secret Manager secrets, Cloud Build connections, and service accounts

Step-by-Step Setup Guide

Step 1: Install the CLI

Install the agents-cli tool using uvx:

uvx google-agents-cli setup

Step 2: Verify GitHub CLI Authentication

Ensure GitHub CLI has the required scopes:

gh auth status
gh auth refresh -s repo -s workflow

Step 3: Run the Command in Preview Mode

Execute the command without --apply to preview changes:

agents-cli infra cicd \
  --staging-project my-staging-project \
  --prod-project my-production-project \
  --cicd-project my-cicd-project \
  --repository-name my-agent-repo \
  --interactive

This generates env.tfvars, backend.tf, and displays the Terraform plan without applying changes.

Step 4: Apply the Infrastructure

Add the --apply flag to provision resources:

agents-cli infra cicd \
  --staging-project my-staging-project \
  --prod-project my-production-project \
  --cicd-project my-cicd-project \
  --repository-name my-agent-repo \
  --apply \
  --interactive

Step 5: Push Your Code

After successful provisioning, push to trigger the pipeline:

git add .
git commit -m "Initial commit"
git push -u origin main

Available Command Flags

Flag	Description
--dev-project	Deploy a single-project development environment
--cicd-runner	Force specific runner: google_cloud_build or github_actions
--github-pat	Provide GitHub Personal Access Token (required for Cloud Build in CI)
--github-app-installation-id	App installation ID for Cloud Build GitHub connections
--local-state	Use local Terraform state instead of GCS backend
--create	Create a new GitHub repository (default uses existing)
--apply	Execute terraform apply instead of just terraform plan
--debug	Enable verbose logging for troubleshooting

Programmatic Usage and Automation

Python API

Import and execute the setup directly from Python:

from google.agents.cli.infra.cmd_cicd import setup_cicd

setup_cicd(
    dev_project=None,
    staging_project="my-staging-project",
    prod_project="my-prod-project",
    cicd_project="my-cicd-project",
    region=None,  # Auto-detects from env.tfvars or defaults to us-east1

    repository_name="my-agent-repo",
    repository_owner=None,  # Prompts if interactive=True

    host_connection_name=None,
    github_pat=None,
    github_app_installation_id=None,
    local_state=False,
    debug=False,
    interactive=True,
    create_repository=False,
    apply_changes=False,  # Set True to apply rather than plan

    cicd_runner=None,  # Auto-detects from wif.tf/github.tf

)

Bash Automation Script

Automate provisioning in CI environments:

#!/usr/bin/env bash
set -euo pipefail

# Ensure GitHub CLI is logged in

gh auth status || gh auth login

# Preview changes

agents-cli infra cicd \
  --staging-project "$STAGING_PROJECT" \
  --prod-project "$PROD_PROJECT" \
  --cicd-project "$CICD_PROJECT" \
  --repository-name "$REPO_NAME" \
  --interactive

# Confirm and apply

read -p "Apply infrastructure changes? (y/N) " answer
if [[ "$answer" =~ ^[Yy]$ ]]; then
  agents-cli infra cicd \
    --staging-project "$STAGING_PROJECT" \
    --prod-project "$PROD_PROJECT" \
    --cicd-project "$CICD_PROJECT" \
    --repository-name "$REPO_NAME" \
    --apply \
    --interactive
fi

Key Source Files

Understanding these files helps troubleshoot and extend the functionality:

File	Purpose
src/google/agents/cli/infra/cmd_cicd.py	Implements the setup_cicd() function handling argument parsing, validation, and orchestration
src/google/agents/cli/infra/_cicd_utils.py	Provides ProjectConfig, run_command(), and GitHub/Cloud Build connection utilities
src/google/agents/cli/main.py	Registers the infra command group and lazy-loads the CICD module
deployment/terraform/cicd/	Contains Terraform configurations for Cloud Build triggers, Workload Identity Federation, and IAM bindings
docs/src/guide/cicd.md	User-facing documentation describing pipeline workflows

Summary

• The agents-cli infra cicd command provisions complete CI/CD infrastructure through a single CLI operation
• It supports both GitHub Actions and Google Cloud Build runners, auto-detecting based on existing Terraform files
• The command generates env.tfvars and backend.tf files to standardize Terraform configuration across environments
• Use --apply to create resources; without it, the command runs in preview/plan mode
• All orchestration logic lives in src/google/agents/cli/infra/cmd_cicd.py with utilities in _cicd_utils.py

Frequently Asked Questions

What CI/CD runners does agents-cli infra cicd support?

The command supports GitHub Actions and Google Cloud Build. It auto-detects the appropriate runner by checking for the presence of wif.tf (Workload Identity Federation) and github.tf files in your repository. You can override auto-detection using the --cicd-runner flag with either google_cloud_build or github_actions as the value.

Where does agents-cli infra cicd store Terraform state?

By default, the command creates a GCS bucket named <project>-terraform-state in your CICD project and configures remote state backends in backend.tf files. If you prefer local state storage, use the --local-state flag, which skips GCS bucket creation and configures Terraform to use local state files instead.

Can I use agents-cli infra cicd with existing GitHub repositories?

Yes. By default, the command validates and configures existing repositories. Use the --create flag only if you want the CLI to create a new GitHub repository via the GitHub API. The command automatically adds the appropriate Git remote to your local checkout regardless of whether the repo is new or existing.

How do I switch from preview mode to actually applying changes?

The command defaults to preview mode, running terraform plan and generating configuration files without creating cloud resources. To apply the infrastructure, add the --apply flag to your command. This executes terraform apply for both the CI/CD configuration and any single-project dev environment specified with --dev-project.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}