@intentsolutionsio/jeremy-github-actions-gcp 2.1.0

package/scripts/validate-workflow.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# Validate GitHub Actions workflow for Vertex AI / GCP best practices
+# This script is called by hooks before writing/editing workflow files
+#
+
+set -e
+
+WORKFLOW_FILE="$1"
+
+echo "🔍 Validating GitHub Actions workflow: $WORKFLOW_FILE"
+
+# Check 1: WIF - Must use workload_identity_provider, NOT credentials_json
+if grep -q "credentials_json" "$WORKFLOW_FILE"; then
+    echo "❌ SECURITY VIOLATION: JSON service account keys detected"
+    echo "   Use Workload Identity Federation (WIF) instead:"
+    echo "   workload_identity_provider: \${{ secrets.WIF_PROVIDER }}"
+    echo "   service_account: \${{ secrets.WIF_SERVICE_ACCOUNT }}"
+    exit 1
+fi
+
+# Check 2: OIDC Permissions - Must have id-token: write for WIF
+if grep -q "workload_identity_provider" "$WORKFLOW_FILE"; then
+    if ! grep -q "id-token: write" "$WORKFLOW_FILE"; then
+        echo "❌ MISSING REQUIRED PERMISSION: id-token: write"
+        echo "   Workload Identity Federation requires OIDC token permission:"
+        echo ""
+        echo "   permissions:"
+        echo "     contents: read"
+        echo "     id-token: write  # REQUIRED for WIF"
+        exit 1
+    fi
+fi
+
+# Check 3: IAM - No overly permissive roles
+if grep -E "roles/owner|roles/editor" "$WORKFLOW_FILE"; then
+    echo "❌ SECURITY VIOLATION: Overly permissive IAM roles detected"
+    echo "   Use least privilege roles instead:"
+    echo "   - roles/run.admin"
+    echo "   - roles/iam.serviceAccountUser"
+    echo "   - roles/aiplatform.user"
+    exit 1
+fi
+
+# Check 4: Secrets - No hardcoded values
+if grep -E "GOOGLE_APPLICATION_CREDENTIALS.*=|GCP_SA_KEY.*=" "$WORKFLOW_FILE"; then
+    echo "❌ SECURITY VIOLATION: Hardcoded credentials detected"
+    echo "   Use GitHub secrets: \${{ secrets.SECRET_NAME }}"
+    exit 1
+fi
+
+# Check 5: Vertex AI deployments - Must have post-deployment validation
+if grep -q "vertex" "$WORKFLOW_FILE" || grep -q "aiplatform" "$WORKFLOW_FILE"; then
+    if ! grep -q "validate-deployment\|validate-agent" "$WORKFLOW_FILE"; then
+        echo "⚠️  WARNING: Vertex AI deployment without validation step"
+        echo "   Add post-deployment validation:"
+        echo "   - name: Validate Deployment"
+        echo "     run: python scripts/validate-deployment.py"
+    fi
+fi
+
+# Check 6: Security scanning - Recommended for production workflows
+if grep -q "deploy" "$WORKFLOW_FILE"; then
+    if ! grep -q "trivy\|trufflehog" "$WORKFLOW_FILE"; then
+        echo "⚠️  RECOMMENDATION: Add security scanning before deployment"
+        echo "   - uses: aquasecurity/trivy-action@master"
+        echo "   - uses: trufflesecurity/trufflehog@main"
+    fi
+fi
+
+echo "✅ GitHub Actions workflow validation passed"
+exit 0

