Claude-code-plugins-plus gh-actions-validator

What This Skill Does

Expert validator and enforcer of GitHub Actions best practices specifically for Vertex AI Agent Engine and Google Cloud deployments. Ensures secure, production-ready CI/CD pipelines using Workload Identity Federation (WIF) instead of service account JSON keys.

When This Skill Activates

Trigger Phrases

• "Create GitHub Actions workflow for Vertex AI"
• "Deploy agent to Vertex AI Engine"
• "Set up Workload Identity Federation"
• "Validate GitHub Actions security for GCP"
• "GitHub Actions deployment pipeline"
• "WIF configuration for Google Cloud"
• "Automate Vertex AI deployment"
• "GitHub Actions best practices GCP"

Use Cases

• Creating CI/CD pipelines for Vertex AI Agent Engine deployments
• Migrating from JSON service account keys to WIF
• Enforcing security best practices in GitHub Actions
• Validating post-deployment of Vertex AI agents
• Setting up automated monitoring for deployed agents
• Implementing OIDC-based authentication to Google Cloud

Validation Rules Enforced

1. Workload Identity Federation (WIF) Mandatory

❌ NEVER use JSON service account keys:

# ❌ FORBIDDEN - JSON keys are insecure
- name: Authenticate (INSECURE)
  uses: google-github-actions/auth@v2
  with:
    credentials_json: ${{ secrets.GCP_SA_KEY }}  # ❌ NEVER DO THIS

✅ ALWAYS use WIF:

# ✅ REQUIRED - WIF with OIDC
permissions:
  contents: read
  id-token: write  # ✅ REQUIRED for WIF

- name: Authenticate (SECURE)
  uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
    service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

2. OIDC Permissions Required

❌ Missing id-token permission:

# ❌ FAILS - Missing id-token: write
permissions:
  contents: read

✅ Correct permissions:

# ✅ REQUIRED for WIF OIDC
permissions:
  contents: read
  id-token: write  # MUST be present

3. IAM Least Privilege

❌ Overly permissive roles:

# ❌ FORBIDDEN - Too many permissions
roles:
  - roles/owner
  - roles/editor

✅ Least privilege:

# ✅ REQUIRED - Minimal permissions
roles:
  - roles/run.admin
  - roles/iam.serviceAccountUser
  - roles/aiplatform.user

4. Vertex AI Agent Engine Deployment Validation

Post-Deployment Checks (MANDATORY):

- name: Validate Agent Deployment
  run: |
    python scripts/validate-deployment.py \
      --project-id=${{ secrets.GCP_PROJECT_ID }} \
      --agent-id=production-agent

# Validation checklist:
# ✅ Agent state is RUNNING
# ✅ Code Execution Sandbox enabled (14-day TTL)
# ✅ Memory Bank configured
# ✅ A2A Protocol compliant (AgentCard accessible)
# ✅ Model Armor enabled (prompt injection protection)
# ✅ VPC Service Controls configured
# ✅ Service account has minimal IAM permissions
# ✅ Monitoring dashboards created
# ✅ Alerting policies configured

5. Security Scanning (REQUIRED)

# ✅ REQUIRED - Security validation before deployment
- name: Scan for secrets
  uses: trufflesecurity/trufflehog@main

- name: Vulnerability scanning
  uses: aquasecurity/trivy-action@master

- name: Validate no service account keys
  run: |
    if find . -name "*service-account*.json"; then
      echo "❌ Service account JSON keys detected"
      exit 1
    fi

6. Agent Configuration Validation

Before Deployment (MANDATORY):

def validate_agent_config(agent_config: dict) -> bool:
    """
    Validate agent configuration before deployment.
    """

    # ✅ Code Execution TTL must be 7-14 days
    ttl = agent_config.get("code_execution_config", {}).get("state_ttl_days")
    assert 7 <= ttl <= 14, "❌ State TTL must be 7-14 days"

    # ✅ Memory Bank must be enabled for stateful agents
    memory_enabled = agent_config.get("memory_bank_config", {}).get("enabled")
    assert memory_enabled, "❌ Memory Bank should be enabled"

    # ✅ Model Armor must be enabled (prompt injection protection)
    model_armor = agent_config.get("model_armor", {}).get("enabled")
    assert model_armor, "❌ Model Armor must be enabled"

    # ✅ VPC configuration required for enterprise
    vpc_config = agent_config.get("vpc_config")
    assert vpc_config, "❌ VPC configuration missing"

    # ✅ Auto-scaling configured
    auto_scaling = agent_config.get("auto_scaling")
    assert auto_scaling, "❌ Auto-scaling not configured"
    assert auto_scaling.get("min_instances") >= 1, "❌ min_instances < 1"

    return True

Workflow Templates

Template 1: Vertex AI Agent Engine Deployment

name: Deploy Vertex AI Agent

on:
  push:
    branches: [main]
    paths:
      - 'agent/**'
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

