Workspaces do CodeQL

Sobre CodeQL espaços de trabalho

Um CodeQL workspace normalmente é usado para desenvolver um conjunto de pacotes de biblioteca e consulta que dependem uns dos outros. Quando você usa um CodeQL workspace, todos os CodeQL pacotes no workspace ficam disponíveis como dependências de origem uns para os outros quando você executa um CodeQL comando que resolve consultas. Isso facilita o desenvolvimento, a manutenção e a publicação de vários pacotes relacionados CodeQL . Para obter mais informações sobre CodeQL pacotes, consulte Como personalizar a análise com pacotes CodeQL.

Os workspaces geralmente são armazenados em um único repositório Git para que os pacotes relacionados possam ser desenvolvidos e publicados juntos.

Dependências de fonte

Em um CodeQL workspace, todos os pacotes incluídos no workspace são tratados como dependências de origem uns dos outros. Isso significa que eles são resolvidos diretamente do sistema de arquivos local e não do cache de CodeQL pacotes.

Porque os pacotes de espaço de trabalho são resolvidos a partir da fonte:

• As alterações locais em um pacote são imediatamente visíveis para outros pacotes no workspace.
• As dependências encontradas no workspace substituem versões no cache do pacote.
• Restrições de versão em arquivos qlpack.yml são ignoradas para dependências do espaço de trabalho, pois a versão é determinada pelo conteúdo do espaço de trabalho.

Esse comportamento é particularmente útil ao desenvolver vários pacotes relacionados ao mesmo tempo. Por exemplo:

• Uma dependência ainda não foi publicada e existe apenas localmente.
• Você está fazendo alterações coordenadas em vários pacotes e precisa que elas sejam resolvidas entre si durante o teste.

Fora de um workspace, as dependências são resolvidas do cache do pacote e devem corresponder às restrições de versão definidas em qlpack.yml. Dentro de um workspace, o processo de resolução prioriza o conteúdo de origem local.

CodeQL espaços de trabalho e resolução de consultas

O modelo de dependência do workspace afeta a forma como os pacotes são instalados e publicados.

• Durante a instalação, as dependências encontradas no workspace não são baixadas no cache do pacote e não são gravadas no codeql-pack.lock.yml arquivo.
• Durante a publicação, as dependências fornecidas pelo espaço de trabalho são agrupadas usando seu conteúdo de origem local em vez de versões do cache de pacotes.

Executar codeql pack install em um diretório de pacote dentro de um workspace utiliza as dependências encontradas no workspace em vez de baixá-las no cache do pacote ou gravá-las no arquivo codeql-pack.lock.yml. Consulte Como criar e trabalhar com pacotes do CodeQL.

Exemplo

Um CodeQL workspace é definido por um arquivo YAML chamado codeql-workspace.yml. Considere o seguinte arquivo codeql-workspace.yml:

provide:
  - "**/qlpack.yml"

E o seguinte CodeQL arquivo do pacote de biblioteca qlpack.yml no espaço de trabalho:

name: my-company/my-library
library: true
version: 1.0.0

E o seguinte CodeQL arquivo de pacote de consultas qlpack.yml no espaço de trabalho:

name: my-company/my-queries
version: 1.0.0
dependencies:
  my-company/my-library: "*"
  codeql/cpp-all: ~0.2.0

Observe que o dependencies bloco do CodeQL pacote de consultas especifica my-company/my-queries``"*" 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. Usar "*" para dependências de origem torna explícito 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 a partir do diretório do pacote de consultas, a dependência codeql/cpp-all do cache de pacotes e o my-company/my-library do espaço de trabalho são agrupados com my-company/my-queries e publicados no registro de contêiner GitHub.

Exemplo de um codeql-workspace.yml arquivo

Um CodeQL workspace é definido por um arquivo YAML chamado 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 CodeQL disponíveis no espaço de trabalho.

• O bloco ignore contém uma lista de padrões glob que definem os pacotes CodeQL que não estão disponíveis no espaço de trabalho.

• O bloco registries contém uma lista de URLs do GHES e padrões de pacote que controlam qual registro de contêineres é usado para publicar pacotes CodeQL. Consulte 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, confira @actions/glob.

Por exemplo, o arquivo a seguir codeql-workspace.yml define um workspace que contém todos os CodeQL pacotes recursivamente encontrados no codeql-packs diretório, exceto os pacotes no experimental diretório. 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/

Você pode listar os pacotes incluídos em um workspace executando codeql pack ls no diretório do workspace.

Usando ${workspace} como um intervalo de versão em arquivos qlpack.yml

CodeQL os pacotes de um workspace podem usar os marcadores 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 publicado 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.