À propos des espaces de travail CodeQL

CodeQL workspaces vous permettent de développer et de gérer plusieurs paquets CodeQL associés, en résolvant directement depuis la source les dépendances entre eux.

Qui peut utiliser cette fonctionnalité ?

CodeQL est disponible pour les types de référentiels suivants :

Dans cet article

À propos des espaces de travail CodeQL

Un espace de travail CodeQL est généralement utilisé pour développer un ensemble de packs de bibliothèques et de requêtes qui dépendent les uns des autres. Quand vous utilisez un espace de travail CodeQL, tous les packs CodeQL de l’espace de travail sont disponibles sous forme de dépendances sources les uns pour les autres quand vous exécutez une commande CodeQL qui résout des requêtes. Le développement, la gestion et la publication de plusieurs packs CodeQL associés sont ainsi facilités. Pour plus d’informations sur les packs CodeQL, consultez Personnalisation de l’analyse avec des packs CodeQL.

Les espaces de travail sont généralement stockés dans un référentiel Git unique afin que les packs associés puissent être développés et publiés ensemble.

Dépendances sources

Dans un espace de travail CodeQL , tous les packs inclus dans l’espace de travail sont traités comme des dépendances sources entre eux. Cela signifie qu’ils sont résolus directement à partir du système de fichiers local plutôt qu’à partir du cache de package CodeQL.

Comme les packs de l’espace de travail sont résolus à partir du code source :

  • Les modifications locales dans un pack sont immédiatement visibles par d’autres packs dans l’espace de travail.
  • Les dépendances trouvées dans l’espace de travail remplacent les versions dans le cache du package.
  • Les contraintes de version dans les qlpack.yml fichiers sont ignorées pour les dépendances d’espace de travail, car la version est déterminée par le contenu de l’espace de travail.

Ce comportement est particulièrement utile lors du développement de plusieurs packs associés en même temps. Par exemple:

  • Une dépendance n’a pas encore été publiée et existe uniquement localement.
  • Vous apportez des modifications coordonnées entre plusieurs packs et avez besoin de les résoudre les unes contre les autres lors du test.

En dehors d’un espace de travail, les dépendances sont résolues à partir du cache du package et doivent correspondre aux contraintes de version définies dans qlpack.yml. Dans un espace de travail, la résolution priorise le contenu source local.

Espaces de travail et résolution des requêtes CodeQL

Le modèle de dépendance d’espace de travail affecte la façon dont les packs sont installés et publiés.

  • Pendant l’installation, les dépendances trouvées dans l’espace de travail ne sont pas téléchargées dans le cache du package et ne sont pas écrites dans le codeql-pack.lock.yml fichier.
  • Lors de la publication, les dépendances fournies par l’espace de travail sont regroupées à l’aide de leur contenu source local plutôt que des versions du cache du package.

Par exemple, l’exécution codeql pack install dans un répertoire pack au sein d’un espace de travail utilise toutes les dépendances trouvées dans l’espace de travail au lieu de les télécharger dans le cache du package ou de les enregistrer dans le codeql-pack.lock.yml fichier. Consultez « Création et utilisation de packs CodeQL ».

Example

Un espace de travail CodeQL est défini par un fichier YAML nommé codeql-workspace.yml. Examinons le fichier codeql-workspace.yml suivant :

provide:
  - "**/qlpack.yml"

Et le fichier qlpack.yml du pack de bibliothèques CodeQL suivant dans l’espace de travail :

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

Et le fichier qlpack.yml du pack de requêtes CodeQL suivant dans l’espace de travail :

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

Remarquez que le bloc dependencies pour le pack de requêtes CodeQL, my-company/my-queries, spécifie "*" comme version du pack de bibliothèques. Étant donné que le pack de bibliothèques est déjà défini en tant que dépendance source dans codeql-workspace.yml, le contenu du pack de bibliothèques est toujours résolu à partir de l’espace de travail. Toute contrainte de version que vous définissez est ignorée dans ce cas. Utiliser "*" pour les dépendances de source rend explicite que la version est héritée de l’espace de travail.

