colibri-deploy-producao

Files (7)

• SKILL.md
• pipeline-colibri.md · references/
• aguardar-builds.sh · scripts/
• aguardar-execucoes.sh · scripts/
• conferir-deploy.sh · scripts/
• estado-repo.py · scripts/
• jira-resumo.py · scripts/

SKILL.md (first lines)

# Liberação para produção

Esta skill leva para produção os pacotes que uma ou mais tarefas do Jira entregam. O fluxo tem ações difíceis de desfazer: merge no `master` e em `production*`, remoção de branch e envio de pacotes ao S3, que chegam às lojas. O pedido do usuário autoriza essas ações para os pacotes das tarefas. Pare e pergunte ao usuário em cada ponto de decisão marcado com **Pergunte**, porque a resposta depende de regra de negócio ou de risco que o código não mostra.

Antes de começar, leia [references/pipeline-colibri.md](./references/pipeline-colibri.md). Ela explica a versão do pacote, as dependências do manifesto, o mapa de repositórios, o build, o deploy e os problemas conhecidos.

## Ferramentas

- `gh` autenticado na organização `ColibriAgile`.
- `git` no repositório local, quando o pedido parte de um branch de fix ou feature.
- MCP do Atlassian: `getAccessibleAtlassianResources`, `getJiraIssue`, `searchJiraIssuesUsingJql`, `editJiraIssue` e `addOrEditJiraIssueComment`. As operações de versão vêm do `discover`: `getJiraProjectVersions` (com `executeRead`) e `manageJiraProjectVersion` (com `executeDestructive`). Chame o `discover` uma vez antes de usar essas operações.
- Scripts desta skill. Nesta skill, `scripts/` quer dizer `<pasta base da skill>/scripts/`: o harness mostra a pasta base quando carrega a skill. Use caminho absoluto nos comandos. Use uma pasta temporária só como pasta de trabalho, para clones e arquivos de saída.

| Script | Uso |
|---|---|
| `jira-resumo.py <arquivo.json>...` | Resume a tarefa salva pelo `getJiraIssue` (fixVersions, descrição, comentários com tabelas). |
| `estado-repo.py <repo>...` | Mostra, só com leitura, versões, dependências, workflows, execuções do master, PR abertos, releases e hotfixes não portados. |
| `aguardar-builds.sh <T0> <repo>:<wf>:<branch>...` | Acompanha os builds disparados pelo merge. Use com a ferramenta Monitor. |
| `aguardar-execucoes.sh <repo>:<runId>...` | Acompanha execuções pelo id (deploy, reexecução). Use com a ferramenta Monitor. |
| `conferir-deploy.sh <repo>:<runId>...` | Mostra a tag, o `.cmpkg` enviado e a contagem `Enviados/Ignorados`. |
| `publicar-market.py consultar <Nome>:<versão>...` | Mostra, só com leitura, o id do pacote no market-place, se ele está publicado e se tem nota. |
| `publicar-market.py publicar <notas.json> [--simular]` | Publica os pacotes pendentes com as notas, com o token de `COLIBRI_MARKET_TOKEN`, e confere o resultado. |

## Lista de tarefas

Antes do passo 0, crie a lista de tarefas da sessão com estes itens. O número de cada item é o número do passo. Atualize cada item quando ele terminar. Se o passo 0 não acha um branch de origem, marque o item 3 como cancelado. Se o passo 8 tira a publicação no market-place, marque o item 13 como cancelado.

0. Identificar o ponto de partida (branch de origem ou master)
1. Ler as tarefas do Jira e listar os pacotes e as versões
2. Mapear cada pacote ao repositório e ao build
3. Integrar o branch de origem no master e remover o branch
4. Separar os pacotes já liberados dos pacotes a liberar
5. Conferir as dependências do `manifesto.server`
6. Conferir o estado do master (builds e testes)
7. Conferir os branches relacionados e os hotfixes não portados
8. Conferir as versões do Jira e as tarefas pendentes nelas
9. Criar os PR para os branches de produção
10. Fazer o merge dos PR
11. Aguardar os builds e conferir as versões geradas
12. Disparar os deploys na ordem das dependências e aguardar
13. Publicar os pacotes no market-place (opcional)
14. Lançar as versões do Jira
15. Gerar o relatório e comentar em cada tarefa