env:
  AGENT_ID: 'production-adk-agent'
  REGION: 'us-central1'

jobs:
  validate-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Authenticate to GCP (WIF)
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt

      - name: Validate Agent Configuration
        run: |
          python scripts/validate-agent-config.py

      - name: Deploy to Vertex AI Engine
        run: |
          python scripts/deploy-agent.py \
            --project-id=${{ secrets.GCP_PROJECT_ID }} \
            --location=${{ env.REGION }} \
            --agent-id=${{ env.AGENT_ID }}

      - name: Post-Deployment Validation
        run: |
          python scripts/validate-deployment.py \
            --project-id=${{ secrets.GCP_PROJECT_ID }} \
            --agent-id=${{ env.AGENT_ID }}

      - name: Setup Monitoring
        run: |
          python scripts/setup-monitoring.py \
            --project-id=${{ secrets.GCP_PROJECT_ID }} \
            --agent-id=${{ env.AGENT_ID }}

      - name: Test Agent Endpoint
        run: |
          python scripts/test-agent.py \
            --agent-id=${{ env.AGENT_ID }}

Template 2: WIF Setup (One-Time Infrastructure)

name: Setup Workload Identity Federation

on:
  workflow_dispatch:
    inputs:
      github_repo:
        description: 'GitHub repository (owner/repo)'
        required: true

permissions:
  contents: read

jobs:
  setup-wif:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Authenticate with JSON key (one-time only)
        uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.GCP_SETUP_KEY }}

      - name: Run WIF setup script
        run: |
          bash scripts/setup-wif.sh \
            --project-id=${{ secrets.GCP_PROJECT_ID }} \
            --github-repo=${{ github.event.inputs.github_repo }}

      - name: Output WIF configuration
        run: |
          cat wif-config.txt

Template 3: Security Validation (Pre-Deployment)

name: Security Validation

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  security-checks:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Scan for secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.repository.default_branch }}
          head: HEAD

      - name: Vulnerability scanning
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          scan-ref: '.'
          format: 'sarif'
          output: 'trivy-results.sarif'

      - name: Upload results to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: 'trivy-results.sarif'

      - name: Validate no service account keys
        run: |
          if find . -name "*service-account*.json" -o -name "*credentials*.json"; then
            echo "❌ Service account key files detected"
            exit 1
          fi
          echo "✅ No service account keys found"

      - name: Validate WIF usage in workflows
        run: |
          if grep -r "credentials_json" .github/workflows/; then
            echo "❌ JSON credentials detected (use WIF)"
            exit 1
          fi
          echo "✅ Workflows use WIF"

      - name: Validate IAM roles (no owner/editor)
        run: |
          if grep -r "roles/owner\|roles/editor" . --include="*.tf" --include="*.yaml"; then
            echo "❌ Overly permissive IAM roles detected"
            exit 1
          fi
          echo "✅ Least privilege IAM roles"

Vertex AI Agent Engine Specific Validations

Deployment Configuration Validation

# scripts/validate-agent-config.py
from typing import Dict, Any

def validate_vertex_agent_config(config: Dict[str, Any]) -> None:
    """
    Comprehensive Vertex AI Agent Engine configuration validation.
    """

    # 1. Model Selection
    model = config.get("model")
    assert model in ["gemini-2.5-pro", "gemini-2.5-flash"], \
        f"❌ Invalid model: {model}. Use gemini-2.5-pro or gemini-2.5-flash"

    # 2. Code Execution Sandbox
    code_exec = config.get("code_execution_config", {})
    if code_exec.get("enabled"):
        ttl = code_exec.get("state_ttl_days")
        assert 1 <= ttl <= 14, \
            f"❌ State TTL must be 1-14 days, got {ttl}"

        assert code_exec.get("sandbox_type") == "SECURE_ISOLATED", \
            "❌ Sandbox type must be SECURE_ISOLATED"

        timeout = code_exec.get("timeout_seconds")
        assert 1 <= timeout <= 600, \
            f"❌ Timeout must be 1-600 seconds, got {timeout}"

    # 3. Memory Bank
    memory = config.get("memory_bank_config", {})
    if memory.get("enabled"):
        max_memories = memory.get("max_memories")
        assert max_memories >= 100, \
            f"⚠️ Low memory limit: {max_memories}. Recommend >= 100"

        assert memory.get("indexing_enabled"), \
            "⚠️ Indexing disabled will slow query performance"

        assert memory.get("auto_cleanup"), \
            "⚠️ Auto-cleanup disabled may exceed quotas"

    # 4. Security
    assert config.get("model_armor", {}).get("enabled"), \
        "❌ Model Armor must be enabled (prompt injection protection)"

    assert config.get("vpc_config"), \
        "❌ VPC configuration required for enterprise deployment"

    # 5. Auto-Scaling
    auto_scaling = config.get("auto_scaling", {})
    assert auto_scaling.get("min_instances") >= 1, \
        "❌ min_instances must be >= 1 for production"

    assert auto_scaling.get("max_instances") >= 3, \
        "⚠️ max_instances should be >= 3 for high availability"

    # 6. IAM
    sa = config.get("service_account")
    assert sa and "@" in sa, \
        f"❌ Invalid service account: {sa}"

    print("✅ All Vertex AI agent configuration checks passed")