Quand vous exécutez codeql pack install à partir du répertoire du pack de requêtes, une version appropriée de codeql/cpp-all est téléchargée dans le cache du package local. De plus, un fichier codeql-pack.lock.yml contenant la version résolue de codeql/cpp-all est créé. Le fichier de verrouillage ne contient pas d’entrée pour my-company/my-library, car il est résolu à partir de dépendances sources. Le fichier codeql-pack.lock.yml va ressembler à ceci :

dependencies:
  codeql/cpp-all:
    version: 0.2.2

Quand vous exécutez codeql pack publish à partir du répertoire du pack de requêtes, la dépendance codeql/cpp-all du cache du package et la bibliothèque my-company/my-library de l’espace de travail sont regroupées avec my-company/my-queries et publiées dans le registre de conteneurs GitHub.

Exemple de codeql-workspace.yml fichier

Un espace de travail CodeQL est défini par un fichier YAML nommé codeql-workspace.yml. Ce fichier contient un bloc provide et éventuellement des blocs ignore et registries.

  • Le bloc provide contient la liste des patrons globaux qui définissent les packs CodeQL disponibles dans l’espace de travail.

  • Le bloc ignore contient la liste des modèles glob qui définissent les packs CodeQL non disponibles dans l’espace de travail.

  • Le bloc registries contient la liste des URL GHES et des modèles de package qui contrôlent le registre de conteneurs utilisé pour la publication des packs CodeQL. Consultez « Publication et utilisation de packs CodeQL ».

Chaque entrée de la section provide ou ignore doit correspondre à l’emplacement d’un fichier qlpack.yml. Tous les modèles Glob sont définis par rapport au répertoire qui contient le fichier d’espace de travail. Pour obtenir la liste des modèles acceptés dans ce fichier, consultez @actions/glob.

Par exemple, le fichier codeql-workspace.yml suivant définit un espace de travail qui contient tous les packs CodeQL trouvés de manière récursive dans le répertoire codeql-packs, à l’exception des packs inclus dans le répertoire experimental. Le bloc registries spécifie que les packs codeql/\* doivent être téléchargés à partir de https://ghcr.io/v2/, à savoir le registre de conteneurs par défaut de GitHub. Tous les autres packs doivent être téléchargés depuis le registre situé à l’adresse GHE_HOSTNAME et publiés sur celui-ci.

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/

Vous pouvez répertorier les packs inclus dans un espace de travail en s’exécutant codeql pack ls dans le répertoire de l’espace de travail.

Utilisation de ${workspace} en tant que plage de versions dans les fichiers qlpack.yml

Les packs CodeQL dans un espace de travail peuvent utiliser les espaces réservés spéciaux ${workspace}, ~${workspace}, et ^${workspace} de plage de versions. Ces espaces réservés indiquent que ce pack dépend de la version du pack spécifié qui se trouve actuellement dans l’espace de travail. Cet espace de réserve est généralement utilisé pour les dépendances au sein des packs de bibliothèques afin de s’assurer que, lors de leur publication, les dépendances dans leur fichier qlpack.yml reflètent l’état de l’espace de travail au moment de leur publication.

Example

Tenez compte des deux packs de bibliothèque suivants dans le même espace de travail :

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

Lorsque my-company/my-library est publié dans le registre de conteneurs GitHub, la version de la dépendance my-company/my-library2 dans le fichier qlpack.yml publié est écrite en tant que 4.5.6.

De même, si la dépendance est my-company/my-library2: ^${workspace} dans le pack source, puis que le pack est publié, la version de la my-company/my-library2 dépendance dans le fichier qlpack.yml publié est écrite en tant que ^4.5.6, indiquant que les versions >= 4.5.6 et < 5.0.0 sont toutes compatibles avec ce pack de bibliothèque.

Si la dépendance est my-company/my-library2: ~${workspace} dans le pack source, puis que le pack est ensuite publié, la version de la dépendance my-company/my-library2 dans le fichier qlpack.yml publié est écrite en tant que ~4.5.6, indiquant que les versions >= 4.5.6 et < 4.6.0 sont toutes compatibles avec ce pack de bibliothèque.