Pular para o conteúdo
ArquiteCloud
Voltar

AWS CodeArtifact: consumindo pacotes Python privados com uv

No post anterior você viu como publicar um pacote Python privado no AWS CodeArtifact usando o uv e automatizar o processo com GitHub Actions. Se ainda não leu, confira o post sobre publicação de pacotes no CodeArtifact com uv e GitHub Actions.

Agora o foco é o outro lado: consumir o pacote já publicado. Este post cobre três cenários de instalação: no projeto local durante o desenvolvimento, dentro de uma imagem Docker, e em pipelines de GitHub Actions usando autenticação via OIDC.

O post não cobre a criação do repositório, publicação, nem o uso de repositórios upstream do PyPI público espelhados no CodeArtifact. O pacote de exemplo é o meu-pacote publicado no domínio meu-dominio e repositório meu-repositorio do post anterior.

Pré-requisitos

Região AWS

Os exemplos usam us-east-1. Substitua pela região do seu repositório CodeArtifact.

Passo 1: entender a URL do índice de instalação

A URL de instalação é diferente da URL de publicação. Essa é a primeira pegadinha ao consumir pacotes do CodeArtifact. A URL de publicação termina em /pypi/meu-repositorio/, enquanto a de instalação termina em /pypi/meu-repositorio/simple/.

O sufixo /simple/ segue a PEP 503, que define o formato de índice usado pelo pip, uv e outros instaladores Python. Qualquer ferramenta compatível com o PyPI consome o CodeArtifact a partir dessa URL.

O formato completo é:

https://<dominio>-<account-id>.d.codeartifact.<regiao>.amazonaws.com/pypi/<repositorio>/simple/

Troque <dominio>, <account-id>, <regiao> e <repositorio> pelos valores da sua conta. Essa URL ainda não contém credenciais, é apenas o endereço do índice.

Passo 2: obter o token de autenticação

A autenticação no CodeArtifact é feita com um token temporário gerado a partir das suas credenciais AWS. O token vale por até 12 horas e serve tanto para publicar quanto para instalar pacotes.

ACCOUNT_ID=$(aws sts get-caller-identity \
  --query Account --output text)

CODEARTIFACT_TOKEN=$(aws codeartifact get-authorization-token \
  --domain meu-dominio \
  --domain-owner "$ACCOUNT_ID" \
  --query authorizationToken \
  --output text)
Permissão sts:GetServiceBearerToken

Para o comando acima funcionar, o IAM da sua conta precisa da permissão sts:GetServiceBearerToken junto com codeartifact:GetAuthorizationToken. Sem ela, o comando falha com erro de acesso negado que não é óbvio nas mensagens padrão.

O token é apenas uma string, mas tratá-lo como senha é essencial. Não o commite em arquivos, não o imprima em logs públicos e prefira sempre passá-lo via variável de ambiente.

Passo 3: configurar o uv no projeto local

Com o token em mãos, declare o índice privado no pyproject.toml do projeto que vai consumir o pacote:

# pyproject.toml
[[tool.uv.index]]
name = "codeartifact"
url = "https://meu-dominio-ACCOUNT_ID.d.codeartifact.us-east-1.amazonaws.com/pypi/meu-repositorio/simple/"
explicit = true

Substitua ACCOUNT_ID pelo ID real da sua conta. Cada campo:

Exporte o token nas variáveis de ambiente que o uv reconhece. O nome das variáveis segue o padrão UV_INDEX_<NOME_EM_MAIUSCULAS>_USERNAME e _PASSWORD:

export UV_INDEX_CODEARTIFACT_USERNAME="aws"
export UV_INDEX_CODEARTIFACT_PASSWORD="$CODEARTIFACT_TOKEN"

O nome de usuário é sempre aws ao autenticar no CodeArtifact via protocolo PyPI. Agora adicione o pacote como qualquer outra dependência, indicando o índice:

uv add meu-pacote --index codeartifact

O uv atualiza o pyproject.toml com a dependência vinculada ao índice:

# pyproject.toml
[project]
dependencies = [
  "meu-pacote",
]

[tool.uv.sources]
meu-pacote = { index = "codeartifact" }
Script para renovar o token

Como o token expira em 12 horas, salve o comando do passo 2 em um script shell (ex. scripts/codeartifact-login.sh) e rode com source sempre que começar a trabalhar no projeto. Isso evita repetir o passo a passo manual todo dia.

Passo 4: consumir o pacote em Docker

Quando o uv sync ou uv pip install roda dentro de um Dockerfile, o token precisa chegar ao build sem acabar persistido no histórico da imagem. A forma correta é usar BuildKit secrets, não ARG ou ENV.

