> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Permita que o GitHub Actions obtenha credenciais temporárias de implantação no Basaltic com a identidade do job.

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](https://docs.basaltic.sh/pt/iam/roles.md#trusting-an-oidc-provider) na mesma conta da role de implantação. Use estes valores:

> [tab] API
>
> ```json theme={null}
> {
>   "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](https://docs.basaltic.sh/pt/iam/roles.md) 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`:

```json theme={null}
{
  "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](https://docs.github.com/en/actions/reference/security/oidc#example-subject-claims).

| 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](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) 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](https://docs.basaltic.sh/pt/iam/policies.md) 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:

```json theme={null}
{
  "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.

```yaml .github/workflows/deploy.yml theme={null}
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](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers).

## 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](https://docs.basaltic.sh/pt/iam/oidc.md#troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.