cicaddy-github 0.8.0

GitHub Actions plugin for cicaddy AI agent framework

cicaddy-action

GitHub Action that wraps cicaddy for running AI agent tasks in GitHub Actions workflows.

Features

• AI-powered PR reviews with optional Context7 MCP for up-to-date library documentation
• Sub-agent delegation for parallel specialized reviews (security, architecture, performance, etc.)
• Go dependency impact analysis for Go dependency update PRs with risk classification
• Changelog report generation from git tag diffs and release notes
• Multiple AI providers: Gemini, OpenAI, Claude, Claude via Vertex AI, Gemini via Vertex AI
• Secret redaction via detect-secrets for safe public outputs
• DSPy YAML task definitions for customizable analysis workflows

Prerequisites

The examples below use Vertex AI with Workload Identity Federation (WIF) for keyless authentication. WIF eliminates static secrets — GitHub mints a short-lived OIDC token per workflow run and GCP exchanges it for temporary credentials scoped to that job.

One-time GCP setup required:

1. Create a Workload Identity Pool and OIDC provider
2. Create a service account with roles/aiplatform.user
3. Bind the pool to the service account scoped to your specific repository (the --member flag must use a principalSet with attribute.repository/OWNER/REPO to enforce repository-level isolation)

Store the resulting values as GitHub repository variables (vars.GCP_WIF_PROVIDER, vars.GCP_SERVICE_ACCOUNT, vars.GCP_PROJECT_ID).

See docs/providers.md for the full gcloud setup commands, authentication method comparison (WIF vs SA key vs API key), and alternative provider configurations (OpenAI, Claude, standalone Gemini API key).

Quick Start

AI PR Review

This example uses the pull_request trigger, which works for in-repo PRs (branches pushed to the same repository). For fork PR support, see .github/workflows/pr-review.yml which uses pull_request_target with a safe-to-review label gate.

name: PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write       # Required for Workload Identity Federation
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - uses: redhat-community-ai-tools/cicaddy-action@main
        with:
          ai_provider: gemini-vertex
          ai_model: gemini-3.5-flash
          google_cloud_project: ${{ vars.GCP_PROJECT_ID }}
          task_file: tasks/pr_review.yml
          post_pr_comment: 'true'
          submit_review: 'true'
          inline_review_comments: 'true'
          delegation_mode: auto
          delegation_verify_findings: 'true'

Fork PRs: The pull_request event cannot mint OIDC tokens for PRs from forks, so WIF authentication will fail. To support fork PRs, use pull_request_target with a label gate (e.g. safe-to-review) to prevent unauthorized code execution. See .github/workflows/pr-review.yml for an example and docs/providers.md for security details.

Sub-Agent Delegation: When DELEGATION_MODE is set to auto, the agent uses AI-powered triage to analyze the PR diff and spawns specialized sub-agents in parallel (e.g., code quality, security, performance). Each sub-agent runs with a focused scope and reduced token budget, and their results are aggregated into a single unified review. This produces deeper, more structured reviews compared to single-agent mode. Set DELEGATION_MODE to none to use a single agent instead. See docs/delegation.md for details.

Changelog Report on Release

name: Generate Changelog

on:
  release:
    types: [published]

jobs:
  changelog:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write       # Required for Workload Identity Federation
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - uses: redhat-community-ai-tools/cicaddy-action@main
        with:
          ai_provider: gemini-vertex
          ai_model: gemini-3.5-flash
          google_cloud_project: ${{ vars.GCP_PROJECT_ID }}
          task_file: tasks/changelog_report.yml

Go Dependency Impact Analysis

Analyze Go dependency update PRs (e.g. from Renovate or Dependabot) with AI-assisted risk classification. The agent collects dependency diffs, usage analysis (via go mod why/go mod graph), upstream changelogs, and security advisories, then posts a structured impact assessment as a PR comment.

name: Go Dependency Impact Analysis

on:
  pull_request:
    paths:
      - 'go.mod'
      - 'go.sum'

jobs:
  dep-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write       # Required for Workload Identity Federation
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: '1.22'

      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - uses: redhat-community-ai-tools/cicaddy-action@main
        with:
          ai_provider: gemini-vertex
          ai_model: gemini-3.5-flash
          google_cloud_project: ${{ vars.GCP_PROJECT_ID }}
          task_file: tasks/go_dep_impact_review.yml
          post_pr_comment: 'true'
          run_govulncheck: 'true'
        env:
          AGENT_TASKS: go_dep_review