package/skills/gh-actions-validator/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gh-actions-validator
+description: |
+  Validate use when validating GitHub Actions workflows for Google Cloud and Vertex AI deployments. Trigger with phrases like "validate github actions", "setup workload identity federation", "github actions security", "deploy agent with ci/cd", or "automate vertex ai deployment". Enforces Workload Identity Federation (WIF), validates OIDC permissions, ensures least privilege IAM, and implements security best practices.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(git:*), Bash(gcloud:*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [devops, deployment, gcp, security]
+---
+# Gh Actions Validator
+
+## Overview
+
+Validate and harden GitHub Actions workflows that deploy to Google Cloud (especially Vertex AI) using Workload Identity Federation (OIDC) instead of long-lived service account keys. Use this to audit existing workflows, propose a secure replacement, and add CI checks that prevent common credential and permission mistakes.
+
+## Prerequisites
+
+Before using this skill, ensure:
+- GitHub repository with Actions enabled
+- Google Cloud project with billing enabled
+- gcloud CLI authenticated with admin permissions
+- Understanding of Workload Identity Federation concepts
+- GitHub repository secrets configured
+- Appropriate IAM roles for CI/CD automation
+
+## Instructions
+
+1. **Audit Existing Workflows**: Scan .github/workflows/ for security issues
+2. **Validate WIF Usage**: Ensure no JSON service account keys are used
+3. **Check OIDC Permissions**: Verify id-token: write is present
+4. **Review IAM Roles**: Confirm least privilege (no owner/editor roles)
+5. **Add Security Scans**: Include secret detection and vulnerability scanning
+6. **Validate Deployments**: Add post-deployment health checks
+7. **Configure Monitoring**: Set up alerts for deployment failures
+8. **Document WIF Setup**: Provide one-time WIF configuration commands
+
+## Output
+
+      - uses: actions/checkout@v4
+      - name: Authenticate to GCP (WIF)
+      - name: Deploy to Vertex AI
+            --project=${{ secrets.GCP_PROJECT_ID }} \
+            --region=us-central1
+      - name: Validate Deployment
+
+## Error Handling
+
+See `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error handling.
+
+## Examples
+
+See `${CLAUDE_SKILL_DIR}/references/examples.md` for detailed examples.
+
+## Resources
+
+- 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
+- Vertex AI Agent Engine: https://cloud.google.com/vertex-ai/docs/agent-engine
+- google-github-actions/auth: https://github.com/google-github-actions/auth
+- WIF setup guide in ${CLAUDE_SKILL_DIR}/docs/wif-setup.md

package/skills/gh-actions-validator/references/ARD.md

@@ -0,0 +1,72 @@
+# ARD: GH Actions Validator
+
+> Part of [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)
+
+## System Context
+
+The GH Actions Validator inspects GitHub Actions workflow files and their associated GCP IAM configuration to ensure secure deployment patterns using Workload Identity Federation.
+
+```
+.github/workflows/*.yml
+       ↓
+[GH Actions Validator]
+  ├── Reads: workflow YAML files, IAM policies
+  ├── Scans: auth patterns, permissions, IAM roles
+  └── Generates: WIF setup commands, hardened workflows
+       ↓
+Validation Report + WIF Setup
+  ├── Security findings (JSON keys, missing OIDC)
+  ├── IAM role recommendations
+  ├── WIF setup gcloud commands
+  └── Hardened workflow templates
+```
+
+## Data Flow
+
+1. **Input**: Repository path containing `.github/workflows/` directory. Optionally a specific workflow file to validate. GCP project ID for IAM audit.
+2. **Processing**: Parse all workflow YAML files. For each workflow: check for JSON key usage patterns, validate `google-github-actions/auth` action configuration, verify `id-token: write` permission, audit IAM roles on the authenticated service account via `gcloud`, check for post-deployment health steps. Generate WIF setup commands if not yet configured.
+3. **Output**: Validation report listing security findings per workflow, IAM role audit results, WIF setup commands (if needed), and optionally a hardened workflow template with WIF auth and security scanning steps.
+
+## Key Design Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| WIF over JSON keys | Require OIDC authentication for all GCP deployments | JSON keys are a security liability: they leak, never expire, and can't be scoped to repo/branch |
+| `google-github-actions/auth@v2` | Standardize on Google's official auth action | Maintained by Google; handles token exchange correctly; supports audience and provider config |
+| Least-privilege IAM audit | Flag owner/editor roles; suggest specific alternatives | Broad roles are the most common security misconfiguration in CI/CD pipelines |
+| YAML-level validation | Parse workflow YAML rather than running workflows | Safe, fast, deterministic; no need for GitHub API tokens or workflow triggers |
+| Idempotent WIF setup | All gcloud commands safe to re-run | Prevents errors when running setup on already-configured projects |
+| Role-to-target mapping | Map deployment targets to minimum IAM roles | Cloud Run needs `roles/run.developer`, Agent Engine needs `roles/aiplatform.user`; prevents over-granting |
+| Auth action version pinning | Require `@v2` not `@v1` or `@main` | Pinned versions are reproducible and auditable; `@main` can introduce breaking changes |
+
+## Tool Usage Pattern
+
+| Tool | Purpose |
+|------|---------|
+| Read | Parse workflow YAML files, IAM policy exports, and WIF configuration files |
+| Write | Generate hardened workflow templates and WIF setup scripts |
+| Edit | Patch existing workflows to add OIDC permissions, update auth actions, add health checks |
+| Grep | Search for JSON key patterns (`credentials_json`, `GOOGLE_APPLICATION_CREDENTIALS`), IAM role references |
+| Glob | Discover all workflow files in `.github/workflows/` |
+| Bash(git:*) | Check git history for committed credentials or key files |
+| Bash(gcloud:*) | Query IAM policies, list service accounts, check WIF pool/provider configuration |
+
+## Error Handling Strategy
+
+| Error Class | Detection | Recovery |
+|------------|-----------|----------|
+| Invalid workflow YAML | YAML parse failure on workflow file | Report syntax error location; suggest `yamllint` for detailed diagnostics |
+| Missing OIDC permission | `id-token: write` not in job permissions | Provide the exact `permissions:` block to add to the workflow |
+| WIF pool not configured | `gcloud iam workload-identity-pools describe` returns not found | Generate the complete set of `gcloud` commands to create pool, provider, and IAM binding |
+| Overprivileged IAM role | Service account has `roles/owner` or `roles/editor` | Suggest the minimum required roles for the specific deployment target (e.g., `roles/run.developer`) |
+| Auth action outdated | `google-github-actions/auth@v1` in workflow | Recommend upgrading to `@v2` with the updated parameter names |
+
+## Extension Points
+
+- Multi-cloud support: extend patterns to validate AWS OIDC or Azure federated credentials
+- Branch-scoped WIF: configure attribute conditions that restrict authentication to specific branches
+- Reusable workflow validation: audit called workflows and composite actions for the same security patterns
+- Policy-as-code: define organization-level security policies that all workflows must satisfy
+- Automated remediation: apply fixes to workflow files with user confirmation
+- Compliance reports: generate audit reports showing WIF adoption percentage across all workflows
+- Team templates: generate organization-level reusable workflows with pre-configured WIF

package/skills/gh-actions-validator/references/PRD.md

@@ -0,0 +1,67 @@
+# PRD: GH Actions Validator
+
+**Version:** 1.0.0
+**Author:** Jeremy Longshore <jeremy@intentsolutions.io>
+**Status:** Active
+**Marketplace:** [tonsofskills.com](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io)
+**Portfolio:** [jeremylongshore.com](https://jeremylongshore.com)
+
+---
+
+## Problem Statement
+
+GitHub Actions workflows that deploy to Google Cloud commonly use long-lived service account JSON keys stored as repository secrets. This practice violates security best practices: keys can leak, never expire, and grant broad permissions. Migrating to Workload Identity Federation (WIF) with OIDC requires coordinating multiple GCP resources (workload identity pool, provider, IAM bindings) and GitHub workflow changes (id-token permissions, auth action). Developers misconfigure these steps, resulting in authentication failures and insecure fallbacks to JSON keys.
+
+## Target Users
+
+| User | Context | Primary Need |
+|------|---------|-------------|
+| DevOps Engineer | Setting up CI/CD for GCP deployments from GitHub Actions | Secure WIF configuration with validated OIDC permissions |
+| Security Engineer | Auditing existing workflows for credential hygiene | Detection of JSON key usage and insecure IAM patterns |
+| Platform Engineer | Standardizing deployment pipelines across teams | Reusable, validated workflow templates with least-privilege IAM |
+| Developer | Deploying Vertex AI agents or Cloud Run services via GitHub Actions | Working workflow with WIF auth and post-deployment health checks |
+
+## Success Criteria
+
+1. Detect 100% of JSON service account key usage in workflow files (secrets or files)
+2. Validate OIDC `id-token: write` permission is present in all deployment workflows
+3. Confirm no `roles/owner` or `roles/editor` IAM bindings in deployment service accounts
+4. Provide complete WIF setup commands that work on first execution
+5. Hardened workflow template includes secret scanning and dependency vulnerability checks
+6. Post-deployment health checks validate endpoint availability before marking success
+
+## Functional Requirements
+
+1. Scan `.github/workflows/` for all YAML workflow files
+2. Detect JSON service account key usage: `GOOGLE_APPLICATION_CREDENTIALS`, key file references, `credentials_json` inputs
+3. Validate WIF authentication: `google-github-actions/auth@v2` action with `workload_identity_provider` parameter
+4. Check OIDC permissions: `id-token: write` in the `permissions` block of deployment jobs
+5. Review IAM roles on deployment service accounts: flag `roles/owner`, `roles/editor`, and recommend least-privilege alternatives
+6. Add security scanning steps: secret detection, dependency vulnerability scanning
+7. Validate post-deployment health checks exist for each deploy step
+8. Generate WIF one-time setup commands for the GCP project
+
+## Non-Functional Requirements
+
+- Validation must work on any GitHub Actions YAML regardless of deployment target (Cloud Run, Agent Engine, Functions)
+- WIF setup commands must be idempotent (safe to re-run without side effects)
+- Must handle matrix builds and reusable workflow patterns
+- No modifications to workflows without explicit user consent
+- YAML parsing must handle all GitHub Actions syntax including anchors, aliases, and expressions
+- Validation must complete offline (no GitHub API calls required for YAML analysis)
+
+## Dependencies
+
+- GitHub repository with Actions enabled and workflow files in `.github/workflows/`
+- Google Cloud project with billing enabled
+- `gcloud` CLI authenticated with admin permissions (for WIF setup)
+- `google-github-actions/auth@v2` action available on GitHub
+
+## Out of Scope
+
+- Non-GCP deployment targets (AWS, Azure)
+- GitHub Actions runner self-hosting configuration
+- Application-level testing within workflows (unit tests, integration tests)
+- Cost optimization of GitHub Actions minutes
+- GitHub App or OAuth token management
+- Workflow performance optimization (caching, parallelism)

package/skills/gh-actions-validator/references/errors.md

@@ -0,0 +1,24 @@
+# Error Handling Reference
+
+**WIF Authentication Failed**
+- Error: "Failed to generate Google Cloud access token"
+- Solution: Verify WIF provider and service account email are correct
+
+**OIDC Token Error**
+- Error: "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable"
+- Solution: Add `id-token: write` permission to workflow
+
+**IAM Permission Denied**
+- Error: "does not have required permission"
+- Solution: Grant service account minimum required roles (run.admin, aiplatform.user)
+
+**Attribute Condition Failed**
+- Error: "Token does not match attribute condition"
+- Solution: Update attribute mapping to include repository restriction
+
+**Deployment Validation Failed**
+- Error: "Agent not in RUNNING state"
+- Solution: Check agent configuration and deployment logs
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/gh-actions-validator/references/examples.md

@@ -0,0 +1,8 @@
+# Examples
+
+**Example: Harden an existing deployment workflow**
+- Input: `.github/workflows/deploy.yml` that uses `credentials_json` or a downloaded service account key.
+- Output: a WIF-based workflow using `google-github-actions/auth@v2`, minimal IAM roles, and a guardrail job that fails PRs when JSON keys appear in workflows.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/gh-actions-validator/scripts/setup-wif.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# setup-wif.sh - Setup Workload Identity Federation for GitHub Actions
+
+set -euo pipefail
+
+PROJECT_ID="${1:-}"
+REPO_OWNER="${2:-}"
+REPO_NAME="${3:-}"
+
+if [[ -z "$PROJECT_ID" ]] || [[ -z "$REPO_OWNER" ]] || [[ -z "$REPO_NAME" ]]; then
+    cat <<EOF
+Usage: $0 <PROJECT_ID> <REPO_OWNER> <REPO_NAME>
+
+Setup Workload Identity Federation for GitHub Actions GCP authentication.
+
+Example:
+    $0 my-project jeremylongshore my-repo
+
+EOF
+    exit 1
+fi
+
+echo "Setting up Workload Identity Federation"
+echo "Project: $PROJECT_ID"
+echo "Repository: $REPO_OWNER/$REPO_NAME"
+echo ""
+
+# Create workload identity pool
+echo "Creating workload identity pool..."
+gcloud iam workload-identity-pools create "github-pool" \
+    --project="$PROJECT_ID" \
+    --location="global" \
+    --display-name="GitHub Actions Pool" || echo "Pool may already exist"
+
+# Create OIDC provider
+echo "Creating OIDC provider..."
+gcloud iam workload-identity-pools providers create-oidc "github-provider" \
+    --project="$PROJECT_ID" \
+    --location="global" \
+    --workload-identity-pool="github-pool" \
+    --issuer-uri="https://token.actions.githubusercontent.com" \
+    --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
+    --attribute-condition="assertion.repository=='$REPO_OWNER/$REPO_NAME'" || echo "Provider may already exist"
+
+# Get WIF provider name
+WIF_PROVIDER="projects/$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
+
+echo ""
+echo "✓ Workload Identity Federation configured"
+echo ""
+echo "Add these secrets to your GitHub repository:"
+echo "  WIF_PROVIDER: $WIF_PROVIDER"
+echo "  GCP_PROJECT_ID: $PROJECT_ID"
+echo ""
+echo "Create a service account and grant it access:"
+echo "  gcloud iam service-accounts create github-actions --project=$PROJECT_ID"
+echo "  gcloud iam service-accounts add-iam-policy-binding github-actions@$PROJECT_ID.iam.gserviceaccount.com \\"
+echo "    --role=roles/iam.workloadIdentityUser \\"
+echo "    --member=\"principalSet://iam.googleapis.com/$WIF_PROVIDER/attribute.repository/$REPO_OWNER/$REPO_NAME\""

package/skills/gh-actions-validator/scripts/validate-workflow.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# validate-workflow.sh - Validate GitHub Actions workflows for GCP security
+
+set -euo pipefail
+
+WORKFLOW_DIR="${1:-.github/workflows}"
+
+echo "Validating GitHub Actions Workflows"
+echo "Directory: $WORKFLOW_DIR"
+echo ""
+
+ISSUES=0
+
+# Check for WIF usage
+echo "Checking for Workload Identity Federation..."
+if grep -r "workload_identity_provider" "$WORKFLOW_DIR" 2>/dev/null; then
+    echo "✓ Using Workload Identity Federation"
+else
+    echo "✗ No WIF configuration found - use WIF instead of JSON keys"
+    ((ISSUES++))
+fi
+
+# Check for JSON keys (security issue)
+echo "Checking for JSON service account keys..."
+if grep -r "credentials_json\|service-account.*json" "$WORKFLOW_DIR" 2>/dev/null; then
+    echo "✗ JSON keys detected - migrate to Workload Identity Federation"
+    ((ISSUES++))
+else
+    echo "✓ No JSON keys found"
+fi
+
+# Check for OIDC permissions
+echo "Checking for id-token permissions..."
+if grep -r "id-token.*write" "$WORKFLOW_DIR" 2>/dev/null; then
+    echo "✓ OIDC permissions configured"
+else
+    echo "⚠ Missing 'id-token: write' permission"
+    ((ISSUES++))
+fi
+
+# Check for security scans
+echo "Checking for security scans..."
+if grep -r "trufflehog\|trivy\|snyk" "$WORKFLOW_DIR" 2>/dev/null; then
+    echo "✓ Security scanning configured"
+else
+    echo "⚠ No security scanning detected"
+fi
+
+echo ""
+if (( ISSUES == 0 )); then
+    echo "✓ Workflows are secure"
+    exit 0
+else
+    echo "✗ Found $ISSUES security issues"
+    exit 1
+fi