GitHub Actions

Use a identidade de um job do GitHub Actions para obter uma sessão temporária de implantação no Basaltic. Não é necessário armazenar uma chave de acesso Basaltic de longa duração no GitHub. O job solicita um JWT OIDC do GitHub e o troca no endpoint AssumeRoleWithWebIdentity do Basaltic. O token bearer resultante autoriza chamadas de implantação à API conforme as políticas da role Basaltic.

Registrar o GitHub na conta de implantação

Siga o registro de provedor na mesma conta da role de implantação. Use estes valores:

{
  "name": "github",
  "issuer": "https://token.actions.githubusercontent.com",
  "audiences": ["urn:example:basaltic:production"]
}

A audiência é o identificador escolhido para essa troca. Use exatamente o mesmo valor no provedor, na política de confiança e no workflow. O guia AWS usa sts.amazonaws.com como audiência de exemplo.

Restringir a role ao seu workflow

Crie uma role IAM chamada github-deployer na conta production. A política de confiança deve indicar seu provedor e o sujeito GitHub exato. Este exemplo usa um ambiente protegido chamado production:

{
  "principals": ["crn:iam::production:oidc-provider/github"],
  "conditions": [
    {
      "operator": "equals",
      "key": "basalt:webidentity:Subject",
      "values": ["repo:acme@123456/app@789012:environment:production"]
    },
    {
      "operator": "equals",
      "set_operator": "for_any_value",
      "key": "basalt:webidentity:Audience",
      "values": ["urn:example:basaltic:production"]
    }
  ]
}

Substitua o proprietário, repositório e IDs do exemplo pelo sub exato do seu token. O GitHub aceita formatos de sujeito baseados em nomes e em IDs imutáveis. Renomeações, transferências ou personalizações podem alterar o valor. Consulte a referência de sujeitos do GitHub.

Escopo do job	Exemplo de sujeito
Ambiente	`repo:acme@123456/app@789012:environment:production`
Branch sem ambiente	`repo:acme@123456/app@789012:ref:refs/heads/main`
Ambiente antigo baseado em nome	`repo:acme/app:environment:production`
Branch antiga baseada em nome	`repo:acme/app:ref:refs/heads/main`

Um sujeito de ambiente não restringe também a branch. Configure a proteção de ambientes do GitHub para limitar branches e aprovações de implantação. O workflow de exemplo usa um ambiente, portanto a confiança deve usar o sujeito de ambiente. O Basaltic avalia emissor, sujeito e audiência verificados. Claims como repository_id, ref e job_workflow_ref não são chaves de política separadas no Basaltic. Coloque as restrições necessárias no sujeito aceito e na configuração do ambiente GitHub.

Conceder permissões de implantação

Anexe políticas de permissão para os recursos específicos alterados pela implantação. A confiança permite autenticação; ela não concede acesso de implantação. Para executar a verificação abaixo, adicione esta pequena política e depois as permissões de implantação da aplicação separadamente:

{
  "version": "2024-01-01",
  "statements": [{
    "effect": "allow",
    "actions": ["iam:GetRole"],
    "resources": ["crn:iam::production:role/github-deployer"]
  }]
}

Obter uma sessão no GitHub Actions

Adicione o workflow abaixo após substituir os valores de conta, role, audiência e ambiente. A permissão id-token: write do GitHub permite ao job solicitar seu token de identidade; as permissões Basaltic continuam vindo da role. A troca não usa credenciais Basaltic preexistentes. Defina BASALTIC_ROLE_ID como o UUID retornado ao criar a role; o endpoint de verificação recebe um UUID.

.github/workflows/deploy.yml

name: Deploy to Basaltic
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read
      id-token: write
    env:
      BASALTIC_ACCOUNT: production
      BASALTIC_ROLE: crn:iam::production:role/github-deployer
      BASALTIC_ROLE_ID: REPLACE_WITH_ROLE_UUID
      BASALTIC_AUDIENCE: urn:example:basaltic:production
    steps:
      - name: Exchange GitHub identity
        shell: bash
        run: |
          python3 - <<'PYTHON'
          import json, os, urllib.parse, urllib.request

          url = os.environ["ACTIONS_ID_TOKEN_REQUEST_URL"]
          separator = "&" if "?" in url else "?"
          url += separator + urllib.parse.urlencode({"audience": os.environ["BASALTIC_AUDIENCE"]})
          request = urllib.request.Request(url, headers={
              "Authorization": "Bearer " + os.environ["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]
          })
          with urllib.request.urlopen(request, timeout=30) as response:
              proof = json.load(response)["value"]
          print("::add-mask::" + proof)
          body = json.dumps({
              "role": os.environ["BASALTIC_ROLE"],
              "web_identity_token": proof,
              "session_name": "github-" + os.environ["GITHUB_RUN_ID"],
              "duration_seconds": 900
          }).encode()
          request = urllib.request.Request(
              "https://iam.basaltic.sh/v1/assume-role-with-web-identity",
              data=body, headers={"Content-Type": "application/json"}
          )
          with urllib.request.urlopen(request, timeout=30) as response:
              session = json.load(response)
          token = session["access_token"]
          print("::add-mask::" + token)
          with open(os.environ["GITHUB_ENV"], "a") as output:
              output.write("BASALTIC_TOKEN=" + token + "\n")
          PYTHON
      - name: Verify deployment role
        shell: bash
        run: |
          curl --fail --silent --show-error \
            -H "Authorization: Bearer $BASALTIC_TOKEN" \
            -H "X-Account-Id: $BASALTIC_ACCOUNT" \
            "https://iam.basaltic.sh/v1/roles/$BASALTIC_ROLE_ID" > /dev/null

Use BASALTIC_TOKEN nas etapas seguintes de implantação como token bearer HTTP. Substitua ou complemente a verificação com seus comandos de implantação, concedendo apenas as ações IAM necessárias. Essa variável é definida pelo exemplo; as ferramentas precisam de sua própria configuração documentada de token. Não imprima o token nem envie a resposta da troca como artefato. O exemplo solicita uma sessão de 15 minutos. Para jobs mais longos, obtenha uma nova prova GitHub e troque-a novamente antes de a sessão Basaltic expirar. Não há refresh token nesse fluxo. Consulte as orientações de workflow OIDC do GitHub.

Solução de problemas

Um 401 na troca costuma indicar registro do emissor, audiência, assinatura ou expiração. Um 403 indica confiança da role: compare o sujeito exato, incluindo IDs imutáveis, branch versus ambiente e o operador de conjunto da audiência. Um 403 após autenticar indica permissões ausentes ou um limite de permissões. Consulte a visão geral de federação.

Primeiros passos

Produtos

Plataforma

Ajuda

Registrar o GitHub na conta de implantação

Restringir a role ao seu workflow

Conceder permissões de implantação

Obter uma sessão no GitHub Actions

Solução de problemas

​Registrar o GitHub na conta de implantação

​Restringir a role ao seu workflow

​Conceder permissões de implantação

​Obter uma sessão no GitHub Actions

​Solução de problemas

Registrar o GitHub na conta de implantação

Restringir a role ao seu workflow

Conceder permissões de implantação

Obter uma sessão no GitHub Actions

Solução de problemas