Impedindo que problemas de qualidade de código atinjam seu branch padrão

Introdução

Neste tutorial, você acompanhará uma única pull request pela análise do Code Quality, do primeiro comentário até a mesclagem. O que você aprenderá:

Como ler os Code Quality comentários em uma pull request e distinguir os dois tipos de resultado.
Como usar o rótulo de gravidade de uma descoberta para decidir o que corrigir, o que ignorar e em que ordem.
Como as escolhas que você faz em uma pull request moldam as pontuações do repositório, a lista de pendências e os limites da mesclagem.

Ao final, você terá resolvido cada resultado impeditivo na pull request de exemplo e mesclado com uma verificação Code Quality limpa, e entenderá por que tomou cada decisão.

Este é um tutorial guiado, portanto prioriza a compreensão em vez da velocidade. Para ver as etapas básicas de como confirmar uma correção automática ou descartar um resultado, consulte o guia complementar: Corrigindo descobertas de qualidade de código em uma solicitação de pull.

Antes de começar

Code Quality está habilitado em um repositório para o qual você contribui. Consulte Habilitando o GitHub Code Quality.
O repositório usa um idioma compatível com CodeQL para que resultados e pontuações baseados em regras sejam gerados. Para obter uma lista de idiomas com suporte, consulte Qualidade do Código do GitHub.
Você tem uma pull request aberta para a ramificação padrão com pelo menos um resultado Code Quality para triagem. Se você não tiver uma solicitação de pull pronta, poderá seguir o exemplo abaixo.

Ao longo deste tutorial, usaremos um exemplo em execução: uma solicitação de pull que refatora algum código introduzirá vários problemas de qualidade de código no branch padrão se ele for mesclado como está. Um exame Code Quality foi realizado automaticamente na pull request e relatou diversos resultados como comentários.

Por que o pull request é o melhor lugar para corrigir um problema identificado

Todo problema que você não resolve na etapa do pull request se torna uma tarefa no backlog do repositório, e a dívida técnica geralmente é mais custosa de quitar depois do que corrigi-la agora. Neste momento, enquanto o pull request está aberto, o contexto e a intenção do código ainda estão frescos na sua mente, o que torna cada apontamento, e sua correção automática, mais fácil e rápido de avaliar, aplicar ou descartar com confiança.

Resolver os resultados no estágio de pull request significa que a equipe passa menos tempo fazendo o trabalho de triagem em vez do desenvolvimento de funcionalidades e evita a sobrecarga de pull requests extras apenas para reduzir a lista de pendências.

Etapa 1: Encontre os comentários na sua Code Quality pull request

Quando você abre uma solicitação pull, Code Quality executa dois tipos de análise e posta descobertas como comentários. Abra a guia Arquivos alterados do seu pull request e veja quem deixou cada comentário — o autor informa qual é o tipo de achado.

As descobertas baseadas em regras são postadas pelo github-code-quality[bot]. Code Quality usa CodeQL para verificar suas alterações em relação a um conjunto de regras e cada comentário inclui um autofixo sugerido.
As descobertas de IA são postadas por Copilot. Se sua organização tiver licenças Copilot e os recursos de IA estiverem habilitados para sua empresa, Revisão de código do Copilot identifica problemas de qualidade que a análise baseada em regras pode não detectar. Esses comentários também incluem uma correção automática sugerida.

Em nosso exemplo, examinaremos três comentários provenientes github-code-quality[bot], portanto, são descobertas baseadas em regras. No seu próprio pull request, você poderá ver os dois tipos — observe qual é qual antes de prosseguir, porque os rótulos de severidade (Etapa 2) se aplicam somente aos comentários baseados em regras.

Etapa 2: Ler o rótulo de severidade para decidir o que importa

Cada descoberta baseada em regras de github-code-quality[bot] recebe um rótulo de gravidade — Erro, Aviso ou Observação. Localize o rótulo em um dos comentários e verifique-o nesta tabela.

Severity	Definition
Error	Indica um problema de alta gravidade que provavelmente causará bugs, falhas ou principais riscos de manutenção.
Aviso	Indica um problema de gravidade moderada que pode afetar a qualidade ou a confiabilidade do código, mas não é imediatamente crítico.
Observação	Indica um problema de baixa gravidade, um pequeno aprimoramento ou uma recomendação. Essas descobertas são úteis para a integridade e a manutenção contínuas do código.

