# Sobre os workspaces do CodeQL

CodeQL espaços de trabalho permitem que você desenvolva e mantenha vários pacotes CodeQL relacionados, resolvendo dependências entre eles diretamente da origem.

## 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](/pt/enterprise-cloud@latest/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).

## 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 espaço de trabalho CodeQL , todos os pacotes incluídos no espaço de trabalho 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 espaço de trabalho, 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 espaço de trabalho são agrupadas usando seu conteúdo de origem local em vez de versões do cache de pacotes. Por exemplo, executar `codeql pack install` em um diretório de pacote dentro de um espaço de trabalho utiliza as dependências encontradas no espaço de trabalho 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](/pt/enterprise-cloud@latest/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies).

Example Um workspace CodeQL é definido por um arquivo YAML chamado `codeql-workspace.yml`.

```yaml
provide:
  - "**/qlpack.yml"
```

Considere o seguinte arquivo `codeql-workspace.yml`:

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

E o seguinte arquivo `qlpack.yml` de pacote de biblioteca do CodeQL no workspace:

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

E o seguinte arquivo de pacote `qlpack.yml` de consultas do CodeQL no workspace: 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.

```yaml
dependencies:
  codeql/cpp-all:
    version: 0.2.2
```

O arquivo `codeql-pack.lock.yml` terá esta aparência:

## 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](/pt/enterprise-cloud@latest/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes). 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](https://github.com/actions/toolkit/tree/main/packages/glob#patterns). 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.

```yaml
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/
```

Todos os outros pacotes devem ser baixados e publicados no registro em `GHE_HOSTNAME`.

## 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

```yaml
name: my-company/my-library
library: true
version: 1.2.3
dependencies:
  my-company/my-library2: ${workspace}
```

```yaml
name: my-company/my-library2
library: true
version: 4.5.6
```

Considere os dois pacotes de bibliotecas a seguir no mesmo espaço de trabalho:

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.