Informationen zu CodeQL-Arbeitsbereichen

Informationen zu CodeQL-Arbeitsbereichen

Ein CodeQL Arbeitsbereich wird in der Regel verwendet, um eine Reihe von Bibliotheks- und Abfrage-Packs zu entwickeln, die voneinander abhängen. Wenn du einen CodeQL-Arbeitsbereich verwendest, stehen alle CodeQL-Pakete im Arbeitsbereich als Quellabhängigkeiten füreinander zur Verfügung, wenn du einen CodeQL-Befehl ausführst, der Abfragen auflöst. Dies erleichtert die Entwicklung, Verwaltung und Veröffentlichung mehrerer zusammengehöriger CodeQL-Pakete. Weitere Informationen zu CodeQL-Paketen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Arbeitsbereiche werden häufig in einem einzigen Git-Repository gespeichert, sodass verwandte Pakete gemeinsam entwickelt und veröffentlicht werden können.

Quellabhängigkeiten

In einem CodeQL Arbeitsbereich werden alle im Arbeitsbereich enthaltenen Pakete als Quellabhängigkeiten voneinander behandelt. Dies bedeutet, dass sie direkt aus dem lokalen Dateisystem aufgelöst werden, anstatt aus dem CodeQL Paketcache.

Da Arbeitsbereichspakete aus der Quelle aufgelöst werden:

• Lokale Änderungen in einem Paket sind sofort für andere Pakete im Arbeitsbereich sichtbar.
• Gefundene Abhängigkeiten im Arbeitsbereich überschreiben Versionen im Paketcache.
• Versionsbeschränkungen in qlpack.yml Dateien werden für Arbeitsbereichsabhängigkeiten ignoriert, da die Version durch den Arbeitsbereichsinhalt bestimmt wird.

Dieses Verhalten ist besonders nützlich, wenn mehrere verwandte Pakete gleichzeitig entwickelt werden. Beispiel:

• Eine Abhängigkeit wurde noch nicht veröffentlicht und ist nur lokal vorhanden.
• Sie nehmen koordinierte Änderungen an mehreren Paketen vor und müssen sicherstellen, dass sie während des Testens aufeinander abgestimmt werden.

Außerhalb eines Arbeitsbereichs werden Abhängigkeiten aus dem Paketcache aufgelöst und müssen mit den in qlpack.ymldefinierten Versionsbeschränkungen übereinstimmen. Innerhalb eines Arbeitsbereichs priorisiert die Auflösung stattdessen lokale Quellinhalte.

CodeQL-Arbeitsbereiche und Abfrageauflösung

Das Arbeitsbereichsabhängigkeitsmodell wirkt sich auf die Installation und Veröffentlichung von Paketen aus.

• Während der Installation werden abhängigkeiten, die sich im Arbeitsbereich befinden, nicht in den Paketcache heruntergeladen und nicht in die codeql-pack.lock.yml Datei geschrieben.
• Während der Veröffentlichung werden vom Arbeitsbereich bereitgestellte Abhängigkeiten mithilfe ihrer lokalen Quellinhalte anstelle von Versionen aus dem Paketcache gebündelt.

Wenn Sie beispielsweise codeql pack install in einem Packverzeichnis innerhalb eines Arbeitsbereichs ausführen, werden Abhängigkeiten verwendet, die im Arbeitsbereich gefunden werden, anstatt sie in den Paketzwischenspeicher herunterzuladen oder in der codeql-pack.lock.yml Datei aufzuzeichnen. Weitere Informationen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Example

Ein CodeQL Arbeitsbereich wird durch eine YAML-Datei mit dem Namen codeql-workspace.ymldefiniert. Betrachten Sie die folgende codeql-workspace.yml -Datei:

provide:
  - "**/qlpack.yml"

Und die folgende CodeQL-Bibliothekspaketdatei qlpack.yml im Arbeitsbereich:

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

Und die folgende CodeQL-Abfragepaketdatei qlpack.yml im Arbeitsbereich:

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

Der dependencies-Block für das CodeQL-Abfragepaket my-company/my-queries gibt "*" als Version des Bibliothekspakets an. Da das Bibliothekspaket bereits als Quellabhängigkeit in codeql-workspace.yml definiert ist, wird der Inhalt des Bibliothekspakets immer innerhalb des Arbeitsbereichs aufgelöst. Alle von dir definierten Versionseinschränkungen werden in diesem Fall ignoriert. Die Verwendung von "*" für Quellabhängigkeiten macht deutlich, dass die Version vom Arbeitsbereich geerbt wird.

