aSkills.dev logo
aSkills.devRegistry
Submit Skill
Verified SOP & TutorialAudited Score 98/100

The Complete Production SOP: How to Deploy and Run GCP Workload Identity Federation with GitHub Actions in Autonomous AI Agents

Step-by-step SOP to install and run GCP Workload Identity Federation in Codex, Claude Code, & Cursor. Eliminate service account keys with deterministic agent SOPs.

View 1-Click Spec
Target Runtimes:codexclaude-codecursorwindsurf
5 min read • Updated for 2026

Technical Overview & Architectural Context

Autonomous coding agents like Codex, Claude Code, Cursor, and Windsurf often default to legacy authentication paradigms when generating CI/CD pipelines. When instructed to connect GitHub Actions to Google Cloud, unconstrained agents typically generate static service account JSON keys, advise saving base64 strings into repository secrets, and introduce severe credential leakage vulnerabilities. Even when prompted to use Workload Identity Federation (WIF), agents frequently misconfigure subject mappings, omit required GitHub OIDC token permissions, or confuse IAM bindings between the Workload Identity Pool and target Google Cloud Service Accounts. The GCP Workload Identity Federation skill enforces strict architectural boundaries on the agent. It mandates the creation of short-lived OIDC federated identities, configures exact attribute mappings (matching repository identities against token assertions), and generates compliant GitHub Actions workflow manifests using `google-github-actions/auth@v2`. By constraining filesystem modifications to workspace paths and requiring validation checks, this skill eliminates key generation anti-patterns and ensures zero-trust CI/CD authentication without manual intervention.

Prerequisites & Environment Requirements

Codex Desktop, Claude Code CLI, Cursor, or Windsurf installed with active workspace access
Google Cloud SDK (gcloud) 450.0.0+ installed and authenticated with Project Owner or Security Admin roles
GitHub CLI (gh) 2.40+ installed and authenticated to target repository
Workspace initialized with Git 2.40+ containing a `.github/workflows/` directory structure

Verified Search Intents & Long-Tail Queries Solved

SEO Audit Score: 98/100

This operational tutorial is engineered to provide deterministic solutions for these developer search queries:

#install gcp-workload-identity-federation in cursor ide#claude code gcp-workload-identity-federation rules#codex desktop gcp-workload-identity-federation setup tutorial#how to fix gcp-workload-identity-federation agent execution error#deterministic devops agent SOP#gcp-workload-identity-federation sandbox permissions and security score#github actions keyless gcp auth workflow skill

Step-by-Step Execution Playbook

1

Local Environment Setup & SKILL.md Mounting

Create the local skill manifest directory and inject verified procedural rules.

Autonomous runtimes discover capabilities through directory scanning. Place the canonical `SKILL.md` file in the `.agents/skills/gcp-workload-identity-federation/` directory within your workspace or global agent registry. The runtime matches natural language inputs to frontmatter trigger patterns like 'setup gcp workload identity github actions' or 'eliminate gcp service account key'.

Terminal Command
mkdir -p .agents/skills/gcp-workload-identity-federation && cat << 'EOF' > .agents/skills/gcp-workload-identity-federation/SKILL.md --- name: "gcp-workload-identity-federation" description: "Authenticate GitHub Actions to Google Cloud securely without managing permanent service account keys." metadata: author: "Google Cloud Platform" version: "1.0.0" runtime_compatibility: - "codex" - "claude-code" - "cursor" - "windsurf" triggers: - "setup gcp workload identity github actions" - "eliminate gcp service account key" - "configure wif gcp" permissions: fs_read: true fs_write: "workspace" shell_exec: false net_access: false --- # GCP Workload Identity Federation with GitHub Actions Configures GCP Workload Identity Federation (WIF) and outputs production-ready Terraform/gcloud and workflow manifests. EOF
.agents/skills/gcp-workload-identity-federation/SKILL.md
---
name: "gcp-workload-identity-federation"
description: "Authenticate GitHub Actions to Google Cloud securely without managing permanent service account keys."
metadata:
  author: "Google Cloud Platform"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "setup gcp workload identity github actions"
  - "eliminate gcp service account key"
  - "configure wif gcp"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---
Production Pro-Tip

Mounting the skill locally inside your repository's `.agents/skills` directory guarantees that all team members using Claude Code or Cursor share identical deterministic generation constraints without prompt drifting.

Sandbox Gotcha

Ensure directory permissions match agent user rights; if using Claude Code CLI inside a restricted container, read permissions (`chmod 644`) on the SKILL.md manifest are strictly required.

2

Environment Secrets & Infrastructure Parameter Validation

Inject required infrastructure identifiers safely without exposing secrets in conversation logs.

Provide contextual project metadata to the workspace without hardcoding raw credentials. Create an environment context file or pass standard variables (`PROJECT_ID`, `PROJECT_NUMBER`, `POOL_NAME`, `PROVIDER_NAME`, `SA_NAME`, `GITHUB_REPO`) so the agent constructs correct resource IDs like `projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_NAME}/providers/${PROVIDER_NAME}`.

Terminal Command
cat << 'EOF' > .env.gcp.example GCP_PROJECT_ID="my-gcp-project" GCP_PROJECT_NUMBER="123456789012" GCP_WORKLOAD_POOL="github-pool" GCP_WORKLOAD_PROVIDER="github-provider" GCP_SERVICE_ACCOUNT="[email protected]" GITHUB_REPO="org/repo" EOF
Production Pro-Tip

