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

> Easily set up CI/CD pipelines with agents-cli infra cicd. Provision GitHub repos, Terraform backends, and build runners like GitHub Actions or Cloud Build in one go.

- Repository: [Google/agents-cli](https://github.com/google/agents-cli)
- Tags: how-to-guide
- Published: 2026-07-01

---

**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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/main.py). The `cicd` subcommand loads dynamically to avoid heavy imports until needed:

```python
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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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`:

```bash
uvx google-agents-cli setup

```

### Step 2: Verify GitHub CLI Authentication

Ensure GitHub CLI has the required scopes:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```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:

```bash
#!/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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/infra/_cicd_utils.py) | Provides `ProjectConfig`, `run_command()`, and GitHub/Cloud Build connection utilities |
| [`src/google/agents/cli/main.py`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/infra/cmd_cicd.py) with utilities in [`_cicd_utils.py`](https://github.com/google/agents-cli/blob/main/_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`.