Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.
Observação: a funcionalidade de gerenciamento de pacote do CodeQL, incluindo pacotes do CodeQL, está em versão beta no momento e sujeita a alterações. Durante a versão beta, os pacotes CodeQL estão disponíveis apenas usando pacotes GitHub – o Container registry. Para usar essa funcionalidade beta, instale a versão mais recente do pacote da CodeQL CLI de: https://github.com/github/codeql-action/releases.
Sobre os pacotes do CodeQL e a CodeQL CLI
Com os pacotes do CodeQL e os comandos de gerenciamento de pacotes na CodeQL CLI, você pode publicar as consultas personalizadas e integrá-las à análise de base de código.
Há dois tipos de pacotes do CodeQL: pacotes de consultas e pacotes de biblioteca.
-
Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, ele inclui todas as dependências transitivas e representações pré-compiladas de cada consulta, além das fontes de consulta. Isso garante a execução consistente e eficiente das consultas no pacote.
-
Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas separadamente.
Você pode usar o comando pack
na CodeQL CLI para criar pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Você também pode publicar e baixar pacotes do CodeQL usando o comando pack
. Para obter mais informações, confira "Publicar e usar pacotes do CodeQL".
Para obter mais informações sobre a compatibilidade entre os pacotes de consultas publicados e as diferentes versões do CodeQL, confira "Publicar e usar pacotes do CodeQL".
Como criar um pacote do CodeQL
Você pode criar um pacote do CodeQL executando o seguinte comando na raiz de check-out do projeto:
codeql pack init <scope>/<pack>
É preciso especificar:
-
<scope>
: o nome da organização do GitHub ou da conta de usuário de destino da publicação. -
<pack>
: o nome do pacote que você está criando.
O comando codeql pack init
cria a estrutura de diretório e os arquivos de configuração de um pacote do CodeQL. Por padrão, o comando cria um pacote de consultas. Se você quiser criar um pacote de biblioteca, edite o arquivo qlpack.yml
para declará-lo explicitamente como um pacote de biblioteca, incluindo a propriedade library:true
.
Como modificar um pacote QL herdado existente para criar um pacote do CodeQL
Se você já tiver um arquivo qlpack.yml
, edite-o manualmente para convertê-lo em um pacote do CodeQL.
-
Edite a propriedade
name
para que ela corresponda ao formato<scope>/<name>
, em que<scope>
é o nome da organização do GitHub ou da conta de usuário de destino da publicação. -
No arquivo
qlpack.yml
, inclua uma propriedadeversion
com um identificador semver, bem como um bloco opcionaldependencies
. -
Migre a lista de dependências no
libraryPathDependencies
para o blocodependencies
. Especifique o intervalo de versão de cada dependência. Se o intervalo não for importante ou você não tiver certeza da compatibilidade, especifique"\*"
para indicar que qualquer versão é aceitável e o padrão será a mais recente quandocodeql pack install
for executado.
Para obter mais informações sobre as propriedades, confira "Como personalizar a análise com pacotes CodeQL".
Adicionar e instalar dependências a um pacote do CodeQL
Você pode adicionar dependências em pacotes do CodeQL usando o comando codeql pack add
. Você precisa especificar o escopo, o nome e (opcionalmente) um intervalo de versão compatível.
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
Se você não especificar um intervalo de versão, a versão mais recente será adicionada. Caso contrário, a versão mais recente que atenda ao intervalo solicitado será adicionada.
Esse comando atualiza o arquivo qlpack.yml
com as dependências solicitadas e as baixa no cache de pacote. Observe que esse comando reformatará o arquivo e removerá todos os comentários.
Você também pode editar manualmente o arquivo qlpack.yml
para incluir dependências e instalá-las com o comando:
codeql pack install
Esse comando baixa todas as dependências no cache compartilhado no disco local.
Observações:
-
A execução dos comandos
codeql pack add
ecodeql pack install
vai gerar ou atualizar o arquivocodeql-pack.lock.yml
. O check-in desse arquivo deve ser feito no controle de versão. O arquivocodeql-pack.lock.yml
contém os números de versão precisos usados pelo pacote. Para obter mais informações, confira "Sobre os arquivos codeql-pack.lock.yml". -
Por padrão,
codeql pack install
instalará as dependências do Container registry no GitHub.com. Você pode instalar as dependências de um Container registry do GitHub Enterprise Server criando um arquivoqlconfig.yml
. Para obter mais informações, consulte "Publicar e usar pacotes do CodeQL" na documentação do GitHub Enterprise Server.
Como personalizar um pacote do CodeQL baixado
A maneira recomendada de experimentar as alterações em um pacote é clonar o repositório que contém o código-fonte.
Se nenhum repositório de origem estiver disponível e você precisar basear as modificações em um pacote baixado do Container registry, lembre-se de que esses pacotes não devem ser modificados nem personalizados após o download e o formato pode mudar no futuro sem aviso prévio. Recomendamos executar as seguintes etapas depois de baixar um pacote se você precisar modificar o conteúdo:
-
Altere o nome do pacote em
qlpack.yml
para evitar confusão com os resultados do pacote não modificado. -
Remova todos os arquivos chamados
*.qlx
em qualquer lugar na estrutura de diretório descompactada. Esses arquivos contêm versões pré-compiladas das consultas e, em algumas situações, o CodeQL os usará em preferência à fonte QL que você modificou.