Always query the numeric project ID (`gcloud projects describe $PROJECT_ID --format='value(projectNumber)'`) rather than guessing, as Workload Identity Provider resource paths require the project number, not the slug.

Sandbox Gotcha

Never execute `gcloud iam service-accounts keys create` when this skill is mounted; the skill enforces keyless authentication and forbids static key creation.

3

Intent Matching & Trigger Invocation

Trigger deterministic agent execution using tested prompt templates.

Invoke the skill explicitly using frontmatter triggers. The agent matches 'setup gcp workload identity github actions' and generates both the infrastructure automation script (or Terraform block) and the corresponding GitHub Actions YAML with required top-level `permissions: id-token: write` and `contents: read` blocks.

Production Pro-Tip

Specify the full GitHub repository slug (e.g., `owner/repo-name`) in your trigger prompt to enable the agent to immediately configure the exact principal attribute restriction (`assertion.repository == 'owner/repo-name'`).

Sandbox Gotcha

If the agent generates workflow steps without `id-token: write`, the OIDC token exchange will fail silently at runtime with HTTP 403.

4

Verification, Linting & Output Quality Gate

Execute automated syntax and policy validation before merging the agent's generated configurations.

Audit generated workflow files and IAM scripts using YAML linters and Google Cloud validation tools. The skill requires verification that no raw credentials are hardcoded and that the workload identity provider string matches the canonical format.

Terminal Command
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/deploy.yml'))" && grep -E 'workload_identity_provider|id-token' .github/workflows/deploy.yml
Production Pro-Tip

Run `actionlint` against generated GitHub Actions workflows to catch missing `id-token: write` permissions or invalid step syntax before committing.

Sandbox Gotcha

Verify that `attribute.repository` is mapped in attribute-mappings; without it, binding to `principalSet://iam.googleapis.com/.../attribute.repository/OWNER/REPO` fails authorization.

Real-World Scenario: Eliminating Service Account Keys for Production Cloud Run Deployment in GitHub Actions

Tested Trigger Prompt (Feed directly into Codex, Claude, or Cursor):

“setup gcp workload identity github actions for deploying our microservice to Cloud Run in project 'prod-cloud-api' (Project Number: 987654321000) from repository 'acme-corp/api-gateway'. Eliminate existing service account keys and generate a verified deploy.yml.”

Deterministic Agent Verification Pipeline:
Generates a gcloud script creating the Workload Identity Pool 'github-pool' and Provider 'github-provider' with issuer 'https://token.actions.githubusercontent.com' and mapping 'google.subject=assertion.sub,attribute.repository=assertion.repository'.
Creates the IAM service account binding: `roles/iam.workloadIdentityUser` assigned to `principalSet://iam.googleapis.com/projects/987654321000/locations/global/workloadIdentityPools/github-pool/attribute.repository/acme-corp/api-gateway`.
Generates `.github/workflows/deploy.yml` with `permissions: { id-token: write, contents: read }` using `google-github-actions/auth@v2` targeting the federated provider and service account.
Includes Cloud Run deployment step using `google-github-actions/deploy-cloudrun@v2` without any references to secret keys.

Runtime Troubleshooting & Failure Modes

Error: google-github-actions/auth failed with: The token "id-token" could not be fetched. Check that "permissions: id-token: write" is set.

Root Cause: GitHub Actions defaults to read-only GITHUB_TOKEN permissions unless explicitly overridden in the workflow. The auth action cannot fetch an OIDC token without write access to id-token.

Resolution Command / Fix:
Add the permissions block at workflow root or job level in .github/workflows/deploy.yml:

permissions:
  contents: read
  id-token: write
Error: ERROR: (gcloud.iam.service-accounts.set-iam-policy) PERMISSION_DENIED: The caller does not have permission [iam.serviceAccounts.setIamPolicy]

Root Cause: The identity running the setup commands lacks the `roles/iam.serviceAccountAdmin` or `roles/resourcemanager.projectIamAdmin` role needed to grant `roles/iam.workloadIdentityUser` on the target service account.

Resolution Command / Fix:
gcloud projects add-iam-policy-binding prod-cloud-api \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountAdmin"

Frequently Asked Questions (GCP Workload Identity Federation with GitHub Actions SOP)

Q:Can I use GCP Workload Identity Federation with GitHub Actions across Codex, Claude Code, and Cursor simultaneously?

Yes. This skill adheres to the open SKILL.md specification. All runtimes that scan workspace directories (such as Cursor's `.agents/skills`, Claude Code's tools, or Codex projects) read the trigger bindings and SOP directives identically.

Q:How does GCP Workload Identity Federation prevent context window overflow during long agent sessions?

Instead of repeatedly re-injecting long cloud architecture guidelines and multi-step security policies, the skill isolates execution into a concise 4-step SOP. The agent only activates relevant WIF logic upon matching specific triggers, conserving prompt tokens for application logic.

Q:Does this skill require escalated root or container permissions?

No. The skill is audited with a security score of 98/100. It requires only standard workspace file write permissions (`fs_write: workspace`) to generate configuration files and workflows, forbidding autonomous shell executions or direct network access.

Ready to equip your autonomous agent with GCP Workload Identity Federation with GitHub Actions?

Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.

Get 1-Click Install Spec