Com ARG, o valor fica visível em docker history e em qualquer camada que o referencie. Com --secret, o Docker expõe o valor como arquivo apenas durante o passo que o requisita, sem gravar em nenhuma camada.

# Dockerfile
# syntax=docker/dockerfile:1.7

FROM python:3.12-slim

RUN pip install --no-cache-dir uv

WORKDIR /app
COPY pyproject.toml uv.lock ./

RUN --mount=type=secret,id=codeartifact_token,env=UV_INDEX_CODEARTIFACT_PASSWORD \
    UV_INDEX_CODEARTIFACT_USERNAME=aws \
    uv sync --frozen --no-dev

COPY . .

CMD ["uv", "run", "python", "-m", "meu_app"]

A opção --mount=type=secret,id=codeartifact_token,env=... monta o valor do secret diretamente na variável de ambiente só pela duração do RUN. O token nunca entra em uma camada da imagem.

Para construir, exporte o token antes e passe para o build:

export CODEARTIFACT_TOKEN=$(aws codeartifact get-authorization-token \
  --domain meu-dominio \
  --domain-owner "$ACCOUNT_ID" \
  --query authorizationToken \
  --output text)

CODEARTIFACT_TOKEN="$CODEARTIFACT_TOKEN" docker build \
  --secret id=codeartifact_token,env=CODEARTIFACT_TOKEN \
  -t meu-app .
Nunca use ARG para o token

Um ARG CODEARTIFACT_TOKEN seguido de ENV ou de uso direto grava o valor nas camadas da imagem. Qualquer pessoa com acesso ao registro (ex. ECR, Docker Hub) extrai o token com docker history --no-trunc.

Passo 5: consumir em GitHub Actions com OIDC

Em CI/CD, o fluxo é o mesmo do post de publicação: GitHub emite um token OIDC, a AWS valida e concede credenciais temporárias para uma role IAM. A diferença é que a role de consumo precisa apenas de permissões de leitura, não de escrita, e a condição de confiança geralmente permite execução em pushes ou pull requests, não só em tags.

Role IAM com permissões de leitura

Crie uma política específica para consumo:

# codeartifact-read-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codeartifact:GetAuthorizationToken",
        "codeartifact:GetRepositoryEndpoint",
        "codeartifact:ReadFromRepository",
        "sts:GetServiceBearerToken"
      ],
      "Resource": "*"
    }
  ]
}

A permissão codeartifact:ReadFromRepository é a que autoriza o download dos pacotes. A role de publicação do post anterior usava PublishPackageVersion e PutPackageMetadata, que não aparecem aqui.

A política de confiança da role segue o mesmo modelo do post anterior, mas sem restringir a execução a tags. Para permitir qualquer branch do repositório:

# trust-policy-read.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub":
            "repo:ORG/REPO:*"
        }
      }
    }
  ]
}

Crie a role e anexe a política:

aws iam create-role \
  --role-name GitHubActions-CodeArtifact-Read \
  --assume-role-policy-document file://trust-policy-read.json

aws iam put-role-policy \
  --role-name GitHubActions-CodeArtifact-Read \
  --policy-name CodeArtifactRead \
  --policy-document file://codeartifact-read-policy.json

Adicione o ARN da nova role como secret AWS_READ_ROLE_ARN no repositório (Settings > Secrets and variables > Actions).

Workflow de instalação

Crie .github/workflows/ci.yml:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_READ_ROLE_ARN }}
          aws-region: us-east-1

      - name: Get CodeArtifact token
        run: |
          TOKEN=$(aws codeartifact get-authorization-token \
            --domain meu-dominio \
            --domain-owner ${{ secrets.AWS_ACCOUNT_ID }} \
            --query authorizationToken \
            --output text)
          echo "::add-mask::$TOKEN"
          echo "UV_INDEX_CODEARTIFACT_PASSWORD=$TOKEN" >> "$GITHUB_ENV"
          echo "UV_INDEX_CODEARTIFACT_USERNAME=aws" >> "$GITHUB_ENV"

      - name: Install dependencies
        run: uv sync --frozen

      - name: Run tests
        run: uv run pytest

Cada parte relevante:

Observações importantes

Recapitulando

Neste post você configurou o uv para instalar um pacote privado hospedado no AWS CodeArtifact em três cenários: no desenvolvimento local, dentro de uma imagem Docker usando BuildKit secrets para não vazar o token, e em pipelines do GitHub Actions com OIDC e uma role IAM de somente leitura. Agora o ciclo está completo: você publica com uma role de escrita restrita a tags Git e consome com uma role de leitura em qualquer branch, sempre com credenciais temporárias e sem chaves de acesso de longa duração armazenadas como secret.


Compartilhe este post:

Post anterior
Deploy seguro de uma aplicação na AWS: rede, domínio, HTTPS e autenticação