GitHub Flow & Release Branches

Um guia para GitHub Flow adaptado para mobile - integração contínua em main, branches de release para trens de loja e branches de hotfix paralelos aos canais OTA para que o JavaScript de produção e os binários da loja ao vivo permaneçam alinhados.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

GitHub Flow (mobile adaptation)
  1. Branch from main     → feat/SHIP-220-dark-mode
  2. Open PR              → CI + device evidence required
  3. Merge to main        → squash preferred
  4. Deploy               → OTA to preview channel OR tag for store build

# Hotfix for live store version 2.4.x (parallel to 2.5 RC on release/2.5.0)
git fetch --tags
git checkout -b hotfix/2.4.2 v2.4.1
git cherry-pick <fix-sha>
git tag -a v2.4.2 -m "Hotfix: crash on cold start [SHIP-991]"
git push origin hotfix/2.4.2 v2.4.2

# JS-only hotfix on same runtimeVersion - OTA from hotfix branch
git checkout hotfix/2.4.2
eas update --branch production --channel production --environment production \
  --message "hotfix: cold start crash [SHIP-991]"

Parallel lanes example
  main              ← integration
  release/2.5.0     ← RC in TestFlight review
  hotfix/2.4.2      ← production store 2.4.x users
  (OTA production channel ← hotfix/2.4.2 commits only)

Quando usar isto:

• Usuários em duas versões de loja simultaneamente (atraso na implantação escalonada).
• O canal de produção OTA não deve receber commits destinados à próxima release da loja.
• A equipe cresce além de "marcar tudo a partir de main", mas não quer o develop do GitFlow.
• Hotfix necessário enquanto release/2.5.0 está congelado na Revisão de App.

Quando evitar:

• Versão única no mercado, OTA desativado - um trunk + tags mais simples pode ser suficiente.
• Hotfix requer um novo módulo nativo - deve ser um build de loja, não uma lane apenas OTA.

Exemplo de Trabalho

Cenário: v2.4.1 está ao vivo na produção (rollout de 50% no Play). release/2.5.0 aguarda na Revisão de App. Um crash na inicialização a frio afeta apenas usuários 2.4.x.

Passo 1 - Mapear branches Git para canais EAS

<!-- docs/branch-channel-map.md -->
| Git branch       | Store version | EAS Update branch | EAS channel  |
|------------------|---------------|-------------------|--------------|
| main             | (next)        | preview           | preview      |
| release/2.5.0    | 2.5.0 RC      | staging           | staging      |
| hotfix/2.4.2     | 2.4.2 live    | production        | production   |

eas channel:view production
# Confirm channel points at production branch - not main

Veja Canais e Branches de Release para a semântica do canal.

Passo 2 - Registrar a correção em main primeiro (verdade da integração)

git checkout main && git pull --ff-only
git checkout -b fix/SHIP-991-cold-start
# ... fix ...
git commit -m "fix(app): guard null session on cold start [SHIP-991]"
git push -u origin fix/SHIP-991-cold-start
# PR → squash merge to main

Passo 3 - Abrir branch hotfix a partir da tag ao vivo

git fetch --tags
git checkout -b hotfix/2.4.2 v2.4.1
git cherry-pick <squashed-sha-from-main>
npm run typecheck && npm run test -- --ci
git push -u origin hotfix/2.4.2

• Branch a partir da tag v2.4.1, não de main - garante a mesma runtimeVersion e código nativo
• Cherry-pick de um commit - não git merge main

Passo 4 - Enviar para loja para hotfix nativo (se necessário)

# Bump app version on hotfix branch only
# app.json → version 2.4.2, ios.buildNumber++, android.versionCode++
 
git commit -am "chore(release): bump to 2.4.2 [SHIP-991]"
git tag -a v2.4.2 -m "Hotfix 2.4.2 - build_id xyz789"
git push origin hotfix/2.4.2 v2.4.2

A tag aciona o fluxo de release EAS - perfil acelerado, mesmo build_id testado em QA.

Passo 5 - Lane paralela OTA (caminho apenas JS)

Se a correção for apenas JavaScript e runtimeVersion corresponder a v2.4.1:

git checkout hotfix/2.4.2
eas update --branch production --channel production --environment production \
  --message "hotfix: cold start [SHIP-991]"

# Verify production channel head matches hotfix tip
git rev-parse hotfix/2.4.2
eas update:list --branch production --limit 1

Passo 6 - Backport para main e release/2.5.0

# main already has fix from step 2
git checkout release/2.5.0 && git pull --ff-only
git cherry-pick <same-sha>
git push origin release/2.5.0

Usuários 2.5.0 recebem a correção quando o binário da loja é enviado - não do canal OTA de produção.

GitHub Flow vs Release Branch - Tabela de Decisão

# List branches still receiving OTA
git branch -r | grep -E 'hotfix|release'
eas channel:list

Template de Proteção de Branch

# Document in CONTRIBUTING.md - enforce in GitHub Settings
main:
  required_checks: [quality, pr-template]
  required_reviews: 1
  allow_force_push: false
 
release/*:
  required_checks: [quality, maestro-smoke]
  required_reviews: 2
  restrict_push: [release-managers]
 
hotfix/*:
  required_checks: [quality]
  required_reviews: 2  # expedited but not solo

Armadilhas

• OTA de main enquanto 2.4 e 2.5 diferem em código nativo - o binário 2.5 pode carregar JS incompatível. Correção: Publicar OTA de produção apenas de hotfix/* vinculado à runtimeVersion ao vivo.
• Branch hotfix de release/2.5.0 para usuários 2.4 - Linha de base nativa errada. Correção: git checkout -b hotfix/2.4.2 v2.4.1.
• Esquecer o cherry-pick para release/2.5.0 - A correção é enviada apenas para usuários antigos; 2.5 regride. Correção: Checklist de backport no template de PR.
• Excluir branch hotfix antes de repontuar o canal - Canal de produção órfão. Correção: eas channel:edit apenas após a documentação da nova lane de tag.
• Hotfixes paralelos para a mesma versão - Segundo branch a partir da tag errada. Correção: Tags sequenciais v2.4.2, v2.4.3; um hotfix aberto por vez por major.minor.

Alternativas

FAQs

Relacionados

• Noções Básicas de Git para Equipes Mobile - janelas de congelamento e regras de cherry-pick
• Rebase Interativo & Worktrees - limpar histórico antes do cherry-pick de hotfix
• Integração com GitHub Actions - verificações de PR em PRs de hotfix
• Canais e Branches de Release - mapeamento canal ↔ branch
• Runbook de Rollback - reverter OTA ruim no canal de produção
• Promoção Automatizada de Loja - submissão com limite de tag
• Melhores Práticas de Git & GitHub - resumo de 25 itens

Versões de Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).