Migração de repositórios de um workspace do Bitbucket Cloud (bitbucket.org) para a instância GitLab self-managed do cliente, inclusive uma instância implantada pela Pointer. Cada onda usa o importador Bitbucket Cloud da instância de destino, recurso nativo da plataforma GitLab, disparado pelo GitLab Congregate a partir do pipeline Pointer, seguido das etapas pós-migração do GitLab Congregate e da verificação da importação por projeto. A autoria fica na conta da importação quando o usuário do destino não tem a identidade Bitbucket vinculada.
1. Para quem
- Workspaces no Bitbucket Cloud cujos repositórios e pull requests passam para uma instância GitLab self-managed do cliente.
- Equipes que substituem o Bitbucket Cloud pela instância GitLab self-managed como repositório de código e revisão de mudanças.
2. Onde executamos
O host de migração fica na rede do cliente (data center próprio ou nuvem), só com conexões de saída. O importador Bitbucket Cloud é executado pela instância GitLab de destino, que busca os dados no Bitbucket Cloud por HTTPS.
3. Escopo do serviço
- Discovery de migração: workspace, projetos e repositórios, pull requests, uso de issues e wiki, LFS, permissões de branch, Bitbucket Pipelines e integrações.
- Plano de ondas por repositório (chave do projeto/repositório), também por planilha, com destino de cada repositório, janela, aprovador e janela de rollback.
- Preparação do projeto do engajamento e da stack do GitLab Congregate no host de migração do cliente, com verificação prévia (preflight) do destino.
- Execução das ondas pelo importador Bitbucket Cloud: onda piloto, simulação, importação com aprovação, etapas pós-migração do GitLab Congregate e verificação da importação por projeto.
- Rollback da onda dentro da janela acordada.
- Encerramento: remoção dos dados do engajamento no host de migração, remoção do runner, revogação dos tokens e relatório de encerramento.
4. Origem, destino e método suportados
Disponível Ofertado nas condições deste documento.
| Origem | Destino | Método | Versões mínimas | Estado |
|---|---|---|---|---|
| Bitbucket Cloud (bitbucket.org) | GitLab self-managed | Importador Bitbucket Cloud da instância de destino, disparado pelo GitLab Congregate | Destino 18.9 ou superior (importação com API token; app passwords removidas na versão 19.0) | Disponível |
- Issues, wiki, milestones, LFS e membros: sob consulta; escopo e condições definidos em proposta específica, com execução piloto.
- Destino: somente GitLab self-managed, inclusive instância implantada pela Pointer. GitLab.com e GitLab Dedicated como destino estão no roadmap.
- Bitbucket Server/Data Center e AWS CodeCommit estão no roadmap; a atribuição de autoria no Bitbucket Cloud por identidade vinculada também.
- Com origem Bitbucket Cloud não há arquivamento da origem, reescrita de referências nos repositórios nem contagem independente origem × destino; a verificação usa o status e as estatísticas da importação de cada projeto.
- Outras origens: GitLab (PS-MIG-01), GitHub (PS-MIG-02) e Azure DevOps (PS-MIG-03).
5. Recursos configurados
● Nativo — recurso da plataforma GitLab◐ Requer configuração○ Integração externa — depende de serviço do cliente ou de terceiro
| Recurso | Classificação | Detalhe |
|---|---|---|
| Importador Bitbucket Cloud | Nativo | Recurso nativo da plataforma GitLab, executado pela instância de destino com o e-mail da conta Atlassian e o API token repassados pelo GitLab Congregate. |
| Ondas de repositórios, também por planilha | Requer configuração | Cada onda lista repositórios pelo caminho chave do projeto/repositório do workspace. Destino = grupo pai no destino + chave do projeto + repositório. |
| Simulação da onda | Requer configuração | Execução do GitLab Congregate em modo simulação, sem criar nada no destino; caminho de destino já ocupado reprova a onda. Com importadores, a conferência do pacote simulado contra o plano gera alerta. |
| Etapas pós-migração do GitLab Congregate | Requer configuração | Depois da importação: membros do repositório adicionados ao projeto de destino e repositório arquivado na origem arquivado também no destino. |
| Verificação da importação por projeto | Requer configuração | Por API na instância de destino: importação com falha reprova a onda; relações com falha e diferença entre objetos lidos e importados geram alerta. |
| Rollback da onda na janela | Requer configuração | Remove do destino os projetos e grupos da onda criados dentro da janela (padrão 24 horas, de 1 a 720 horas), com exclusão agendada ou permanente. |
| Tratamento de segredos no host | Requer configuração | A configuração do GitLab Congregate com os tokens é gerada no início de cada job e apagada no fim; toda saída passa por um sanitizador que remove os tokens e mascara e-mails. O e-mail da conta Atlassian fica em variável do ambiente, fora do repositório do engajamento. |
6. Ferramentas
Ferramenta da GitLab Professional Services (licença MIT)
GitLab Congregate
Versão 8.6.0 fixada por digest, com MongoDB e Redis também fixados, em uma stack de contêineres exclusiva do engajamento no host de migração. Lista o workspace, dispara o importador Bitbucket Cloud da instância de destino e executa as etapas pós-migração.
Recurso nativo da plataforma GitLab
Importador Bitbucket Cloud
Importa repositório, descrição, pull requests e comentários, issues, milestones, wiki, labels e LFS; executado pela instância de destino.
Ferramenta Pointer
psctl
Valida o plano de migração, gera e apaga a configuração do GitLab Congregate em cada job, executa o preflight, resolve cada onda, verifica cada importação e gera os relatórios, com saídas sanitizadas.
Componente oficial da GitLab
GitLab Runner
Runner de executor shell, exclusivo do projeto do engajamento, instalado no host de migração do cliente.
7. Como o pipeline Pointer executa
- Validação do plano de migração (automática a cada alteração): origem, workspace, destino, host, ondas e variáveis exigidas.
- Preparação do host de migração: stack do GitLab Congregate com versões fixas, sem portas publicadas.
- Verificação prévia da migração (automática): token e versão do destino, fonte de importação Bitbucket Cloud habilitada, grupo pai no destino e configuração do GitLab Congregate.
- Inventário da origem: repositórios do workspace e repositórios fora de ondas.
- Por onda: Simulação da onda → Migração da onda (com aprovação), com etapas pós-migração e verificação da importação por projeto.
- Depois da onda, quando necessário: Reversão da onda (rollback) dentro da janela.
- Encerramento: remoção dos dados do host.
8. Metodologia
Assessment → Implantação → Otimização → Transferência de conhecimento.
Fase 1
Assessment
- Kick-off: escopo (workspace, projetos, repositórios, volumes), janelas, congelamento de escrita no Bitbucket Cloud por onda, aprovadores de cada onda e do rollback.
- Discovery de migração: pull requests, uso de issues e wiki, LFS, permissões de branch, regras de aprovação, Bitbucket Pipelines, webhooks e integrações; respostas no registro de decisões do engajamento.
- Envio do documento de pré-requisitos (PR-MIG-04) e acompanhamento do checklist de prontidão.
- Criação do projeto do engajamento e validação do plano de migração pelo pipeline.
- Preparação do host de migração, verificação prévia (preflight) sem erro e inventário da origem.
- Plano de ondas: onda piloto e ondas seguintes, sem repositório fora de onda sem decisão registrada.
Fase 2
Implantação
- Onda piloto: simulação, importação e validação funcional com o cliente (clone, merge requests e, quando usados, issues e wiki).
- Ondas seguintes: uma janela por onda, com congelamento de escrita no Bitbucket Cloud durante a janela.
- Verificação da importação de cada repositório; alertas analisados e registrados; rollback dentro da janela quando necessário.
Fase 3
Otimização
- Pós-migração: permissões de branch, Bitbucket Pipelines convertidos para GitLab CI/CD, runners e integrações no destino, conforme os responsáveis do plano.
- Comunicação aos usuários sobre o fim do uso dos repositórios no Bitbucket Cloud (o pipeline não arquiva a origem Bitbucket Cloud).
Fase 4
Transferência de conhecimento
- Revisão dos relatórios das ondas e dos alertas aceitos com a equipe do cliente.
- Entrega do repositório do engajamento com o plano, o registro de decisões e os relatórios.
- Encerramento: remoção dos dados do engajamento no host de migração, remoção do runner, revogação dos tokens, relatório de encerramento e aceite.
9. Entregáveis
| Entregável | Descrição | Formato |
|---|---|---|
| Relatório de verificação prévia | Destino, fonte de importação, versão do GitLab Congregate, erros e alertas. | Markdown (artefato do pipeline) |
| Inventário da origem | Repositórios do workspace, onda e destino de cada um e repositórios fora de ondas; sem tokens, e-mails ou membros. | Markdown e CSV (artefato do pipeline) |
| Plano de ondas | Repositórios de cada onda e destino de cada um, validado pelo pipeline. | Repositório do engajamento (YAML e CSV) e Markdown por onda |
| Relatório de simulação de cada onda | Resultado da simulação e caminhos de destino livres. | Markdown (artefato do pipeline) |
| Relatório de cada onda | Existência de cada repositório no destino, status da importação e estatísticas por projeto (objetos lidos × importados) e relações com falha. | Markdown e JSON (artefato do pipeline) |
| Relatório de rollback | Quando executado: estado de cada projeto e grupo da onda no destino após o rollback. | Markdown (artefato do pipeline) |
| Registro de decisões | Decisões do engajamento: ondas, exceções, alertas aceitos e itens de tratamento manual. | Repositório do engajamento |
| Relatório de encerramento | Resultado das ondas, alertas aceitos, itens de tratamento manual, remoção dos dados do host e do runner e revogação dos tokens. | Documento |
10. Premissas
- A instância GitLab self-managed de destino está instalada e em operação, na versão 18.9 ou superior, com a integração Bitbucket Cloud e a fonte de importação Bitbucket Cloud habilitadas.
- Sem identidade Bitbucket vinculada ao usuário do destino, pull requests e comentários ficam na conta da importação, com referência ao autor original (documentação GitLab); não há reatribuição depois.
- O pipeline não cria usuários a partir do Bitbucket Cloud: os usuários do destino já existem (LDAP, SAML ou cadastro).
- Imagens e anexos inline em Markdown continuam como links para o Bitbucket Cloud e deixam de funcionar se o repositório de origem for apagado.
- Repositórios da onda não recebem alterações no Bitbucket Cloud durante a janela da onda.
- O rollback só remove o que a onda criou dentro da janela acordada.
- Os relatórios ficam como artefatos dos jobs no projeto do engajamento: 90 dias para a preparação do host e o preflight, 1 ano para os demais.
- Cada engajamento usa uma versão fixa dos componentes do pipeline e do GitLab Congregate; mudança de versão só por merge request.
Fora do escopo
- Bitbucket Server/Data Center e AWS CodeCommit como origem (roadmap).
- Destino GitLab.com ou GitLab Dedicated (roadmap).
- Atribuição de autoria por identidade Bitbucket vinculada (roadmap).
- Itens classificados como “não migra” na matriz do documento de pré-requisitos; recriação só por acordo.
- Operação sem acesso à internet no host de migração (air-gapped), que está no roadmap.
Responsabilidades do cliente
- Instância de destino na versão 18.9 ou superior, com a integração e a fonte de importação Bitbucket Cloud habilitadas e grupo pai privado ou interno.
- Host de migração dedicado com Docker, runner shell do engajamento e rede: host → Bitbucket Cloud, destino e serviços da GitLab; destino → Bitbucket Cloud por HTTPS.
- API token da Atlassian com os escopos exigidos, e-mail da conta Atlassian e token de administrador do destino, cadastrados como variáveis do projeto do engajamento.
- Aprovador de cada onda e do rollback, janelas e congelamento de escrita no Bitbucket Cloud durante a janela.
- Validação funcional dos repositórios críticos de cada onda e responsáveis pelos itens de tratamento manual.
Detalhamento no documento de pré-requisitos PR-MIG-04, enviado após a escolha do serviço.
11. Duração
Prazo definido na proposta, a partir do Levantamento da Plataforma.
A duração depende do número de repositórios e de pull requests, do número de ondas, das janelas de mudança e da prontidão dos pré-requisitos. As referências consultadas não trazem estimativa oficial de duração para origem Bitbucket Cloud. No pipeline, o job de migração de cada onda tem limite padrão de 8 horas. Toda estimativa de prazo depende do volume real, dos limites de API do Bitbucket Cloud e da infraestrutura do destino, e não é garantia de prazo.
12. Documentos relacionados
- PR-MIG-04 · Pré-requisitos: Migração Bitbucket Cloud para GitLab self-managed
- PS-MIG-01 · Migração GitLab para GitLab self-managed
- PS-MIG-02 · Migração GitHub para GitLab self-managed
- PS-MIG-03 · Migração Azure DevOps para GitLab self-managed