Sobre os workspaces do CodeQL
Observação: este artigo descreve os recursos disponíveis na versão da ação do CodeQL e o pacote da CodeQL CLI associado incluído na versão inicial desta versão do GitHub Enterprise Server. Se sua empresa usa uma versão mais recente da ação CodeQL, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes. Para obter informações sobre como usar a versão mais recente, consulte "Como configurar a verificação de código do seu dispositivo".
Você pode usar um workspace do CodeQL para agrupar vários pacotes do CodeQL. Um caso de uso típico de um workspace do CodeQL é desenvolver um conjunto de biblioteca e pacotes de consultas do CodeQL que sejam mutuamente dependentes. Para obter mais informações sobre os pacotes CodeQL, confira "Como personalizar a análise com pacotes CodeQL".
O principal benefício de um workspace do CodeQL é que ele facilita o desenvolvimento e a manutenção de vários pacotes do CodeQL. Quando você usa um workspace do CodeQL, todos os pacotes do CodeQL no workspace ficam disponíveis como dependências de origem uns dos outros quando você executa um comando do CodeQL que resolve consultas. Isso facilita o desenvolvimento, a manutenção e a publicação de vários pacotes do CodeQL relacionados.
Na maioria dos casos, você deve armazenar o workspace do CodeQL e os pacotes do CodeQL que ele contém em um repositório Git. Isso facilita o compartilhamento do ambiente de desenvolvimento do CodeQL.
O arquivo codeql-workspace.yml
Um workspace do CodeQL é definido por um arquivo YAML codeql-workspace.yml
. Esse arquivo contém um bloco provide
e, opcionalmente os blocos ignore
e registries
.
-
O bloco
provide
contém uma lista de padrões glob que definem os pacotes do CodeQL que estão disponíveis no workspace. -
O bloco
ignore
contém uma lista de padrões glob que definem os pacotes do CodeQL que não estão disponíveis no workspace. -
O bloco
registries
contém uma lista de URLs GHES e padrões de pacote que controlam qual registro de contêiner é usado para publicar pacotes do CodeQL. Para obter mais informações, confira "Publicar e usar pacotes do CodeQL".
Cada entrada na seção provide
ou ignore
precisa ser mapeada para o local de um arquivo qlpack.yml
. Todos os padrões glob são definidos em relação ao diretório que contém o arquivo de workspace. Para ver a lista de padrões aceitos nesse arquivo, consulte "@actions/glob".
Por exemplo, o arquivo a seguir codeql-workspace.yml
define um workspace que contém todos os pacotes do CodeQL encontrados recursivamente no diretório codeql-packs
, exceto os pacotes no diretório experimental
. O bloco registries
especifica que os pacotes codeql/\*
devem ser baixados de https://ghcr.io/v2/
, que é o registro de contêiner padrão do GitHub. Todos os outros pacotes devem ser baixados e publicados no registro em GHE_HOSTNAME
.
provide:
- "*/codeql-packs/**/qlpack.yml"
ignore:
- "*/codeql-packs/**/experimental/**/qlpack.yml"
registries:
- packages: 'codeql/*'
url: https://ghcr.io/v2/
- packages: '*'
url: https://containers.GHE_HOSTNAME/v2/
Para verificar se o arquivo codeql-workspace.yml
inclui os pacotes do CodeQL esperados, execute o comando codeql pack ls
no mesmo diretório que o workspace. O resultado do comando é uma lista de todos os pacotes do CodeQL no workspace.
Dependências de fonte
As dependências de fonte são pacotes do CodeQL resolvidos do sistema de arquivos local fora do cache de pacotes do CodeQL. Essas dependências podem estar no mesmo workspace do CodeQL ou especificadas como uma opção de caminho usando o argumento --additional-packs
. Quando você compila e executa consultas localmente, as dependências de origem substituem as dependências encontradas no cache de pacotes do CodeQL, bem como as restrições de versão definidas no qlpack.yml
. Todas as referências a pacotes do CodeQL no mesmo workspace são resolvidas como dependências de origem.
Isso é útil principalmente nas seguintes situação:
-
Uma das dependências do pacote de consultas que você está executando ainda não foi publicada. A resolução da origem é a única maneira de referenciar esse pacote.
-
Você está fazendo alterações em vários pacotes ao mesmo tempo e deseja testá-los em conjunto. A resolução da origem garante que você esteja usando a versão do pacote com as alterações contidas.
Workspaces e resolução de consultas do CodeQL
Todos os pacotes de CodeQL em um workspace estão disponíveis como dependências de origem uns dos outros quando você executa qualquer comando do CodeQL que resolva consultas ou pacotes. Por exemplo, quando você executa codeql pack install
em um diretório de pacote em um workspace, qualquer dependência que seja encontrada no workspace será usada em vez de baixar essa dependência no cache do pacote e adicioná-la ao arquivo codeql-pack.lock.yml
. Para obter mais informações, confira "Como criar e trabalhar com pacotes do CodeQL".
Da mesma forma, quando você publicar um pacote de consultas do CodeQL no registro de contêiner do GitHub usando o comando codeql pack publish
, sempre usará as dependências do workspace em vez de usar as dependências encontradas no cache de pacote local.
Isso garante que todas as alterações locais feitas em uma biblioteca de consultas em uma dependência sejam refletidas automaticamente em todos os pacotes de consultas que você publicar desse workspace.
Exemplo
Considere o seguinte arquivo codeql-workspace.yml
:
provide:
- "**/qlpack.yml"
E o seguinte arquivo qlpack.yml
de pacote de biblioteca do CodeQL no workspace:
name: my-company/my-library
library: true
version: 1.0.0
E o seguinte arquivo de pacote qlpack.yml
de consultas do CodeQL no workspace:
name: my-company/my-queries
version: 1.0.0
dependencies:
my-company/my-library: "*"
codeql/cpp-all: ~0.2.0
Observe que o bloco dependencies
do pacote de consultas do CodeQL, my-company/my-queries
, especifica "*"
como a versão do pacote de biblioteca. Como o pacote de biblioteca já está definido como uma dependência de fonte no codeql-workspace.yml
, o conteúdo do pacote de biblioteca sempre é resolvido dentro do workspace. Qualquer restrição de versão definida será ignorada nesse caso. Recomendamos que você use "*"
nas dependências de origem para deixar claro que a versão é herdada do workspace.
Quando você executa codeql pack install
do diretório do pacote de consultas, uma versão apropriada do codeql/cpp-all
é baixada para o cache de pacote local. Além disso, um arquivo codeql-pack.lock.yml
é criado contendo a versão resolvida do codeql/cpp-all
. O arquivo de bloqueio não conterá uma entrada para my-company/my-library
, pois é resolvido por meio das dependências de origem. O arquivo codeql-pack.lock.yml
terá esta aparência:
dependencies:
codeql/cpp-all:
version: 0.2.2
Quando você executa codeql pack publish
do diretório do pacote de consultas, a dependência codeql/cpp-all
do cache de pacotes e o my-company/my-library
do workspace são agrupados com my-company/my-queries
e publicados no registro de contêiner do GitHub.
Usando ${workspace}
como um intervalo de versão em arquivos qlpack.yml
Os pacotes do CodeQL em um espaço de trabalho podem usar os espaços reservados especiais de intervalo de versão ${workspace}
, ~${workspace}
e ^${workspace}
. Esses espaços reservados indicam que esse pacote depende da versão do pacote especificado que está atualmente no espaço de trabalho. Esse espaço reservado geralmente é usado para dependências dentro de pacotes de biblioteca para garantir que, quando forem publicados, as dependências em seu arquivo qlpack.yml
reflitam o estado do espaço de trabalho quando foram publicadas.
Exemplo
Considere os dois pacotes de bibliotecas a seguir no mesmo espaço de trabalho:
name: my-company/my-library
library: true
version: 1.2.3
dependencies:
my-company/my-library2: ${workspace}
name: my-company/my-library2
library: true
version: 4.5.6
Quando my-company/my-library
for publicada no registro de contêiner GitHub, a versão da dependência my-company/my-library2
no arquivo qlpack.yml
publicado será escrita como 4.5.6
.
Da mesma forma, se a dependência for my-company/my-library2: ^${workspace}
no pacote de origem e, em seguida, o pacote for publicado, a versão da dependência my-company/my-library2
no arquivo qlpack.yml
publicado será escrita como ^4.5.6
, indicando que as versões >= 4.5.6
e < 5.0.0
são todas compatíveis com esse pacote de biblioteca.
Se a dependência for my-company/my-library2: ~${workspace}
no pacote de origem e, em seguida, o pacote for publicado, a versão da dependência my-company/my-library2
no arquivo qlpack.yml
publicado será escrita como ~4.5.6
, indicando que as versões >= 4.5.6
e < 4.6.0
são todas compatíveis com esse pacote de biblioteca.