Sobre os workspaces do CodeQL

Sobre os workspaces do CodeQL

Um workspace CodeQL normalmente é usado para desenvolver um conjunto de pacotes de biblioteca e consulta que dependem uns dos outros. 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. Para obter mais informações sobre os pacotes CodeQL, confira 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 workspace CodeQL , 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, em vez do cache de pacotes CodeQL.

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.

Workspaces e resolução de consultas do CodeQL

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 workspace 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. Confira Como criar e trabalhar com pacotes do CodeQL.

Example

Um workspace CodeQL é definido por um arquivo YAML chamado codeql-workspace.yml. 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. 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 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.

Exemplo de um codeql-workspace.yml arquivo

Um workspace CodeQL é 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 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. 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, 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 http://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: http://ghcr.io/v2/

 - packages: '*'
   url: http://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

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.

Example

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.