Sobre os workspaces do CodeQL

Sobre os workspaces do CodeQL

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 saber mais 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 saber mais, 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 uma lista de padrões aceitos nesse arquivo, confira @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 saber mais, 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.