# Workspaces do CodeQL

CodeQL Os workspaces permitem que você desenvolva e mantenha vários pacotes relacionados CodeQL juntos, resolvendo dependências entre eles diretamente da origem.

## 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](/pt/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 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](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies).

### Exemplo

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

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

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

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

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

```yaml
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](/pt/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 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`.

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

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:

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

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.