GitHub bloqueia merge por licença: como configurar

Resposta rápida

Para bloquear um pull request que adiciona uma dependência com licença fora da política, habilite o dependency graph, crie a política de licenças no enterprise e aplique um branch ruleset com Require license compliance results before merging. Comece com o ruleset em Evaluate para observar anotações sem impedir o merge; depois mova somente os repositórios validados para Active.

O recurso entrou em disponibilidade geral em 16 de outubro de 2026. Ele exige GitHub Enterprise Cloud, inclusive com data residency, GitHub Code Security habilitado nos repositórios protegidos e permissão para administrar políticas e rulesets. Não é uma função geral de qualquer plano nem substitui análise jurídica da licença.

O que o GitHub verifica no pull request

Quando um pull request altera manifestos de pacotes, o GitHub compara as dependências entre a branch base e a branch do pull request. As licenças detectadas para dependências diretas e transitivas presentes no dependency graph são avaliadas contra a política efetiva do repositório.

Uma violação aparece como anotação no pull request. Em modo Active, ela impede o merge até a equipe remover ou substituir a dependência, permitir a licença na política ou aprovar uma exceção. Em Evaluate, o resultado é exibido para análise, mas o ruleset por si só não bloqueia o merge. Uma regra separada que exija resolver comentários ainda pode afetar anotações, portanto revise a proteção da branch durante o piloto.

Confirme os requisitos antes de procurar a opção

A configuração fica no nível do enterprise porque a política forma uma base central. Os repositórios-alvo precisam pertencer a organizações desse enterprise, ter GitHub Code Security habilitado e manter o dependency graph ativo. A pessoa que cria a política também precisa de acesso para administrar a política empresarial e os rulesets usados no rollout.

Se sua organização usa GitHub Enterprise Server, GitHub Team ou um repositório sem a licença necessária, o procedimento desta página não se aplica. O dependency-review-action continua sendo uma alternativa distinta para revisar dependências em repositórios públicos e em repositórios privados elegíveis, mas ele não transforma esses ambientes na política empresarial anunciada agora.

• Confirme que a organização pertence a uma conta GitHub Enterprise Cloud.
• Verifique se GitHub Code Security está habilitado nos repositórios do piloto.
• Ative o dependency graph e confirme que ele identifica os ecossistemas usados pelo projeto.
• Garanta que o responsável consegue administrar políticas do enterprise e rulesets.
• Defina com a área jurídica quais expressões SPDX podem entrar na política.

Crie a política sem adivinhar o risco jurídico

No enterprise, abra Policies, License compliance e Default policy. A interface permite escolher licenças de uma lista ou importar identificadores e expressões SPDX manualmente, uma por linha. As categorias de risco exibidas pelo GitHub são informativas; a própria documentação alerta que elas não constituem aconselhamento jurídico.

Não copie uma lista de permissões de outro projeto sem conferir o modo de distribuição, o produto e as obrigações da empresa. Uma licença pode ser aceitável para uma ferramenta interna e inadequada para um binário distribuído. Registre a decisão, a justificativa e o responsável por cada regra para que o bloqueio seja explicável.

• Abra o enterprise e acesse Policies, License compliance, Default policy.
• Selecione as licenças aprovadas ou importe expressões SPDX já revisadas.
• Salve uma política inicial pequena e documente quem a aprovou.
• Evite liberar uma família ampla apenas para remover o primeiro bloqueio.

Defina quem pode aprovar exceções

O GitHub criou a função Enterprise Open-Source License Manager. Atribua-a a pessoas ou equipes que possam revisar pedidos e modificar a política. Esses responsáveis recebem notificações de solicitações pendentes e encontram a fila nas visões de segurança do enterprise.

Uma exceção pode valer para um pacote, uma licença ou um padrão de pacotes e pode ter escopo de repositório ou de enterprise. Prefira o menor escopo que resolve o caso. Uma exceção global criada para liberar um único componente pode enfraquecer a política de todos os repositórios sem que as equipes percebam.

• Abra People, Enterprise roles e Role assignments.
• Atribua Enterprise Open-Source License Manager à equipe revisora.
• Defina prazo e evidência mínima para pedidos de exceção.
• Audite exceções amplas e remova as que perderam a justificativa.

Faça rollout com Evaluate antes de Active

Para um rollout gradual, crie uma propriedade personalizada de repositório, por exemplo open_source_license_compliance, com os valores inactive, evaluate e active. Depois crie dois branch rulesets: um em Evaluate apontando para os repositórios marcados como evaluate e outro em Active para os marcados como active.