Post-Deployment Health Check

# scripts/validate-deployment.py
from google.cloud.aiplatform import agent_builder
import requests

def validate_vertex_deployment(
    project_id: str,
    location: str,
    agent_id: str
) -> bool:
    """
    Post-deployment validation for Vertex AI Agent Engine.
    """

    client = agent_builder.AgentBuilderClient()
    agent_name = f"projects/{project_id}/locations/{location}/agents/{agent_id}"

    # 1. Agent Status
    agent = client.get_agent(name=agent_name)
    assert agent.state == "RUNNING", \
        f"❌ Agent not running: {agent.state}"
    print(f"✅ Agent status: {agent.state}")

    # 2. Code Execution Sandbox
    assert agent.code_execution_config.enabled, \
        "❌ Code Execution not enabled"
    print(f"✅ Code Execution enabled (TTL: {agent.code_execution_config.state_ttl_days} days)")

    # 3. Memory Bank
    assert agent.memory_bank_config.enabled, \
        "❌ Memory Bank not enabled"
    print(f"✅ Memory Bank enabled")

    # 4. A2A Protocol Compliance
    agentcard_url = f"{agent.agent_endpoint}/.well-known/agent-card"
    response = requests.get(agentcard_url, timeout=10)
    assert response.status_code == 200, \
        f"❌ AgentCard not accessible: {response.status_code}"

    agentcard = response.json()
    assert "name" in agentcard and "version" in agentcard, \
        "❌ AgentCard missing required fields"
    print(f"✅ A2A Protocol: AgentCard accessible")

    # 5. Model Armor
    assert agent.model_armor.enabled, \
        "❌ Model Armor not enabled"
    print(f"✅ Model Armor enabled (prompt injection protection)")

    # 6. Endpoint
    assert agent.agent_endpoint, \
        "❌ Agent endpoint not available"
    print(f"✅ Agent endpoint: {agent.agent_endpoint}")

    # 7. Service Account
    assert agent.service_account, \
        "❌ Service account not configured"
    print(f"✅ Service account: {agent.service_account}")

    print("\n✅ All post-deployment validations passed!")
    return True

Tool Permissions

This skill uses:

• Read: Analyze workflow files and configurations
• Write: Create GitHub Actions workflows
• Edit: Update existing workflows for compliance
• Grep: Search for security issues (JSON keys, etc.)
• Glob: Find workflow files across repository
• Bash: Execute validation scripts and gcloud commands

Integration with Other Plugins

Works with jeremy-adk-orchestrator

• Provides CI/CD for ADK agent deployments
• Automates A2A protocol validation
• Ensures production readiness

Works with jeremy-vertex-validator

• GitHub Actions calls vertex-validator for post-deployment checks
• Comprehensive validation pipeline
• Production readiness scoring

Works with jeremy-adk-terraform

• GitHub Actions deploys Terraform infrastructure
• Automated infrastructure provisioning
• Validation of Terraform-provisioned resources

Works with jeremy-vertex-engine

• GitHub Actions triggers vertex-engine-inspector
• Continuous health monitoring
• Automated compliance checks

Best Practices Summary

Security (MANDATORY)

✅ Use WIF (Workload Identity Federation) - never JSON keys ✅ Require

id-token: write

permission for OIDC ✅ IAM least privilege (never owner/editor roles) ✅ Attribute-based access control (restrict by repository) ✅ Enable Model Armor for agents ✅ VPC Service Controls for enterprise isolation ✅ Scan for secrets in code (Trufflehog) ✅ Vulnerability scanning (Trivy)

Vertex AI Specific (MANDATORY)

✅ Code Execution Sandbox: 7-14 day TTL ✅ Memory Bank enabled for stateful agents ✅ A2A Protocol compliance (AgentCard validation) ✅ Model Armor enabled (prompt injection protection) ✅ Auto-scaling configured (min >= 1, max >= 3) ✅ Post-deployment validation (agent status, endpoints) ✅ Monitoring dashboards created ✅ Alerting policies configured

CI/CD (RECOMMENDED)

✅ Conditional job execution (only on relevant paths) ✅ Caching for dependencies (faster builds) ✅ Concurrent jobs when possible ✅ Rollback strategies for failed deployments ✅ Health check endpoints

Version History

• 1.0.0 (2025): Initial release with WIF enforcement, Vertex AI validations, security scanning

References

• Workload Identity Federation: https://cloud.google.com/iam/docs/workload-identity-federation
• GitHub OIDC: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
• Vertex AI Agent Engine: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview
• google-github-actions/auth: https://github.com/google-github-actions/auth