# Migrando para Git Nativo no SageMaker Unified Studio O SageMaker Unified Studio substituiu o modelo de sync automático por controle de versão Git flexível e granular, cobrindo Query Editor, Visual ETL, Workflows e Notebooks numa experiência unificada. Para equipes em ambientes regulados, essa mudança não é cosmética, ela redefine auditabilidade, rastreabilidade de artefatos e o modelo de governança de código analítico. Neste artigo, percorro a jornada de migração, os riscos reais e as decisões de arquitetura que fazem a diferença em produção. - URL: https://fernando.moretes.com/blog/migrando-para-git-nativo-no-sagemaker-unified-studio-amazon-sagem - Markdown: https://fernando.moretes.com/blog/migrando-para-git-nativo-no-sagemaker-unified-studio-amazon-sagem/article.md?lang=pt - Published: 2026-07-31T09:03:14.216Z - Category: IA & Agentes - Tags: sagemaker, git, mlops, governance, migration, dataops, fintech, devops - Reading time: 9 min - Source: [Amazon SageMaker Unified Studio brings richer Git version control to all project tools](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-sagemaker-unified-studio-git/) --- Controle de versão em plataformas de dados analíticos sempre foi um cidadão de segunda classe, tolerado, não projetado. O SageMaker Unified Studio acaba de mudar isso, e a migração exige mais do que clicar em 'opt in'. ## O Ponto de Partida: Sync Automático e Suas Armadilhas Antes da atualização de julho de 2026, o SageMaker Unified Studio operava com um modelo de sincronização automática entre o projeto e o repositório Git. Na superfície, isso parecia conveniente: qualquer arquivo salvo no projeto era propagado automaticamente. Na prática, em ambientes financeiros onde trabalho com frequência, esse modelo criava três problemas sérios. Primeiro, **ausência de intenção de commit**: arquivos intermediários, credenciais hardcoded acidentais, outputs de células de notebook e artefatos de debug entravam no histórico Git sem nenhuma revisão deliberada. Em uma auditoria de conformidade, cada commit precisa representar uma mudança intencional e rastreável, não o estado de um workspace em determinado momento. Segundo, **notebooks sem suporte Git algum**: a ferramenta mais usada por cientistas de dados simplesmente não participava do ciclo de versionamento. Isso forçava workflows paralelos e ad hoc, cópias manuais para S3, convenções de nomenclatura frágeis, ou o uso do terminal para operações Git fora do contexto do projeto. O resultado era divergência entre o que estava no repositório e o que estava sendo executado. Terceiro, **acoplamento rígido entre projeto e repositório**: o repositório era configurado no momento da criação do projeto e não podia ser alterado facilmente depois. Em times que evoluem suas estruturas de repositório, monorepos, repos por domínio, branches de feature de longa duração, esse acoplamento era um obstáculo real de governança. A nova experiência resolve os três. ## O Que Mudou de Fato: Anatomia do Novo Modelo O novo modelo de Repositórios no SageMaker Unified Studio introduz controle de versão em nível de arquivo para todas as ferramentas do projeto: Query Editor (SQL), Visual ETL (Glue Studio), Workflows (Step Functions / SageMaker Pipelines) e Notebooks (JupyterLab). A mudança arquitetural central é a **separação entre o ciclo de vida do projeto e o ciclo de vida do repositório**. Repositórios agora são recursos independentes que podem ser associados a um projeto a qualquer momento após sua criação. Um único projeto pode conectar-se a múltiplos repositórios e múltiplos branches simultaneamente, o que habilita, por exemplo, um time de MLOps a manter o código de feature engineering em um repo, os artefatos de pipeline em outro, e os notebooks exploratórios em um terceiro, todos visíveis dentro do mesmo workspace. A granularidade de seleção de arquivos é o diferencial operacional mais importante. O engenheiro escolhe explicitamente quais arquivos adicionar ao staging antes de cada commit. Isso não é apenas UX, é um controle de governança. Em um ambiente regulado por SOX ou PCI-DSS, a capacidade de demonstrar que apenas artefatos revisados e intencionais entram no histórico de auditoria é um requisito, não uma preferência. Para usuários de JupyterLab e Code Editor, o acesso ao Git CLI via terminal integrado permanece disponível, o que é crítico para workflows de automação que dependem de scripts de pré-commit, hooks de linting ou validação de notebooks via `nbconvert`. O modelo não remove poder dos usuários avançados, ele adiciona uma camada de governança sobre eles. ## Fluxo de Migração: Sync Automático → Git Nativo por Ferramenta Mostra a jornada de migração desde o modelo legado de sync automático até o novo modelo Git nativo, com os pontos de decisão por ferramenta e os repositórios externos suportados. ### 🏛️ Modelo Legado / Legacy Model - Auto Sync (project-level) (ci) - Notebooks (sem Git / no Git) (compute) ### 🔀 Ponto de Migração / Migration Gate - Opt-in Project Update (security) - Repositórios Desacoplados Decoupled Repos (storage) ### 🛠️ Ferramentas do Projeto / Project Tools - Query Editor (SQL) (data) - Visual ETL (Glue Studio) (data) - Workflows (Pipelines) (compute) - Notebooks (JupyterLab) (ai) ### 📦 Repositórios Externos / External Repos - GitHub (external) - GitLab (external) - Bitbucket (external) ### 🔐 Governança / Governance - IAM / IAM Identity Center (security) - File-level Staging + Commit (ci) ### Fluxos - legacy_sync -> opt_in: atualizar projeto - legacy_nb -> opt_in: habilita Git - opt_in -> repo_decouple: desacopla repo - repo_decouple -> query_ed: conecta - repo_decouple -> visual_etl: conecta - repo_decouple -> workflows: conecta - repo_decouple -> notebooks: conecta - query_ed -> file_select: staging granular - visual_etl -> file_select - workflows -> file_select - notebooks -> file_select - file_select -> github: commit + push - file_select -> gitlab: commit + push - file_select -> bitbucket: commit + push - iam_idc -> repo_decouple: autoriza acesso ## A Jornada de Migração: Decisões e Passos 1. **1. Inventário de Artefatos Existentes**: Antes de acionar o opt-in, mapeie todos os artefatos atualmente sincronizados automaticamente. Identifique notebooks com outputs persistidos (células executadas com dados sensíveis), queries SQL com parâmetros hardcoded, e definições de Visual ETL com referências a buckets S3 específicos de ambiente. Esses artefatos precisam de revisão antes de entrar em um histórico Git auditável. Use `aws s3 ls` e a API do SageMaker Unified Studio para listar os arquivos de projeto antes da migração. 2. **2. Definir a Estratégia de Repositório**: Decida entre monorepo por projeto, repos por domínio (ex: feature-engineering, pipelines, analytics-sql) ou repos por artefato. Em ambientes financeiros, recomendo repos por domínio com branches de proteção obrigatória em `main` e `release/*`. Configure regras de branch protection no GitHub/GitLab antes de conectar ao projeto: exija pull request reviews, status checks de CI e assinatura de commits (GPG/SSH) para rastreabilidade de autoria em auditorias. 3. **3. Configurar Conexões Git no Admin Guide**: Siga o Admin Guide para configurar as conexões Git no nível do domínio. As conexões suportam GitHub, GitLab e Bitbucket. Para ambientes corporativos, use tokens de acesso pessoal (PAT) com escopo mínimo, apenas `repo` para GitHub, `read_repository` + `write_repository` para GitLab, armazenados no AWS Secrets Manager e referenciados via IAM role com condição `aws:SourceVpc` para restringir acesso à VPC do SageMaker. Evite tokens de organização com escopo amplo. 4. **4. Executar o Opt-in por Projeto**: O opt-in é por projeto, não global. Em um ambiente com dezenas de projetos, planeje uma janela de migração faseada: comece com projetos de desenvolvimento/sandbox, valide o comportamento do novo modelo de staging, depois migre projetos de staging e produção. O opt-in não é reversível sem recriar o projeto, documente isso em um ADR antes de executar em projetos críticos. Verifique que todos os membros do projeto foram notificados, pois o workflow de commit muda imediatamente após o opt-in. 5. **5. Estabelecer Convenções de Commit e .gitignore**: Com o controle granular de arquivos, o risco de inconsistência aumenta: diferentes engenheiros farão staging de arquivos diferentes com mensagens de commit inconsistentes. Implemente Conventional Commits como padrão da equipe (`feat:`, `fix:`, `chore:`, `data:`). Configure um `.gitignore` específico para SageMaker Unified Studio que exclua: `*.ipynb_checkpoints`, arquivos de output de notebook, arquivos `.env`, credenciais temporárias e artefatos de execução de Glue Job. Versione o `.gitignore` como o primeiro commit do repositório. 6. **6. Integrar com CI/CD Downstream**: O push para o repositório externo deve acionar pipelines de CI/CD. Para notebooks, configure GitHub Actions ou GitLab CI para executar `nbconvert --to script` e validar com `flake8` ou `ruff`. Para Visual ETL (Glue), o JSON exportado pode ser validado com `cfn-lint` se for CloudFormation, ou com scripts Python que verificam referências de catálogo. Para Workflows (SageMaker Pipelines), valide o JSON de definição do pipeline contra o schema da API. Isso transforma o repositório em um portão de qualidade, não apenas um arquivo. ## Governança de IAM e Identidade: O Detalhe que Importa em Produção O anúncio confirma suporte tanto para domínios IAM quanto para IAM Identity Center (IDC). Essa distinção tem implicações diretas em como você modela o acesso ao repositório em ambientes corporativos. Em domínios com IAM Identity Center, os usuários são federados via SAML ou SCIM de um IdP corporativo (Okta, Azure AD, Ping). O acesso ao repositório Git externo precisa ser mapeado para identidades que o provedor externo reconhece. A abordagem que recomendo é: armazenar o PAT do repositório no Secrets Manager com uma política de recurso que permite acesso apenas à role de execução do SageMaker Unified Studio, com condição `aws:PrincipalTag/Team` para segmentar por time. Isso evita que um cientista de dados do time de crédito acesse repositórios do time de risco de mercado. Para domínios IAM puros, o modelo é mais direto, mas requer atenção ao princípio do menor privilégio nas permissões do projeto. A IAM policy da role de execução deve incluir `sagemaker:CreateProject` e `sagemaker:UpdateProject` apenas para os usuários que precisam executar o opt-in de migração, não para todos os membros do projeto. Um ponto crítico que frequentemente é negligenciado: os tokens de acesso ao repositório Git são segredos de longa duração. Implemente rotação automática via Lambda + Secrets Manager com um schedule de 30 dias, e configure alertas no CloudWatch para detectar uso de tokens próximos à expiração. Em uma auditoria PCI-DSS, a ausência de rotação de credenciais é uma não-conformidade direta. ## Observabilidade do Ciclo de Versionamento: Além do Commit Log Um erro comum em migrações de plataforma de dados é tratar o Git como o único plano de observabilidade. O histórico de commits responde 'o que mudou e quando', mas não responde 'qual versão do notebook produziu o modelo que está em produção hoje' ou 'qual query SQL gerou o relatório regulatório do mês passado'. Para fechar esse gap, implemente rastreabilidade bidirecional: cada execução de pipeline no SageMaker deve registrar o hash do commit Git que originou os artefatos de código. Isso pode ser feito via parâmetros de pipeline (`PipelineDefinitionS3Uri` + metadados customizados) ou via tags em experimentos do MLflow/SageMaker Experiments. O hash do commit vira uma chave de lookup que conecta o artefato de modelo ao código-fonte exato. No plano de métricas operacionais, monitore via CloudWatch: frequência de commits por projeto (sinal de adoção), taxa de conflitos de merge (sinal de problemas de coordenação de time), e latência entre push e execução de pipeline de CI (sinal de saúde do workflow). Para ambientes com múltiplos repositórios por projeto, o CloudWatch Logs Insights pode agregar eventos de push via CloudTrail + EventBridge para um dashboard unificado. Um padrão que tenho implementado em clientes financeiros é o **commit-triggered lineage**: ao fazer push, um Lambda acionado via EventBridge registra no DynamoDB uma entrada com `{commit_hash, project_id, author, timestamp, files_changed, downstream_pipeline_id}`. Esse registro vira a fonte de verdade para auditorias, não o console do Git, que pode ser alterado com force-push. ## Antes e Depois: Impacto Operacional da Migração - **0%**: Cobertura Git de Notebooks (antes). Notebooks não tinham suporte Git no modelo anterior; agora participam do mesmo ciclo de versionamento das demais ferramentas. - **4/4**: Ferramentas com Git Nativo (depois). Query Editor, Visual ETL, Workflows e Notebooks, todas as ferramentas do projeto agora têm controle de versão consistente. - **N:M**: Relação Projeto:Repositório (antes 1:1, depois N:M). Um projeto pode agora conectar múltiplos repositórios e branches simultaneamente, eliminando o acoplamento rígido do modelo anterior. - **~30min**: Tempo Estimado de Opt-in por Projeto (sandbox). Incluindo inventário de artefatos, configuração de conexão Git e validação pós-migração em projetos de complexidade média. > **Riscos Reais da Migração: O Que Pode Dar Errado:** **1. Irreversibilidade do opt-in**: O opt-in para o novo modelo de Git não é reversível sem recriar o projeto. Em projetos com histórico de execução, metadados de experimento e configurações de domínio, recriar o projeto implica perda de contexto operacional. Documente o estado atual em um ADR antes de migrar qualquer projeto de produção. **2. Vazamento de dados sensíveis no histórico Git**: Com o modelo anterior de sync automático, arquivos iam para o repositório sem revisão. Ao migrar, o histórico legado pode conter outputs de notebook com dados PII, tokens temporários em arquivos `.env`, ou queries SQL com valores de parâmetros reais. Execute `git log --all --full-history -- '*.env'` e ferramentas como `truffleHog` ou `gitleaks` no histórico antes de conectar o repositório ao novo modelo. **3. Divergência entre branches em projetos multi-repositório**: Com suporte a múltiplos repositórios e branches simultâneos, é possível que um engenheiro trabalhe em `feature/model-v2` em um repo enquanto outro trabalha em `main` de outro repo referenciando os mesmos dados. Sem políticas de branch explícitas e comunicação de time, isso gera inconsistências silenciosas que só aparecem em execuções de pipeline. **4. Tokens Git como superfície de ataque**: PATs armazenados para conexão com GitHub/GitLab/Bitbucket são credenciais de longa duração. Se comprometidos, permitem acesso de leitura/escrita ao repositório fora do contexto do SageMaker. Implemente rotação obrigatória, alertas de uso anômalo via CloudTrail, e restrinja os tokens ao menor escopo possível. ## Modelo Anterior vs. Novo Modelo de Repositórios | Critério | Dimensão | Sync Automático (Anterior) | Git Nativo (Novo) | | --- | --- | --- | --- | | Suporte a Notebooks | Nenhum | Completo (file-level staging) | - | | Granularidade de Commit | Projeto inteiro (automático) | Arquivo a arquivo (intencional) | - | | Acoplamento Projeto-Repositório | 1:1, definido na criação | N:M, adicionado a qualquer momento | - | | Acesso Git CLI | Limitado | Terminal integrado (JupyterLab/Code Editor) | - | | Adequação para Auditoria Regulatória | Baixa (commits não intencionais) | Alta (commits deliberados e rastreáveis) | - | | Provedores Suportados | GitHub, GitLab, Bitbucket | GitHub, GitLab, Bitbucket (mesmo conjunto) | - | ## Análise pelos Pilares Well-Architected - **security**: Controle granular de staging reduz o risco de vazamento acidental de segredos no histórico Git. PATs devem ser armazenados no Secrets Manager com rotação automática. IAM conditions com `aws:PrincipalTag` segmentam acesso por time. Commits assinados (GPG/SSH) garantem não-repúdio de autoria, crítico para SOX e PCI-DSS. - **reliability**: O desacoplamento entre projeto e repositório elimina um ponto único de falha na criação do projeto. Múltiplos repositórios por projeto permitem isolamento de falhas, um repositório indisponível não bloqueia o trabalho em outros. Resolução de conflitos in-browser reduz dependência de ferramentas externas. > **Nota do Curador:** Na minha experiência com plataformas de dados em ambientes financeiros, o maior risco desta migração não é técnico, é cultural. Times acostumados com sync automático vão resistir ao staging granular como 'burocracia', até o primeiro incidente de credencial vazada no histórico Git ou o primeiro relatório regulatório que não pode ser reproduzido porque o notebook foi alterado sem commit. O que eu faria: implementar o commit-triggered lineage no DynamoDB antes de migrar qualquer projeto de produção, usar `gitleaks` como step obrigatório no CI pipeline, e documentar a decisão de migração em um ADR com os trade-offs explícitos, especialmente a irreversibilidade do opt-in. A lição aprendida da forma difícil: governança de código analítico precisa ser projetada, não improvisada depois de um incidente. ## Veredicto: Migre, Mas com Governança Explícita O novo modelo de Repositórios do SageMaker Unified Studio é uma evolução arquitetural genuína, não um incremento de UX. A cobertura Git de Notebooks, o desacoplamento projeto-repositório e o controle granular de staging resolvem problemas reais de auditabilidade que o modelo anterior simplesmente ignorava. Para ambientes financeiros regulados, a migração não é opcional a médio prazo: a capacidade de demonstrar rastreabilidade intencional de artefatos analíticos é um requisito de conformidade crescente. A recomendação é migrar, mas com uma sequência disciplinada: inventário de artefatos legados, varredura de segredos no histórico Git existente, definição de estratégia de repositório, configuração de IAM/Secrets Manager para PATs, estabelecimento de convenções de commit e `.gitignore`, e integração com CI/CD downstream antes do opt-in em projetos de produção. O opt-in irreversível é o risco operacional mais relevante, trate-o com o mesmo rigor de uma migração de banco de dados: documente, valide em sandbox, execute com janela de manutenção e rollback plan explícito (que neste caso é recriar o projeto a partir de um backup de configuração). O sinal mais importante desta atualização não é a feature em si, é a direção: o SageMaker Unified Studio está convergindo para um IDE de dados com governança de engenharia de software de primeira classe. Times que adotarem essa disciplina agora terão vantagem operacional e regulatória significativa nos próximos 12-18 meses. ## Referências - [AWS What's New: Amazon SageMaker Unified Studio brings richer Git version control to all project tools (Jul 30, 2026)](https://aws.amazon.com/about-aws/whats-new/2026/07/amazon-sagemaker-unified-studio-git/) - [AWS Docs: Working with repositories in Amazon SageMaker Unified Studio](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/storage.html) - [AWS What's New: Amazon SageMaker Unified Studio adds S3 file sharing options to projects (Aug 2025)](https://aws.amazon.com/about-aws/whats-new/2025/08/amazon-sagemaker-unified-studio-s3-file-sharing-options) - [AWS Big Data Blog: An integrated experience for all your data and AI with Amazon SageMaker Unified Studio (Dec 2024)](https://aws.amazon.com/blogs/big-data/an-integrated-experience-for-all-your-data-and-ai-with-amazon-sagemaker-unified-studio/) - [gitleaks: Secret detection for Git repositories](https://github.com/gitleaks/gitleaks) - [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/) - [AWS Secrets Manager: Rotating secrets automatically](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)