Playbook de Apoio a Migração — middag-io

Passo-a-passo para migração de repos ativos do Bitbucket para o GitHub quando isso fizer sentido operacional. Referências: ADR-001, ADR-004, ADR-006.

Este guia não define a estratégia principal da MIDDAG. A estratégia principal é estruturar a operação. Migração é apenas uma das atividades de apoio.

GitLab não é fonte de migração para GitHub neste processo, pois o histórico GitLab já foi migrado para Bitbucket anos atrás.

Pré-requisitos

• GitHub CLI (gh) autenticado com admin da org middag-io
• Acesso SSH Git tanto ao Bitbucket (middagtec) quanto ao GitHub (middag-io)
• 1Password CLI (op) para verificação de migração de secrets

1. Pré-Migração

1.1 Determinar nome de destino

Siga ADR-001 — Convenção de Nomes de Repositórios para a tabela completa de nomenclatura e casos especiais. Ponto-chave: cada repo recebe um prefixo de categoria (wp-plugin-, docker-, moodle-, etc.).

1.2 Verificar estado do repo no Bitbucket

# Listar branches ativas
git ls-remote --heads [email protected]:middagtec/{old-name}.git

# Verificar variáveis de pipeline (manual — BB Settings → Repository Variables)
# Documentar todas as variáveis para mapeamento de secrets

1.3 Mapear secrets

Veja ADR-005 — Integração 1Password + GitHub para a tabela completa de mapeamento de variáveis Bitbucket → GitHub.

Se secrets específicos do repo existem, crie vault + SA do 1Password conforme G03 — Operações 1Password.

2. Mirror Clone

# 1. Criar repo vazio no GitHub
gh repo create middag-io/{new-name} --private --description "{desc}"

# 2. Mirror clone do Bitbucket (preserva todas branches, tags, histórico)
git clone --mirror [email protected]:middagtec/{old-name}.git /tmp/{old-name}.git

# 3. Push mirror para o GitHub
cd /tmp/{old-name}.git
git push --mirror [email protected]:middag-io/{new-name}.git

# 4. Limpar clone temporário
rm -rf /tmp/{old-name}.git

Verificar mirror

# Verificar se todas as branches chegaram
gh api repos/middag-io/{new-name}/branches --jq '.[].name'

# Verificar tags
gh api repos/middag-io/{new-name}/tags --jq '.[].name'

3. Configurar Repositório

# Definir branch default
gh repo edit middag-io/{new-name} --default-branch main

# Renomear master → main se necessário
gh api repos/middag-io/{new-name}/branches/master/rename -f new_name=main

# Adicionar topics
gh repo edit middag-io/{new-name} --add-topic wordpress,plugin,middag

# Custom properties
gh api repos/middag-io/{new-name}/properties/values \
  -X PATCH \
  -f properties[][property_name]=platform -f properties[][value]=wordpress \
  -f properties[][property_name]=component-type -f properties[][value]=plugin \
  -f properties[][property_name]=deploy-target -f properties[][value]=production

4. Adicionar Workflows CI

Siga G04 — Checklist de Setup de Repo seções 4-5 e ADR-006 — Workflows Reutilizáveis para:

1. Workflow CI (.github/workflows/ci.yml)
2. Workflow de release (.github/workflows/release.yml)
3. Arquivos de config release-please (veja ADR-003 — Estratégia de Release)

Remover pipeline do Bitbucket

git rm bitbucket-pipelines.yml
git commit -m "ci: remove Bitbucket Pipelines (migrated to GitHub Actions)"

5. Atualizar Ambiente de Dev Local

# Atualizar URL do remote
cd /path/to/local/repo
git remote set-url origin [email protected]:middag-io/{new-name}.git
git fetch --all --prune

# Verificar
git remote -v

6. Atualizar Referências Composer

Se o repo usa pacotes do privatesatis, atualizar composer.json:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://privatesatis.middag.com.br"
    }
  ]
}

Atualizar auth.json para dev local:

{
  "http-basic": {
    "privatesatis.middag.com.br": {
      "username": "github-middag-io",
      "password": "<token>"
    }
  }
}

7. Testar CI

# Push para develop — CI deve disparar
git push origin develop

# Abrir PR para main
gh pr create --base main --head develop --title "ci: migrate to GitHub Actions"

# Acompanhar CI
gh run watch

# Após merge para main — verificar se release-please cria Release PR
gh pr list --repo middag-io/{new-name}

8. Arquivar no Bitbucket

Após confirmar GitHub Actions verde em main + develop:

1. Ir ao Bitbucket → middagtec/{old-name} → Settings
2. Definir repositório como somente-leitura (não deletar — preservar histórico)
3. Adicionar descrição: MIGRADO → github.com/middag-io/{new-name}

Checklist Pós-Migração

• [ ] Todas as branches e tags presentes no GitHub
• [ ] Branch default definido como main
• [ ] Branch develop existe
• [ ] Topics e custom properties definidos
• [ ] CI workflow verde em develop
• [ ] CI workflow verde em PR para main
• [ ] Config + manifest release-please criados
• [ ] Anotações de versão no arquivo principal
• [ ] bitbucket-pipelines.yml removido
• [ ] Remotes de dev local atualizados
• [ ] Referências Composer atualizadas (se aplicável)
• [ ] Pipeline de deploy funcional (se aplicável)
• [ ] Repo no Bitbucket definido como somente-leitura

Status da Migração

Wave	Status	Notas
0 — Infra	COMPLETO	.github, CI workflows, config da org
1 — WP	COMPLETO	6 repos migrados, pipelines BB removidos, workflows reutilizáveis + release-please
2 — Libs	Pendente	Renomear + polimento de topics/properties
3 — Apps	Pendente
4 — Moodle core	Pendente	CI complexo (moodle-plugin-ci)
5 — Moodle sites	Pendente	Migração por site

Troubleshooting

Problema	Causa	Solução
fatal: remote error: access denied	Chave SSH não está no Bitbucket	Adicionar deploy key ou usar chave pessoal
Branches ausentes após mirror	Branches protegidas no lado BB	Verificar permissões de branch no BB
CI falha: workflow not found	Caminho errado para workflow reutilizável	middag-io/.github-private/.github/workflows/{name}.yml@workflows-v1
Erro secrets: inherit	Repo não está sob org middag-io	Transferir repo para org primeiro
Branch master ainda é default	Rename não propagou	gh repo edit --default-branch main
Conflito de push no mirror	Repo GitHub foi criado com README	Recriar repo sem README ou force push