## Passo 0: Identificar o ponto de partida

O usuário pode pedir a liberação de 2 lugares. O fluxo muda um pouco em cada caso.

- **Modo master:** o pedido vem só com as chaves do Jira, ou o repositório local está no `master`, num `production*` ou fora de um repositório Colibri. O código já está no master. Pule o passo 3.
- **Modo branch:** o repositório local está num branch de fix ou de feature (por exemplo `fix/WIN-3159-troco`, `feature/WIN-3160`). O código desse branch ainda não está no master. O passo 3 integra o branch no master antes do PR para a produção.

1. No diretório de trabalho, rode `git rev-parse --abbrev-ref HEAD` e `gh repo view --json name,owner --jq '.owner.login + "/" + .name'`.
2. Se o branch atual não é `master` nem `production*` e o repositório é da `ColibriAgile`, o branch é candidato ao modo branch. Guarde o nome do branch e o repositório.
3. Se o usuário não deu a chave do Jira, tire a chave do nome do branch. Prefira o prefixo do projeto (`WIN-<número>`); o padrão genérico `[A-Z]+-[0-9]+` também pega textos como `UTF-8`. O passo 1 confirma a chave com o `getJiraIssue`. Se o nome não tem chave ou a chave não existe no Jira, **Pergunte** a chave.
4. Se o usuário deu chaves e o branch tem outra chave, **Pergunte** se o branch atual faz parte da liberação. Se o branch não tem chave e o repositório não gera nenhum pacote das tarefas (passo 2), use o modo master: o branch não tem relação com a liberação.
5. No modo branch, confira o repositório local:
   - `git status --porcelain` vazio. Se há mudanças sem commit, **Pergunte**. Não faça `stash` nem commit por conta própria: as mudanças podem estar fora do que o QA testou.
   - Rode `git fetch origin` e `git ls-remote --exit-code --heads origin <branch>`. Se o branch não existe no remoto (código de saída 2), o branch nunca foi enviado: **Pergunte** se faz `git push -u origin HEAD`.
   - Se o branch existe no remoto, rode `git rev-list --left-right --count origin/<branch>...HEAD`. O número da direita é a quantidade de commits locais sem push: se ele é maior que 0, **Pergunte** se faz o push. O número da esquerda é a quantidade de commits do remoto que o local não tem: faça `git pull --ff-only origin <branch>`.

**Saída:** modo (branch ou master), repositório, branch de origem e chaves.

## Passo 1: Ler as tarefas

1. Obtenha o `cloudId` com `getAccessibleAtlassianResources`.
2. Para cada chave, chame `getJiraIssue` com `view: "full"`. O resultado passa do limite e o harness o salva em arquivo. Rode `python -I scripts/jira-resumo.py <arquivos>`.
3. Monte a lista de pacotes:
   - `fixVersions` dá os pacotes e a versão curta (por exemplo `POS 11.2`).
   - As tabelas dos comentários ("Pacotes para o QA", "Pacotes para baixar") dão a versão completa e o branch do build do QA. Para cada pacote, use a versão do comentário mais recente.
   - Um pacote só em `fixVersions`, sem versão completa, entra com a versão curta. Registre isso.
4. Junte as tarefas. Se 2 tarefas pedem o mesmo pacote com os 3 primeiros números diferentes, **Pergunte** qual versão vale.
5. Separe os itens "fora dos pacotes" (scripts do cloud, Catálogo cloud, configuração manual). Eles vão para o relatório como pendências.
6. Confira se o QA aprovou cada tarefa (status e últimos comentários). Se uma tarefa não tem aprovação, **Pergunte** se ela entra. No modo branch, essa resposta vem antes do merge no master: sem aprovação, o branch não entra no master.

**Saída:** tabela com pacote, versão esperada, branch do build do QA e tarefa de origem. A versão esperada é a versão da fixVersion. Se a tabela do QA tem uma versão completa com os mesmos números iniciais, use os 3 primeiros números dela.

## Passo 2: Mapear os repositórios