A etiqueta está desempenhando duas funções ao mesmo tempo para você:

Ele informa o que corrigir primeiro. A gravidade reflete o impacto esperado de uma regra no código típico. Em nosso exemplo, você começará com o Erro, depois o Aviso e trataria a Observação como um polimento opcional.

          **Ele pode decidir se você pode mesclar.** Um administrador de repositório ou proprietário da organização pode configurar Code Quality como uma porta de mesclagem. Por exemplo, se o limiar para mesclagem for "Aviso e acima", cada resultado de nível **Aviso***e***Erro** deverá ser corrigido ou descartado antes que você possa mesclar (resultados de **Nota** não impediriam a mesclagem). Da mesma forma, um limite mais rigoroso pode exigir que você resolva _todas as_ descobertas antes da mesclagem.

Para ver se há um bloqueio, role até a seção Verificações na parte inferior da pull request. Se suas alterações ficarem abaixo do limiar exigido, você verá um aviso de bloqueio de mesclagem: "A mesclagem está bloqueada: foram detectados problemas de qualidade do código."

Captura de tela do banner de bloqueio de mesclagem na seção Verificações de uma solicitação de pull.

Em nosso exemplo, a porta é definida como "Aviso e acima", logo, a faixa está presente: o Erro e o Aviso estão impedindo a mesclagem e a Observação não está. Isso mostra o que você precisa resolver antes que este pull request possa ser mesclado.

Se a faixa do bloco de mesclagem não especificar um nível de gravidade, você deverá limpar todos os resultados para mesclar a pull request.

Etapa 3: Resolver cada descoberta

Para cada descoberta, decida se ela se aplica ao seu código e, se isso acontecer, como corrigi-lo. Isso leva você a uma das três ações.

Assessment	Ação recomendada	Notes
A descoberta é legítima e a correção sugerida parece correta
Aplicar a sugestão de correção automática	Clicar em Aplicar sugestão não consome AI credits, e as correções automáticas baseadas em regras não exigem licença Copilot.
A descoberta é real, mas você deseja corrigir várias de uma vez ou a correção sugerida precisa ser adaptada
Delegar para Copilot— mencione `@copilot` em um comentário para entregar o trabalho ao agente de nuvem. Copilot reage a 👀, inicia uma nova sessão de agente e faz push das correções necessárias para a ramificação da pull request	Requer uma Copilot licença e consome AI credits.
O resultado não se aplica, por exemplo, trata-se do código de teste, um padrão intencional ou um falso positivo.	Clique em Descartar resultado e forneça um motivo	Você poderá mesclar a pull request, mas o alerta aparecerá no backlog do repositório e em pull requests futuras.

Aplique a prática à própria pull request seguindo a ordem de gravidade.

Em nosso exemplo:

As ocorrências de nível Erro e Aviso são erros reais, e as correções automáticas sugeridas parecem razoáveis, por isso aplicamos as sugestões de correção automática. Os resultados são resolvidos e deixam de ser contabilizados na contagem de bloqueios.
Um resultado no nível Observação sinaliza um padrão secundário em um auxiliar de teste adjacente. É intencional, logo, descartamos com um motivo como "Usado em testes".
Há vários achados adicionais no nível de Nota. Em vez de percorrer cada sugestão de correção automática, uma por uma, comentamos: "@copilot, corrija todos os problemas no nível Observação restantes". Acompanhamos o progresso de Copilot na guia Agentes do repositório e revisamos os commits enviados por ele para a pull request quando estão prontos.

Etapa 4: confirmar se a solicitação de pull está desbloqueada (opcional)

Se você tiver mesmo resultados impeditivos, depois que tiver corrigido ou descartado os resultados relevantes, retorne à seção Verificações na parte inferior da pull request.

Em nosso exemplo, com as ocorrências Erro e Aviso resolvidas, o banner de bloqueio da mesclagem desaparece. A pull request agora está pronta para ser mesclada.

Se a faixa ainda estiver lá, isso significará que um resultado em ou acima de gravidade impeditiva ainda está aberta.

Etapa 5: Solucione os resultados gerados por IA de Copilot

Se sua organização tiver Copilot licenças e os recursos de IA estiverem habilitados para sua empresa, você também verá comentários postados por Copilot. Estas são as descobertas baseadas em IA introduzidas na Etapa 1, e elas vêm de Revisão de código do Copilot em vez de github-code-quality[bot].