The AGENT_TASKS: go_dep_review env var activates the Go dependency review agent instead of the default PR code review agent. The run_govulncheck input enables vulnerability reachability analysis (requires Go and govulncheck installed in the runner).

See docs/providers.md for the full WIF setup guide, alternative providers (OpenAI, Claude, standalone Gemini API key), the SA key fallback, and an authentication method comparison table.

Inputs

Input	Required	Description
ai_provider	Yes	AI provider: gemini, openai, claude, anthropic-vertex, gemini-vertex
ai_model	Yes	Model identifier
ai_api_key	No	AI provider API key (not needed for anthropic-vertex or gemini-vertex)
vertex_project_id	No	GCP project ID for Vertex AI Claude (falls back to google_cloud_project)
google_cloud_project	No	GCP project ID for Vertex AI (required for gemini-vertex, optional fallback for anthropic-vertex)
google_cloud_location	No	Vertex AI location (default: global)
task_file	No	Path to DSPy YAML task file
task_prompt	No	Inline task prompt (alternative to task_file)
report_template	No	Path to custom HTML report template
mcp_servers_config	No	JSON array of MCP server configs
slack_webhook_url	No	Slack webhook URL for notifications
post_pr_comment	No	Post results as PR comment (default: false)
submit_review	No	Submit formal PR review with APPROVE/REQUEST_CHANGES (default: false)
inline_review_comments	No	Post AI findings as inline comments on PR diff lines (default: false)
run_govulncheck	No	Run govulncheck for vulnerability reachability analysis (default: false)
dep_review_severity_threshold	No	Minimum semver bump to analyze: minor or major (default: minor)
delegation_mode	No	Enable AI-powered sub-agent delegation: none (default) or auto
max_sub_agents	No	Maximum concurrent sub-agents, 1-10 (default: 3)
delegation_verify_findings	No	Verify sub-agent findings against codebase to reduce false positives (default: false)
github_token	No	GitHub token (default: ${{ github.token }})

Review Output Options

The action supports three independent review output options that control how results appear on a PR. All three default to false and can be combined:

Option	What it does
post_pr_comment	Posts (or updates) a bot comment on the PR with the full review summary. On subsequent runs the same comment is updated in place.
submit_review	Submits a formal GitHub review (APPROVE / REQUEST_CHANGES / COMMENT) based on the AI analysis.
inline_review_comments	Attaches AI findings as inline comments on the exact diff lines. Requires submit_review: 'true' since inline comments are part of the GitHub review.

Recommended combinations:

# Summary comment only (simplest)
post_pr_comment: 'true'

# Summary comment + inline diff comments (recommended for most teams)
post_pr_comment: 'true'
submit_review: 'true'
inline_review_comments: 'true'

# Formal review with inline comments, no standalone comment
submit_review: 'true'
inline_review_comments: 'true'

Note: inline_review_comments works best with submit_review: 'true' and delegation_mode: auto. Delegation produces structured findings with file/line info that inline comments need. Without submit_review, inline comments are posted as a COMMENT review (no approval/rejection verdict).

Outputs

Output	Description
report_html	Path to generated HTML report
report_json	Path to JSON analysis result
summary	Brief text summary

Custom Tasks

Create DSPy YAML task files to define custom analysis workflows. See tasks/ for examples:

• tasks/pr_review.yml — AI code review
• tasks/changelog_report.yml — Changelog generation
• tasks/go_dep_impact_review.yml — Go dependency impact analysis

Local Development

Running cicaddy locally

You can run cicaddy locally to review PRs without GitHub Actions. This is useful for testing changes to the plugin or reviewing PRs in other repositories.

1. Install the plugin in editable mode:

uv pip install -e ".[test]"

2. Create an env file (e.g. .env.my-review):

# AI Provider (Gemini via Vertex AI — uses Google Cloud ADC, no API key needed)
AI_PROVIDER=gemini-vertex
AI_MODEL=gemini-3.5-flash
GOOGLE_CLOUD_PROJECT=your-gcp-project
# GOOGLE_CLOUD_LOCATION=global  # optional, defaults to "global"

# AI Provider (standalone Gemini API key — alternative to Vertex AI)
# AI_PROVIDER=gemini
# AI_MODEL=gemini-3.5-flash
# GEMINI_API_KEY=<your-gemini-api-key>

