Usa WIF con GitHub Actions

Cada ejecución de un flujo de trabajo de GitHub Actions puede solicitar un token de identidad firmado al emisor alojado de GitHub en https://token.actions.githubusercontent.com. Con Workload Identity Federation, tu flujo de trabajo intercambia ese token por un token de acceso de Anthropic de corta duración, de modo que tus trabajos de CI pueden llamar a la API de Claude sin un secreto ANTHROPIC_API_KEY almacenado en tu repositorio.

El claim sub del token codifica el repositorio y el contexto del disparador. Para un push a una rama tiene la forma repo:<owner>/<repo>:ref:refs/heads/<branch>. Las ejecuciones de pull request usan repo:<owner>/<repo>:pull_request, y los despliegues controlados por entorno usan repo:<owner>/<repo>:environment:<name>. Tu regla de federación se compara con este claim (y otros, como repository_owner y ref) para decidir qué ejecuciones de flujo de trabajo tienen permitido autenticarse.



Requisitos previos

• Familiaridad con los conceptos de WIF: cuentas de servicio, emisores de federación y reglas de federación.
• Un repositorio de GitHub donde puedas editar archivos de flujo de trabajo y otorgar el permiso id-token: write.
• Permiso para crear cuentas de servicio, emisores de federación y reglas de federación en la Claude Console para tu organización de Anthropic.
• El ID de tu organización de Anthropic. Puedes encontrarlo en la Claude Console en Settings → Organization.



Configura tu flujo de trabajo

GitHub solo emite un token de identidad a los trabajos que lo solicitan explícitamente. Agrega el permiso id-token: write a nivel de flujo de trabajo o de trabajo:

permissions:
  id-token: write
  contents: read

Dentro del trabajo, el runner expone dos variables de entorno: ACTIONS_ID_TOKEN_REQUEST_URL y ACTIONS_ID_TOKEN_REQUEST_TOKEN. Llama a la URL de solicitud con el token de solicitud como credencial bearer y tu audiencia elegida como parámetro de consulta, luego escribe el "JSON Web Token" (token web JSON), o JWT, devuelto en un archivo:

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
      | jq -r .value > /tmp/gha-jwt

Si prefieres JavaScript, actions/github-script expone la misma capacidad a través de core.getIDToken(audience):

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v8
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('https://api.anthropic.com');
      fs.writeFileSync('/tmp/gha-jwt', token);

El token decodificado contiene claims que describen la ejecución del flujo de trabajo. Tu regla de federación se compara con estos:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "aud": "https://api.anthropic.com",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "workflow": "CI",
  "actor": "octocat",
  "event_name": "push"
}

Consulta la referencia de claims de sujeto de OIDC de GitHub para ver la lista completa de formatos de sub.



Configura Anthropic

En la Claude Console, abre Settings → Workload identity, haz clic en Connect workload y selecciona el mosaico de GitHub Actions. El asistente te guía a través del registro del emisor, la creación de una cuenta de servicio y la creación de una regla de federación.

El asistente crea estos recursos por ti. Usa los siguientes valores, ya sea que los ingreses en el asistente o los envíes a la Admin API:

Emisor de federación: GitHub publica su documento de descubrimiento OIDC y su JWKS públicamente, así que usa el modo de descubrimiento. Anthropic actualiza las claves automáticamente cuando GitHub las rota.

{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks": { "type": "discovery" }
}

Regla de federación: Haz coincidir solo las ejecuciones de flujo de trabajo en las que pretendes confiar. Consulta Restringe qué flujos de trabajo pueden autenticarse para saber cómo delimitar estos claims de forma segura.

{
  "name": "gha-main",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main",
    "audience": "https://api.anthropic.com",
    "claims": {
      "repository_owner": "your-org"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Sé tan específico como lo permita la carga de trabajo. Relaja subject_prefix a repo:your-org/your-repo:* (junto con una restricción claims.ref) solo si la regla debe coincidir con múltiples tipos de eventos del mismo repositorio, porque el segmento final de sub varía entre los eventos ref:..., environment:... y pull_request.



Adquiere y usa un token

Establece las variables de entorno de federación en el trabajo y llama al SDK normalmente. Anthropic() lee ANTHROPIC_IDENTITY_TOKEN_FILE, intercambia el JWT en la primera solicitud y actualiza el token de acceso automáticamente antes de que expire.

import anthropic

# Lee ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID y ANTHROPIC_IDENTITY_TOKEN_FILE
# desde el entorno del trabajo.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Cada token de identidad emitido por GitHub expira aproximadamente cinco minutos después de su emisión. El endpoint de solicitud de tokens (ACTIONS_ID_TOKEN_REQUEST_URL) permanece válido durante todo el trabajo, por lo que puedes obtener un token nuevo en cualquier momento. El SDK intercambia el token en el primer uso y almacena en caché el token de acceso de Anthropic resultante. Para trabajos que se ejecutan durante más tiempo que la vida útil del token de Anthropic, el SDK vuelve a leer ANTHROPIC_IDENTITY_TOKEN_FILE en cada actualización, así que vuelve a ejecutar el paso de obtención periódicamente (o envuélvelo en un bucle en segundo plano) para mantener el archivo actualizado. Alternativamente, pasa al SDK un callback proveedor de tokens que llame directamente a ACTIONS_ID_TOKEN_REQUEST_URL en lugar de usar la ruta del archivo.



Verifica la configuración

Un intercambio exitoso devuelve un access_token que comienza con sk-ant-oat01- y un valor expires_in en segundos. Ante un 400 invalid_grant, consulta Solucionar problemas de un intercambio fallido; la causa más común del lado de GitHub Actions es que el formato del claim sub no coincide (su segmento final varía entre los eventos ref:..., environment:... y pull_request).



Restringe qué flujos de trabajo pueden autenticarse

Limita el bloque match de la regla al alcance más estrecho que se ajuste a tu caso de uso:

• Fija un único repositorio: Usa subject_prefix: "repo:your-org/your-repo:*" para que otros repositorios de la organización no coincidan.
• Fija una rama protegida: Agrega "ref": "refs/heads/main" (o tu rama de lanzamiento) bajo claims para que las ejecuciones de pull request y las ramas de características no coincidan.
• Fija el propietario explícitamente: Agrega "repository_owner": "your-org" bajo claims como una verificación de defensa en profundidad contra casos límite en el análisis de sub.
• Fija un entorno de despliegue: Para trabajos de despliegue, haz coincidir subject_prefix: "repo:your-org/your-repo:environment:production" y protege ese entorno con revisores requeridos en GitHub.



Próximos pasos

• Workload Identity Federation: recorrido completo de configuración, variables de entorno y precedencia de credenciales.
• Autenticación: cómo se compara la federación con las claves de API.