À propos des espaces de travail CodeQL
Note
Cet article décrit les fonctionnalités disponibles avec la version de l’action CodeQL et le bundle CodeQL CLI associé inclus dans la mise en production initiale de cette version de GitHub Enterprise Server. Si votre entreprise utilise une version plus récente de l’action CodeQL, consultez la version GitHub Enterprise Cloud de cet article pour obtenir plus d’informations sur les dernières fonctionnalités. Pour plus d’informations sur l’utilisation de la dernière version, consultez « Configuration de l’analyse de code pour votre appliance ».
Vous utilisez un espace de travail CodeQL quand vous voulez regrouper plusieurs packs CodeQL ensemble. Un cas d’usage classique pour un espace de travail CodeQL consiste à développer un ensemble de bibliothèques et de packs de requêtes CodeQL qui dépendent les uns des autres. Pour plus d’informations sur les packs CodeQL, consultez « Personnalisation de l’analyse avec des packs CodeQL ».
Le principal avantage d’un espace de travail CodeQL est qu’il vous permet de développer et de gérer plus facilement plusieurs packs CodeQL. 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.
Dans la plupart des cas, il est préférable de stocker l’espace de travail CodeQL et les packs CodeQL qu’il contient dans un seul dépôt Git. Le partage de votre environnement de développement CodeQL s’en retrouve ainsi facilité.
Le fichier codeql-workspace.yml
Un espace de travail CodeQL est défini par un fichier yaml codeql-workspace.yml
. Ce fichier contient un bloc provide
et éventuellement des blocs ignore
et registries
.
-
Le bloc
provide
contient la liste des modèles Glob 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. Pour plus d’informations, 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/
Pour vérifier que votre fichier codeql-workspace.yml
inclut les packs CodeQL attendus, exécutez la commande codeql pack ls
dans le même répertoire que votre espace de travail. Le résultat de la commande est la liste de tous les packs CodeQL inclus dans l’espace de travail.
Dépendances sources
Les dépendances sources sont des packs CodeQL résolus à partir du système de fichiers local en dehors du cache des packages CodeQL. Ces dépendances peuvent se trouver dans le même espace de travail CodeQL ou être spécifiées sous forme d’option de chemin à l’aide de l’argument --additional-packs
. Quand vous compilez et exécutez des requêtes localement, les dépendances sources remplacent toutes les dépendances trouvées dans le cache des packages CodeQL ainsi que les contraintes de version définies dans le fichier qlpack.yml
. Toutes les références aux packs CodeQL dans le même espace de travail sont résolues en dépendances sources.
Cela s’avère particulièrement utile dans les situations suivantes :
-
L’une des dépendances du pack de requêtes que vous exécutez n’est pas encore publiée. La résolution à partir de la source est la seule façon de référencer ce pack.
-
Vous apportez des modifications à plusieurs packs en même temps et vous voulez les tester ensemble. La résolution à partir de la source garantit que vous utilisez la version du pack qui contient vos modifications.
Résolution des requêtes et espaces de travail CodeQL
Tous les packs CodeQL inclus dans un espace de travail sont disponibles en tant que dépendances sources les uns pour les autres quand vous exécutez une commande CodeQL qui résout des requêtes ou des packs. Par exemple, quand vous exécutez codeql pack install
dans le répertoire d’un pack dans un espace de travail, toute dépendance qui se trouve dans l’espace de travail est utilisée au lieu de télécharger cette dépendance dans le cache du package et de l’ajouter au fichier codeql-pack.lock.yml
. Pour plus d’informations, consultez « Création et utilisation de packs CodeQL ».
De même, lorsque vous publiez un CodeQL query pack dans le registre de conteneurs GitHub en utilisant la commande codeql pack publish
utilisera toujours les dépendances de l'espace de travail au lieu d'utiliser les dépendances trouvées dans le cache local des paquets.
Cela garantit que toutes les modifications locales que vous apportez à une bibliothèque de requêtes dans une dépendance sont automatiquement répercutées dans les packs de requêtes que vous publiez à partir de cet espace de travail.
Exemple
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. Nous vous recommandons d’utiliser "*"
pour les dépendances sources afin de bien montrer 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.
Utilisation de ${workspace}
en tant que plage de versions dans les fichiers qlpack.yml
CodeQL packs 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 réservé est généralement utilisé pour les dépendances à l’intérieur des packs de bibliothèque afin de s’assurer que lorsqu’ils sont publiés. Les dépendances dans leur fichier qlpack.yml
reflètent l’état de l’espace de travail lorsqu’ils ont été publiés.
Exemple
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.