Pré-requisitos: Migração GitLab para GitLab self-managed

Documento enviado ao cliente depois da escolha do serviço PS-MIG-01 — Migração GitLab para GitLab self-managed. Lista o que o cliente provisiona, as credenciais que entrega, as informações a enviar à Pointer, o checklist de prontidão e a matriz do que é migrado. O prazo de devolução das informações e do checklist é definido no kick-off.

Os itens do checklist marcados como Preflight automático são conferidos pelo pipeline Pointer contra a origem e o destino reais antes da primeira onda; os demais são conferidos na reunião de prontidão ou pelo próprio cliente. Nenhuma onda é executada com erro no preflight.

1. Origem e destino suportados
2. Configuração da instância de destino
3. Preparação da instância de origem
4. Host de migração
5. Runner do engajamento
6. Rede
7. Usuários e contribuições
8. Governança da migração
9. Critérios de aceite por onda
10. Método por arquivo: diferenças em relação ao Direct Transfer
11. Entrega das credenciais
12. Credenciais que o cliente entrega à Pointer
13. Informações a enviar
14. Matriz de itens migrados
15. Checklist de prontidão

1. Origem e destino suportados

2. Configuração da instância de destino

3. Preparação da instância de origem

• Origem GitLab self-managed: Direct Transfer habilitado também na origem por um administrador. A documentação GitLab exige a opção nas duas instâncias; o preflight confere só o destino.
• Default minimum role required to create projects diferente de No one: com No one, grupos com projetos não são importados (documentação GitLab).
• Snippets habilitados no projeto de origem para que os snippets sejam importados.
• Espaço livre em /tmp na origem self-managed e, com object storage, proxy_download habilitado.
• Nível de assinatura da origem (Free, Premium ou Ultimate) informado no formulário.
• Preparativos da documentação do GitLab Congregate: limpar repositórios (exportação abaixo de 5 GB por projeto) e tags de registry sem uso; consolidar usuários (remover, pular ou migrar inativos); congelamento de escrita comunicado por broadcast message e, opcionalmente, modo de manutenção.

4. Host de migração

5. Runner do engajamento

6. Rede

7. Usuários e contribuições

• Direct Transfer: usuários nunca são criados pela migração; contribuições e memberships vão para usuários placeholder mesmo quando existe no destino um usuário com o mesmo e-mail (documentação GitLab).
• Criação de usuários pelo GitLab Congregate (opcional): exige token de administrador na origem e no destino; o administrador da origem é criado como <usuário>_migrated quando o nome já existe.
• Usuários já provisionados no destino (LDAP ou SAML): só a reatribuição em lote, sem criação.
• Correspondência origem → destino: por e-mail (padrão, pela API de administrador da origem), por username ou por planilha origem → destino, que vale antes das outras duas. Reatribuição com origem GitLab.com: sob consulta; escopo e condições definidos em proposta específica, com execução piloto.
• Reatribuição dos usuários placeholder: pedida pelo Owner do grupo de topo; com a opção de reatribuição sem confirmação ligada no destino, é imediata.
• Método por arquivo: não há usuários placeholder. Autoria e memberships são mapeados na importação pelo e-mail público da origem igual ao e-mail primário no destino; usuário inexistente no destino nesse momento fica com a autoria na conta da importação, sem reatribuição depois. Por isso os usuários são criados ou provisionados antes da primeira onda. Membros com papel Owner são importados como Maintainer.
• A conta dona do token do destino é a conta da importação: recebe as contribuições sem usuário correspondente.

8. Governança da migração

• Aprovador de cada onda e do rollback, do lado do cliente.
• Janela de manutenção de cada onda e congelamento de escrita na origem durante a janela.
• Responsável pelos usuários placeholder sem correspondente (Owner do grupo de topo) e prazo.
• Responsável pela revisão e aprovação dos merge requests de reescrita de referências.
• Momento do corte (arquivamento da origem) e comunicação aos usuários.
• Responsável por cada item de tratamento manual da matriz.

9. Critérios de aceite por onda

• Relatório da onda sem erro: todo item existe no destino, número de projetos igual ao da origem, Direct Transfer finished, branches, tags, issues e merge requests iguais na contagem independente.
• Falhas de relação e divergências de contagem (alertas) analisadas e aceitas ou corrigidas, com registro no registro de decisões. Sem usuários no destino, é esperado que regras de aprovação fiquem sem aprovadores e que contribuições e memberships fiquem em usuários placeholder.
• Com reatribuição: todos os usuários reatribuídos (ou aguardando aceite, se o destino exigir confirmação), aprovadores das regras reaplicados e autoria em placeholder e membros iguais na contagem.
• Bytes de LFS menores logo após a migração podem ser atraso das estatísticas do destino: nova conferência antes de abrir chamado.
• Validação funcional pelo cliente nos projetos críticos da onda: clone, merge requests, issues e pipelines.

10. Método por arquivo: diferenças em relação ao Direct Transfer