Quando os resultados baseados em regras comparam suas alterações com um conjunto fixo de CodeQL regras, Revisão de código do Copilot raciocina sobre a intenção do seu código. Ele identifica problemas de qualidade que não se enquadram em uma regra específica, por isso, é um complemento útil para os comentários baseados nas regras, e não um substituto para eles.

Essas descobertas não carregam um rótulo de severidade de "Erro", "Aviso" ou "Observação". Como a porta de mesclagem que você viu na Etapa 2 conta apenas a gravidade dos resultados com base em regras, os resultados da plataforma IA jamais impedem a pull request por conta própria. Isso não os torna opcionais; resolvê-los dentro do contexto ainda é a melhor forma de manter problemas de qualidade fora da ramificação padrão.

Você resolve uma descoberta com tecnologia de IA com as mesmas três opções que usou na Etapa 3:

Aplique a sugestão de correção automática. Cada comentário inclui uma correção sugerida. Se estiver correto as-is, clique em Confirmar sugestão. A aplicação da correção automática não consome GitHub AI Credits.
Delegar para Copilot— mencione @copilot em um comentário para entregar o trabalho ao agente de nuvem. Copilot interage com 👀, inicia uma nova sessão de agente e envia as correções necessárias no branch do pull request. Essa opção requer uma Copilot licença e consome GitHub AI Credits.
Resolva o comentário. Se ele não se aplicar ao código, clique em Resolver.

Como isso se relaciona com o restante da saúde do código

O pull request que você acabou de aprovar faz parte de um contexto mais amplo:

          **Pontuações.** As pontuações de confiabilidade e capacidade de manutenção do seu repositório são calculadas com base nas ocorrências identificadas no branch padrão. A resolução dos resultados antes da mesclagem é como você evita que essas pontuações se deteriorem. Consulte [AUTOTITLE](/code-security/code-quality/reference/metrics-and-ratings).

Pendências. Qualquer coisa que você não corrija na pull request entra na lista de pendências na ramificação padrão. Reduzir esse backlog exige uma disciplina própria. Consulte Elevando a pontuação de qualidade do código do repositório.
Conformidade. Quando uma classe de resultados não deve alcançar genuinamente a ramificação padrão, o conjunto de regras "Exigir resultados da qualidade de código" ajuda administradores de repositório e proprietários de organização a codificar essa decisão como uma porta de mesclagem. Consulte Resolvendo um bloqueio em sua pull request.

As equipes mais saudáveis combinam todas as três: triagem e remediação deliberadas na etapa de pull request, trabalho periódico na lista de pendências e limites aplicados no limite de mesclagem.

Solução de problemas

Não vejo comentários Code Quality . A verificação talvez ainda esteja em execução, suas alterações podem não afetar um idioma compatível ou você não tem nenhum resultado. Confirme se Code Quality está habilitado e dê tempo para que a verificação (chamada "CodeQL – Qualidade do Código") seja concluída. Consulte Habilitando o GitHub Code Quality.
Eu só vejo comentários de github-code-quality[bot], nunca de Copilot. As descobertas alimentadas por IA exigem Copilot licenças e recursos de IA habilitados para sua empresa. Sem eles, você verá apenas descobertas baseadas em regras.
Não encontro correções automáticas para meus problemas de qualidade de código. A geração de correção automática consome GitHub AI Credits. Sua organização pode ter esgotado seu orçamento mensal de AI credits.
O banner do bloco de merge não desaparece. Pelo menos um resultado em ou acima da gravidade de bloqueio ainda está aberto. Se você não vir um nível de severidade definido no banner de bloqueio de mesclagem, isso significa que seu repositório está usando os limites de qualidade de código mais rigorosos, que exigem que todos os problemas sejam resolvidos antes da mesclagem. Consulte Resolvendo um bloqueio em sua pull request.

Conclusion

Neste tutorial, você percorreu Code Quality comentários sobre uma pull request, usou gravidade para priorizar a correção e resolveu deliberadamente cada problema identificado antes de mesclar a pull request. Ao tratar cada resultado, e a correção automática, como uma decisão pequena contextual, você impediu que a dívida de qualidade do código chegasse à ramificação padrão.

Próximas Etapas

Aplique o mesmo pensamento à sua lista de pendências existente: Elevando a pontuação de qualidade do código do repositório.
Saiba como as descobertas se traduzem em pontuações para que você possa medir o impacto do trabalho: Referência de métricas e pontuações.