Configuração de integração contínua
Decida o que é executado no push e em cada solicitação de alteração e escreva na sintaxe que a forja do projeto entende. As decisões neste arquivo são independentes da forja: detecte o ecossistema, decida o que precisa ser executado, escolha uma matriz, decida o cache. A sintaxe que expressa essas decisões não é, portanto, ela reside em references/github-actions.md para GitHub Actions e references/gitlab.md para GitLab CI/CD. Leia o arquivo de referência correspondente antes de escrever qualquer configuração; não escreva a sintaxe de uma forja traduzindo as palavras-chave da outra, porque as duas têm formatos diferentes para gatilhos, matrizes e cache.
Escopo
Este skill é responsável pelo que é executado: quais verificações são executadas, em quais gatilhos, em quais versões, com qual cache. Ele compartilha os arquivos de workflow e pipeline que escreve com outros dois skills, e o limite entre eles é a área de regra, não uma descrição de arquivos.
As regras de CI abaixo (R-CI-*) pertencem a este skill. As regras SEC, postura de segurança dos mesmos arquivos, como SHAs de ações fixadas, permissões mínimas, atualizadores de dependências, proteção de branch e imagens fixadas, pertencem ao oss-harden. As regras REL, publicação de um artefato construído em um registro com publicação confiável, proveniência e um portal de aprovação, pertencem ao oss-publish. Não adicione um bloco permissions:, fixe um SHA, configure proteção de branch ou escreva um job de publicação enquanto trabalha com este skill; observe que o projeto precisa disso e passe o trabalho para o skill proprietário.
Implantação de um site estático construído no próprio Pages da forja também é algo que é executado em um push, então permanece aqui em vez de com o oss-publish, que possui lançamentos de registro. Nenhuma regra exige isso: um projeto publica um site porque possui um, portanto é escrito apenas onde o repositório constrói um site e o usuário solicita a implantação.
Princípios
Verifique tudo antes de adicionar uma etapa, um segredo ou um valor de configuração: leia o repositório real em vez de adivinhar sua forma. Pergunte quando algo é incerto em vez de inventar uma resposta plausível.
Chame a própria automação do projeto em vez de escrever lógica de shell dentro do pipeline. Uma etapa que executa npm test em vez de jest --coverage --ci mantém o pipeline e o laptop de um colaborador executando o mesmo comando, que é o que R-CI-02 verifica. Quando essa automação não existe, pergunte se deve adicioná-la ao projeto ou recorrer a comandos inline.
Apresente escolhas de política em vez de adivinhá-las, mesmo quando o repositório já contém testes, um Dockerfile ou um pipeline. O que é executado em uma solicitação de alteração, o que desencadeia um build de lançamento e como a implantação acontece são decisões que o usuário toma; o código só informa o que é possível, não o que é desejado.
Processo
Etapa 1: Detecte a forja
Procure por um diretório .github/workflows/ ou arquivo .gitlab-ci.yml existente, verifique o git remote para um host github.com ou gitlab, ou pergunte diretamente se nenhum sinal estiver presente. Isso decide qual arquivo de referência governa as Etapas 6 e 7. Se o usuário declarar a forja explicitamente, confie nisso em vez de qualquer sinal encontrado no repositório.
Etapa 2: Analise o repositório
Identifique a linguagem e o runtime a partir dos arquivos de origem e do manifesto do pacote, e observe a faixa de versão que o projeto afirma suportar; a matriz na Etapa 4 deve cobrir tudo isso, incluindo a versão mais antiga e a mais nova suportada, conforme R-CI-03.
Encontre todos os comandos aplicáveis de lint, teste, typecheck e build que o projeto já define, sejam scripts do gerenciador de pacotes, um Makefile, um Rakefile ou uma ferramenta como tox ou just, e leia-os com atenção suficiente para conhecer seus argumentos e efeitos colaterais. Não invente uma classe de verificação ausente: um repositório de documentação pode não ter build, e um script pequeno pode não ter linter. Se o repositório tiver um guia CONTRIBUTING, seus comandos e a automação do projeto devem concordar; resolva qualquer conflito antes de copiar qualquer um deles para a CI.
Leia qualquer configuração de CI existente antes de alterá-la, para saber se deve estendê-la ou substituí-la.
Identifique todos os lockfiles que o projeto commita, como package-lock.json, Gemfile.lock, poetry.lock ou Cargo.lock, e qual cache de download do gerenciador de pacotes cada comando de instalação pode reutilizar com segurança. Não assuma que um diretório de dependências instaladas é um cache.
Encontre .env.example e pesquise no código-fonte por variáveis de ambiente necessárias, para que uma etapa que precise de um segredo seja identificada antes da geração, em vez de após uma execução com falha.
Etapa 3: Apresente as descobertas e pergunte
Resuma o que a Etapa 2 encontrou e, em seguida, pergunte sobre as escolhas que o código por si só não pode responder: o que deve ser executado em um pull ou merge request, o que deve desencadear um build de lançamento e se a CI existente deve ser estendida ou substituída. Pergunte apenas o que se aplica a este projeto; um projeto sem Dockerfile não recebe pergunta sobre um registro.
Onde a Etapa 2 encontrou um build que produz um site estático, pergunte se ele também deve ser implantado e para onde. Um site pode ser construído como uma verificação e nunca publicado, portanto, trate um build estático como uma pergunta e não como consentimento para implantá-lo.
Etapa 4: Escolha a matriz
Construa a matriz de versões a partir das linhas de lançamento suportadas identificadas na Etapa 2, não de uma única versão fixada. Inclua toda linha de lançamento major ou minor mantida que o projeto afirma suportar. Um projeto sem faixa de suporte declarada recebe um pipeline de versão única em vez de uma matriz inventada; não fabrique alegações de suporte que o manifesto não faz. Se uma faixa for contínua e incluir linhas de lançamento que o projeto não pretende suportar, corrija a faixa declarada em vez de testar silenciosamente um subconjunto.
Etapa 5: Decida o cache
Armazene em cache apenas dados de download do gerenciador de pacotes ou outro diretório que a documentação oficial da ferramenta diga ser seguro reutilizar. Prefira a ação de configuração de runtime oficial da forja quando ela suportar o gerenciador de pacotes detectado e fizer o hash do lockfile. Caso contrário, chaveie um cache explícito no lockfile mais cada limite de compatibilidade que altere seu conteúdo, como sistema operacional, arquitetura, runtime e gerenciador de pacotes. Uma chave de fallback é opcional e não deve cruzar um desses limites. Um projeto sem lockfile ou sem cache de download reutilizável não recebe etapa de cache.
Etapa 6: Escreva a configuração
Abra o arquivo de referência para a forja escolhida na Etapa 1 e siga sua sintaxe exatamente. Ambos os arquivos de referência cobrem gatilho em push para o branch padrão e em cada solicitação de alteração (R-CI-01), um timeout em cada job com cancelamento de execuções substituídas no mesmo branch (R-CI-05) e as decisões de cache da Etapa 5 (R-CI-04). Ambos também trazem uma seção de implantação de Pages, usada apenas quando a Etapa 3 estabeleceu que o projeto deseja uma. Nenhum arquivo de referência cobre permissões, fixação de SHA ou publicação; isso fica fora do arquivo que você escreve aqui.
Etapa 7: Valide antes de apresentar
Confirme que a configuração é sintaticamente válida com o validador próprio da forja, quando um estiver disponível, e confirme que todo comando que ela chama existe e é executado localmente na mesma ordem. Para GitLab, use CI Lint com a configuração incluída expandida. Para GitHub, inspecione o workflow no editor de Actions ou envie-o em um branch quando o usuário tiver autorizado essa alteração externa; um analisador YAML genérico não pode validar expressões do GitHub ou semântica de workflow. Liste quaisquer segredos que o pipeline precise, com o comando para adicionar cada um, sem executar esse comando. Confirme que a matriz corresponde a cada linha de lançamento suportada e que cada job tem um timeout e participa do cancelamento de execuções substituídas quando seguro.
Etapa 8: Apresente o resultado
Mostre o arquivo gerado, um breve resumo do que foi detectado e decidido, a lista de segredos a configurar e qualquer coisa que reste para o usuário definir no nível do repositório ou projeto, como proteção de branch ou aprovadores de ambiente, nomeando o skill que o possui em vez de tentar fazê-lo aqui.
Regras que este skill possui
R-CI-01: CI é executada em cada push para o branch padrão e em cada solicitação de alteração
R-CI-02: CI executa os mesmos comandos de lint, teste e build que o guia de contribuição fornece aos humanos
R-CI-03: A matriz de teste cobre toda versão de runtime que o projeto afirma suportar
R-CI-04: Caches de dependência são chaveados no lockfile
R-CI-05: Cada job tem um timeout, e execuções substituídas para o mesmo branch são canceladas