• Merge requests: só o último diff é preservado; só o último pipeline do merge request fica visível.
• Pipelines importados ficam arquivados; agendamentos chegam inativos e atribuídos ao usuário que fez a importação.
• Membros com papel Owner são importados como Maintainer. Membros herdados viram membros diretos quando a exportação é feita pelo Owner do grupo de topo; com o grupo de topo não migrado, a importação por arquivo adiciona como membros diretos do projeto os membros herdados desse grupo.
• Níveis de acesso de branches e tags protegidas voltam para Maintainer, salvo quando quem importa é Owner do grupo de topo ou administrador.
• Não exportados: tokens de trigger, logs e artefatos de jobs, container registry, variáveis de CI/CD, allowlist do job token, webhooks, tokens criptografados, número de aprovações exigidas, limites de tamanho de repositório, deploy keys com push em branch protegida, secure files, políticas de segurança, links entre issues e itens vinculados, links para merge requests relacionados e variáveis de agendamentos.
• Regras de aprovação: só Approvals for protected branches e Eligible approvers.
• Deploy keys não são importadas pela exportação; o pós-importação do GitLab Congregate as recria.
• Exportação por arquivo de grupos está descontinuada pela GitLab. No pipeline, onda só de subgrupos roda com opção própria, e onda que mistura grupo de topo e subgrupo solto é recusada: grupo de topo e subgrupo avulso ficam em ondas separadas.
• O usuário que fez o merge de um merge request mergeado não é preservado.

11. Entrega das credenciais

Cada credencial é cadastrada como variável de CI/CD do projeto do engajamento, com as opções Protected e Masked and hidden e escopo restrito ao ambiente de migração, que é protegido e exige aprovação para a migração e o rollback de cada onda. O pipeline lista, sem valores, as variáveis exigidas pelo plano, e o preflight reprova se faltar alguma. A configuração do GitLab Congregate com os tokens só existe durante cada job no host de migração.

Tokens nunca são colados em chat, issue ou arquivo; se isso ocorrer, o token é revogado e outro é emitido. No encerramento, os tokens usados na origem e no destino são revogados e as contas de administrador criadas para o engajamento são desativadas.

12. Credenciais que o cliente entrega à Pointer

Nenhum valor secreto é enviado por e-mail, chat, issue ou arquivo. Cada credencial é cadastrada como variável de CI/CD protegida no projeto do engajamento, com escopo do ambiente, e revogada no encerramento.

13. Informações a enviar

Informações sem sigilo, devolvidas pelo cliente antes da reunião de prontidão. Os campos marcados como obrigatórios são conferidos pela validação automática do pipeline.

Origem

Destino

Host de migração e rede

Usuários

Ondas

Pós-migração e corte

Contatos

14. Matriz de itens migrados

O tratamento de cada item segue a documentação oficial do método de migração e é conferido na onda piloto do engajamento.

Grupos

Issues, épicos e planejamento

Repositório

Merge requests

CI/CD

Pacotes e registries

Configurações, membros e integrações do projeto

Instância

Notas da matriz

• A confirmar na onda piloto (tratamento não classificado pelo pipeline Pointer; definido no plano de ondas e conferido na onda piloto): configurações das cadências de iteração, push rules de grupo e campos personalizados de grupo e projeto (a documentação GitLab lista os três como não suportados pelo Direct Transfer); domínios do GitLab Pages (não suportados pelo Direct Transfer); tokens de acesso pessoais, de projeto e de grupo e tokens criptografados (a documentação GitLab informa que usuários e os tokens que criam são excluídos da migração); configurações da instância, aparência, broadcast messages e variáveis de instância (fora do Direct Transfer; o GitLab Congregate informa que ainda não suporta).
• A confirmar na onda piloto (sem tratamento definido nas fontes): módulos Terraform do Infrastructure Registry (a documentação GitLab lista como não suportado pelo Direct Transfer e a matriz do GitLab Congregate como suportado, sem etapa específica no pipeline); relação de fork (suportada segundo a matriz do GitLab Congregate, sem etapa específica no pipeline); chaves SSH e GPG dos usuários criados pelo GitLab Congregate (a documentação do GitLab Congregate orienta verificar as chaves no destino e criar novas se faltarem).
• Nível de assinatura: com o nível da origem informado errado, o GitLab Congregate ignora sem erro itens pagos como regras de aprovação, webhooks de grupo e de projeto e push rules.
• O pós-importação do GitLab Congregate desarquiva temporariamente os projetos arquivados na origem e no destino para aplicar os itens e depois os arquiva de novo.
• URLs em notas e descrições só são reescritas para links do próprio grupo ou projeto migrado; links para outros projetos da origem permanecem (a reescrita de referências nos arquivos dos repositórios é tratada à parte).
• Após o início da migração de uma onda, alterações na origem podem não ser copiadas para o destino.
• Método por arquivo: as diferenças em relação a esta matriz estão na seção “Método por arquivo: diferenças em relação ao Direct Transfer”.

15. Checklist de prontidão

Itens conferidos antes da execução. "Preflight automático" indica verificação feita pelo pipeline contra o ambiente real; os demais são conferidos na reunião de prontidão ou pelo cliente.