Wenn du codeql pack install über das Abfragepaketverzeichnis ausführst, wird eine entsprechende Version von codeql/cpp-all in den lokalen Paketcache heruntergeladen. Außerdem wird eine codeql-pack.lock.yml-Datei erstellt, die die aufgelöste Version von codeql/cpp-all enthält. Die Sperrdatei enthält keinen Eintrag für my-company/my-library, da sie über Quellabhängigkeiten aufgelöst wird. Die Datei codeql-pack.lock.yml sollte in etwa wie folgt aussehen:

dependencies:
  codeql/cpp-all:
    version: 0.2.2

Wenn du codeql pack publish über das Abfragepaketverzeichnis ausführst, werden die codeql/cpp-all-Abhängigkeit aus dem Paketcache und das my-company/my-library-Paket aus dem Arbeitsbereich mit my-company/my-queries gebündelt und in der GitHub-Containerregistrierung veröffentlicht.

Beispiel für eine codeql-workspace.yml Datei

Ein CodeQL Arbeitsbereich wird durch eine YAML-Datei mit dem Namen codeql-workspace.ymldefiniert. Diese Datei enthält einen provide-Block und optional ignore- und registries-Blöcke.

• Der provide-Block enthält eine Liste der Globmuster, die die CodeQL-Pakete definieren, die im Arbeitsbereich verfügbar sind.

• Der ignore-Block enthält eine Liste der Globmuster, die die CodeQL-Pakete definieren, die nicht im Arbeitsbereich verfügbar sind.

• Der registries-Block enthält eine Liste der GHES-URLs und Paketmuster, die steuern, welche Containerregistrierung für die Veröffentlichung von CodeQL-Paketen verwendet wird. Weitere Informationen findest du unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Jeder Eintrag im Abschnitt provide oder ignore muss dem Speicherort einer qlpack.yml-Datei zugeordnet werden. Alle Glob-Muster werden relativ zu dem Verzeichnis definiert, das die Arbeitsbereichsdatei enthält. Eine Liste der in dieser Datei akzeptierten Muster findest du unter @actions/glob.

Die folgende codeql-workspace.yml-Datei definiert beispielsweise einen Arbeitsbereich, der alle CodeQL-Pakete enthält, die rekursiv im Verzeichnis codeql-packs gefunden werden, mit Ausnahme der Pakete im Verzeichnis experimental. Der registries-Block gibt an, dass codeql/\*-Pakete von https://ghcr.io/v2/heruntergeladen werden sollen. Dabei handelt es sich um die Standardcontainerregistrierung von GitHub. Alle anderen Pakete sollten von GHE_HOSTNAME heruntergeladen und in der dortigen Registrierung veröffentlicht werden.

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/

Indem Sie codeql pack ls im Arbeitsverzeichnis des Arbeitsbereichs ausführen, können Sie die in einem Arbeitsbereich enthaltenen Pakete auflisten.

Verwendung von ${workspace} als Versionsbereich in qlpack.yml-Dateien

CodeQL-Pakete in einem Arbeitsbereich können die speziellen Platzhalter für Versionsbereiche ${workspace}, ~${workspace} und ^${workspace} verwenden. Diese Platzhalter geben an, dass dieses Paket von der Version des angegebenen Pakets abhängt, das sich derzeit im Arbeitsbereich befindet. Dieser Platzhalter wird in der Regel für Abhängigkeiten innerhalb von Bibliothekspaketen verwendet, um sicherzustellen, dass die Abhängigkeiten in ihrer qlpack.yml-Datei den Zustand des Arbeitsbereichs widerspiegeln, wenn sie veröffentlicht werden.

Example

Betrachten Sie die folgenden beiden Bibliothekspakete im selben Arbeitsbereich:

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

Wenn my-company/my-library in der GitHub-Containerregistrierung veröffentlicht wird, wird die Version der my-company/my-library2-Abhängigkeit in der veröffentlichten qlpack.yml-Datei als 4.5.6 geschrieben.

Wenn die Abhängigkeit my-company/my-library2: ^${workspace} im Quellpaket ist und das Paket veröffentlicht wird, wird die Version der my-company/my-library2-Abhängigkeit in der veröffentlichten qlpack.yml-Datei als ^4.5.6 geschrieben, was anzeigt, dass die Versionen >= 4.5.6 und < 5.0.0 alle mit diesem Bibliothekspaket kompatibel sind.

Wenn die Abhängigkeit my-company/my-library2: ~${workspace} im Quellpaket ist und das Paket veröffentlicht wird, wird die Version der my-company/my-library2-Abhängigkeit in der veröffentlichten qlpack.yml-Datei als ~4.5.6 geschrieben, was anzeigt, dass die Versionen >= 4.5.6 und < 4.6.0 alle mit diesem Bibliothekspaket kompatibel sind.