1. Use o mapa da referência para achar o repositório de cada pacote. Para um pacote fora do mapa, procure o `nome` do manifesto: `gh search code '"nome": "<Nome>"' --owner ColibriAgile --filename manifesto.server`. Se a busca falhar ou não achar nada, **Pergunte** o repositório ao usuário.
2. Rode `python -I scripts/estado-repo.py <repo1> <repo2> ...` com todos os repositórios. O script leva cerca de 20 segundos por repositório: use timeout de 600000 ms ou `run_in_background`. Guarde a saída: os passos 4 a 8 usam essa saída. No modo branch, o passo 3 roda o script de novo para o repositório de origem.
3. Para cada pacote, anote:
   - o `versao.ini` e o branch de produção que dispara o build (gatilho `push` do workflow);
   - o workflow de build;
   - o deploy: a entrada `tag_prefix` e se o `deploy.yml` repassa o `tag-prefix` para a action.

**Saída:** para cada pacote, repositório, `versao.ini`, branch de produção, workflow de build e forma de deploy.

## Passo 3: Integrar o branch de origem no master

Só no modo branch. O objetivo é colocar no master o código que o QA aprovou, com a versão certa, e deixar o repositório local limpo no master. Os passos seguintes usam só o master.

O merge no master exige só 2 condições: a aprovação do QA (passo 1, item 6) e a versão conferida (3.1). Os passos 5, 7 e 8 vêm depois do merge. Um problema nesses passos (dependência, hotfix, versão do Jira com pendência) para só o PR para a produção. O merge no master fica, porque o código aprovado pelo QA pertence ao master. Diga isso ao usuário em 1 frase antes do merge.

### 3.1 Conferir a versão do branch

Para cada pacote da liberação que o repositório de origem gera, leia o `versao.ini` local que o passo 2 ligou ao pacote. Um repositório com vários builds tem 1 `versao.ini` por pacote (por exemplo, `.build/app/` e `.build/scripts/`). Compare os números da versão esperada (passo 1) com os mesmos números do `versao.ini`. Uma versão curta com 2 números (`POS 11.2`) compara só os 2 primeiros: o `Release` do `versao.ini` fica como está.

- **Iguais:** siga.
- **Jira maior que o branch** (por exemplo, Jira `POS 11.2.1` e `versao.ini` `11.2.0`): ofereça o ajuste. **Pergunte** com as opções "Ajustar o `versao.ini` para `<X.Y.Z>`" e "Não ajustar e tirar este pacote da liberação". Mostre a versão do Jira, a versão do branch e o caminho do `versao.ini`. Com uma versão curta de 2 números maior que o branch (Jira `POS 11.3`, `versao.ini` `11.2.4`), sugira `<X.Y>.0`.
- **Jira menor que o branch:** não ajuste. **Pergunte** se a fixVersion da tarefa está errada ou se o branch tem uma versão nova de propósito.

Se o usuário tira um pacote da liberação, **Pergunte** se o merge do branch no master continua. O branch pode gerar outros pacotes da liberação.

Para fazer o ajuste aprovado:

1. Edite só os valores `MajorVersion`, `MinorVersion` e `Release` da seção `[versaoinfo]`. Use a ferramenta Edit para manter a codificação e o fim de linha do arquivo.
2. Rode `git add -- <caminho do versao.ini>`.
3. Faça o commit no branch de origem: `git commit -m 'chore(versao): <Pacote> <X.Y.Z> (<CHAVE>)'`. Use aspas simples: no PowerShell, aspas duplas expandem `$` e crases.
4. Rode `git push -u origin HEAD`.
5. Registre o ajuste para o relatório. O commit muda só a versão, mas é um commit que o QA não testou.

O ajuste fica no branch, antes do merge, para que o master receba o código e a versão no mesmo merge.

### 3.2 Fazer o merge no master

1. Procure um PR aberto do branch: `gh pr list -R ColibriAgile/<repo> --head <branch> --base master --state open --json number,url`. Se ele existe, use esse PR.
2. Se não existe, crie: `gh pr create -R ColibriAgile/<repo> --base master --head <branch> --title "<CHAVE>: <resumo da tarefa>" --body "<corpo>"`. O corpo cita a tarefa com o link e termina com as linhas de atribuição que a sessão pede.
3. Confira o PR com `gh pr view <n> -R ColibriAgile/<repo> --json mergeable,mergeStateStatus` (repita enquanto o valor for `UNKNOWN`):
   - `CLEAN`: siga.

From ColibriAgile/agents-instructions, MIT.

More from ColibriAgile/agents-instructions