Nos dois rulesets, habilite Require license compliance results before merging. O primeiro produz dados e anotações sem impor o bloqueio do próprio ruleset; o segundo aplica a barreira. Esse desenho permite medir falsos positivos, licenças ausentes, manifestos não detectados e tempo de resposta da equipe revisora antes de proteger projetos críticos.

• Crie a propriedade open_source_license_compliance com inactive, evaluate e active.
• Comece com inactive como valor padrão e selecione poucos repositórios representativos.
• Crie um branch ruleset em Evaluate direcionado ao valor evaluate.
• Crie outro branch ruleset em Active direcionado ao valor active.
• Ative Require license compliance results before merging nos dois.
• Promova um repositório para active somente após revisar os resultados do piloto.

Como resolver um merge bloqueado

Abra a anotação e identifique pacote, versão e expressão de licença detectada. A correção preferível é usar uma dependência compatível. Se o pacote é necessário, a pessoa desenvolvedora pode solicitar o encerramento do alerta com contexto; um License Manager decide se nega ou aprova uma exceção no escopo adequado.

Não altere a política central apenas porque um build urgente parou. Confirme a licença no pacote e na origem oficial, consulte a equipe jurídica e verifique se o uso real é compatível. Depois da aprovação, o alerta é fechado e o pull request é liberado somente se nenhum outro requisito de merge continuar falhando.

• Confirme que o alerta corresponde à dependência realmente adicionada ou alterada.
• Tente substituir ou remover o pacote antes de pedir uma exceção.
• Documente finalidade, versão, origem e motivo da necessidade.
• Aprove no escopo de repositório quando não houver justificativa para o enterprise inteiro.
• Reexecute os checks e confira as outras regras aplicáveis à branch.

API, agentes e trilha de auditoria

A disponibilidade geral acrescentou endpoints para baixar, atualizar e substituir a política empresarial e para verificar se pacotes atendem à política. O GitHub destaca que essa consulta permite que agentes de código evitem recomendar ou incorporar pacotes já incompatíveis com as regras da organização.

Mudanças de política emitem eventos de audit log com prefixo license_compliance_policy. Use a API para backup, validação e automação controlada, não para conceder exceções silenciosas. Um agente deve consultar a política antes de sugerir a dependência e ainda produzir uma mudança revisável; não dê a ele permissão ampla para relaxar a política que o restringe.

Por que a verificação não apareceu

Comece pelo escopo: confirme enterprise, organização, repositório, licença do Code Security, dependency graph e branch atingida pelo ruleset. Depois verifique se o pull request realmente altera um manifesto reconhecido e se o ruleset está em Evaluate ou Active. Um ruleset Disabled não executa a avaliação.

Se a anotação existe mas o merge continua disponível, provavelmente o repositório ainda está em Evaluate. Se o merge está bloqueado sem uma violação aparente, abra todos os checks e regras de branch, porque rulesets e branch protection são combinados e a versão mais restritiva aplicável prevalece. Consulte o GitHub Status antes de desfazer a proteção por causa de uma falha simultânea em Pull Requests ou API.

• Confirme o valor da propriedade personalizada e o alvo do ruleset.
• Verifique Enforcement status: Disabled, Evaluate ou Active.
• Abra Settings, Security, License policy para revisar a política efetiva do repositório.
• Confirme que o dependency graph detecta as dependências diretas e transitivas esperadas.
• Revise todos os checks e a branch protection antes de concluir que a licença é o único bloqueio.

Limitações e próxima ação útil

Este guia foi verificado em 17 de outubro de 2026. O recurso depende dos dados de dependência e licença que o GitHub consegue detectar; um resultado aprovado não prova que todo código, arquivo copiado ou obrigação jurídica do projeto foi inventariado. A política reduz risco operacional, mas não substitui SBOM revisado, inventário de componentes, análise jurídica nem obrigações de atribuição e distribuição.

Comece com três repositórios que representem ecossistemas e modelos de distribuição diferentes. Mantenha-os em Evaluate, abra pull requests de teste com uma licença permitida, uma não permitida e uma ausente, e confira anotações, exceções e audit log. Só depois mova o primeiro repositório para active e acompanhe tempo de resolução e causas de bloqueio.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• Open source license compliance generally availableGitHub Changelog
• About open source license complianceGitHub Docs
• Configuring open source license policiesGitHub Docs
• About rulesetsGitHub Docs
• Dependency review actionGitHub
• GitHub StatusGitHub