Informationen zu CodeQL-Arbeitsbereichen

Informationen zu CodeQL-Arbeitsbereichen

Du verwendest einen CodeQL-Arbeitsbereich, wenn du mehrere CodeQL-Pakete gruppieren möchtest. Ein typischer Anwendungsfall für einen CodeQL-Arbeitsbereich ist die Entwicklung mit einer CodeQL-Bibliothek und Abfragepaketen, die gegenseitig voneinander abhängig sind. Weitere Informationen zu CodeQL-Paketen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Der Hauptvorteil eines CodeQL-Arbeitsbereichs besteht darin, dass du mehrere CodeQL-Pakete leichter entwickeln und verwalten kannst. 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.

In den meisten Fällen solltest du den Arbeitsbereich CodeQL und die darin enthaltenen CodeQL-Pakete in einem Git-Repository speichern. Dies vereinfacht die Freigabe deiner CodeQL-Entwicklungsumgebung.

Die codeql-workspace.yml-Datei.

Ein CodeQL-Arbeitsbereich wird durch die YAML-Datei codeql-workspace.yml definiert. 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 Globmuster werden relativ zu dem Verzeichnis definiert, das die Arbeitsbereichsdatei enthält. Eine Liste der in dieser Datei akzeptierten Muster finden Sie 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/

Du kannst überprüfen, ob deine codeql-workspace.yml-Datei die erwarteten CodeQL-Pakete enthält, indem du den Befehl codeql pack ls im selben Verzeichnis wie dein Arbeitsbereich ausführst. Das Ergebnis des Befehls ist eine Liste aller CodeQL-Pakete im Arbeitsbereich.

Quellabhängigkeiten

Quellabhängigkeiten sind CodeQL-Pakete, die über das lokale Dateisystem außerhalb des CodeQL-Paketcaches aufgelöst werden. Diese Abhängigkeiten können sich im selben CodeQL-Arbeitsbereich befinden oder als Pfadoption mit dem --additional-packs-Argument angegeben werden. Wenn du Abfragen lokal kompilierst und ausführst, überschreiben Quellabhängigkeiten alle Abhängigkeiten, die im CodeQL-Paketcache gefunden werden, sowie die in qlpack.yml definierten Versionseinschränkungen. Alle Verweise auf CodeQL-Pakete im selben Arbeitsbereich werden als Quellabhängigkeiten aufgelöst.

Das kann insbesondere in folgenden Situationen nützlich sein:

• Eine der Abhängigkeiten des Abfragepakets, das du ausführst, wurde noch nicht veröffentlicht. Die Auflösung über die Quelle ist die einzige Möglichkeit, auf dieses Paket zu verweisen.

• Du nimmst Änderungen an mehreren Paketen gleichzeitig vor und möchtest sie gemeinsam testen. Das Auflösen über die Quelle stellt sicher, dass du die Version des Pakets mit deinen Änderungen verwendest.

CodeQL-Arbeitsbereiche und Abfrageauflösung

Alle CodeQL-Pakete in einem Arbeitsbereich sind als Quellabhängigkeiten füreinander verfügbar, wenn du einen CodeQL-Befehl ausführst, der Abfragen oder Pakete auflöst. Wenn du beispielsweise codeql pack install in einem Paketverzeichnis in einem Arbeitsbereich ausführst, wird jede Abhängigkeit verwendet, die im Arbeitsbereich vorhanden ist, anstatt diese Abhängigkeit in den Paketcache herunterzuladen und der codeql-pack.lock.yml-Datei hinzuzufügen. Weitere Informationen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Ebenso werden beim Veröffentlichen eines CodeQL-Abfragepakets in der GitHub-Containerregistrierung mit dem Befehl codeql pack publish immer die Abhängigkeiten aus dem Arbeitsbereich anstatt der Abhängigkeiten im lokalen Paketcache verwendet.

Dadurch wird sichergestellt, dass alle lokalen Änderungen, die du an einer Abfragebibliothek in einer Abhängigkeit vornimmst, automatisch in allen Abfragepaketen berücksichtigt werden, die du in diesem Arbeitsbereich veröffentlichst.

Beispiel

Betrachte 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. Es wird empfohlen, für Quellabhängigkeiten "*" zu verwenden, um deutlich zu machen, 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.

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

CodeQL-Pakete in einem Arbeitsbereich können die speziellen ${workspace}-, ~${workspace}-, und ^${workspace}-Versionsbereich-Platzhalter 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.

Beispiel

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.