# GitHub Configuration
GITHUB_TOKEN=<your-github-token>
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=pull_request
GITHUB_PR_NUMBER=42

# Agent Settings
POST_PR_COMMENT=true
SUBMIT_REVIEW=true
INLINE_REVIEW_COMMENTS=true
ENABLE_LOCAL_TOOLS=true
LOCAL_TOOLS_WORKING_DIR=.

# Optional: MCP servers (e.g. Context7 for library docs)
MCP_SERVERS_CONFIG=[{"name": "context7", "protocol": "http", "endpoint": "https://mcp.context7.com/mcp", "headers": {"CONTEXT7_API_KEY": "<your-key>"}}]

# Logging
LOG_LEVEL=INFO

3. Generate a GitHub token:

The token needs repo scope for private repos or public_repo for public repos. When POST_PR_COMMENT=true, the token must also have write access to pull requests (the repo scope includes this; for fine-grained tokens, enable "Pull requests: Write").

# Use your existing gh CLI token
gh auth token

Warning: Never commit env files containing secrets. The .env.* pattern is already in .gitignore, but if you use a different naming convention (e.g. .env), make sure it is also ignored.

4. Run the review:

uv run cicaddy run --env-file .env.my-review

The agent auto-detects github_pr type from the env vars, fetches the PR diff, runs AI analysis, and optionally posts a comment on the PR.

5. Validate configuration (optional):

uv run cicaddy validate --env-file .env.my-review

Environment Variables Reference

Variable	Required	Description
AI_PROVIDER	Yes	gemini, openai, claude, anthropic-vertex, or gemini-vertex
AI_MODEL	Yes	Model identifier (e.g. gemini-3.5-flash)
GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY	Yes*	API key matching the provider (*not needed for anthropic-vertex or gemini-vertex)
ANTHROPIC_VERTEX_PROJECT_ID	No	GCP project ID (required for anthropic-vertex, falls back to GOOGLE_CLOUD_PROJECT)
GOOGLE_CLOUD_PROJECT	No	GCP project ID for Vertex AI (required for gemini-vertex)
GOOGLE_CLOUD_LOCATION	No	Vertex AI location (default: global)
GITHUB_TOKEN	Yes	GitHub personal access token
GITHUB_REPOSITORY	Yes	Target repo in owner/repo format
GITHUB_EVENT_NAME	No	Set to pull_request for auto-detection (optional if GITHUB_PR_NUMBER is set)
GITHUB_PR_NUMBER	Yes	PR number to review
POST_PR_COMMENT	No	Post results as PR comment (true/false)
SUBMIT_REVIEW	No	Submit formal PR review with APPROVE/REQUEST_CHANGES (true/false)
INLINE_REVIEW_COMMENTS	No	Post AI findings as inline comments on PR diff lines (true/false)
AGENT_TASKS	No	Agent task type (e.g. go_dep_review for Go dependency analysis)
DELEGATION_MODE	No	auto for AI-powered sub-agent delegation, none for single-agent (default: none)
MAX_SUB_AGENTS	No	Max concurrent sub-agents for delegation, 1-10 (default: 3)
DELEGATION_VERIFY_FINDINGS	No	Verify sub-agent findings against codebase to reduce false positives (true/false)
SUB_AGENT_MAX_ITERS	No	Max iterations per sub-agent, 1-15 (default: 5)
AI_TASK_FILE	No	Path to DSPy YAML task file for custom workflows
RUN_GOVULNCHECK	No	Run govulncheck for reachability analysis (true/false)
DELEGATION_AGENTS_DIR	No	Custom agent YAML directory (default: .agents/delegation)
DELEGATION_AGENTS	No	JSON config for inline custom sub-agents
TRIAGE_PROMPT	No	Custom triage instructions
GIT_DIFF_CONTEXT_LINES	No	Number of context lines in diffs (default: 10)
ENABLE_LOCAL_TOOLS	No	Enable local git tools (true/false)
LOCAL_TOOLS_WORKING_DIR	No	Working directory for local tools
MCP_SERVERS_CONFIG	No	JSON array of MCP server configurations
LOG_LEVEL	No	Logging level (DEBUG, INFO, WARNING, ERROR)

Build & Test

# Run tests with coverage
pytest tests/ -q --cov=src/cicaddy_github

# Run all linters (pre-commit)
pre-commit run --all-files

# Build Docker image
docker build -t cicaddy-action:test .

License

Apache-2.0