About CodeQL workspaces

You use a CodeQL workspace when you want to group multiple CodeQL packs together. A typical use case for a CodeQL workspace is to develop a set of CodeQL library and query packs that are mutually dependent. For more information on CodeQL packs, seeCustomizing analysis with CodeQL packs.

The main benefit of a CodeQL workspace is that it makes it easier for you to develop and maintain multiple CodeQL packs. When you use a CodeQL workspace, all the CodeQL packs in the workspace are available assource dependencies for each other when you run a CodeQL command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related CodeQL packs.

In most cases, you should store the CodeQL workspace and the CodeQL packs contained in it in one git repository. This makes it easier to share your CodeQL development environment.

Thecodeql-workspace.yml file

A CodeQL workspace is defined by acodeql-workspace.yml yaml file. This file contains aprovide block, and optionallyignore andregistries blocks.

• Theprovide block contains a list of glob patterns that define the CodeQL packs that are available in the workspace.

• Theignore block contains a list of glob patterns that define CodeQL packs that are not available in the workspace.

• Theregistries block contains a list of GHES URLs and package patterns that control which container registry is used for publishing CodeQL packs. For more information, seePublishing and using CodeQL packs.

Each entry in theprovide orignore section must map to the location of aqlpack.yml file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see@actions/glob.

For example, the followingcodeql-workspace.yml file defines a workspace that contains all the CodeQL packs recursively found in thecodeql-packs directory, except for the packs in theexperimental directory. Theregistries block specifies thatcodeql/\* packs should be downloaded fromhttps://ghcr.io/v2/, which is GitHub’s default container registry. All other packs should be downloaded from and published to the registry atGHE_HOSTNAME.

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/

To verify that yourcodeql-workspace.yml file includes the CodeQL packs that you expect, run thecodeql pack ls command in the same directory as your workspace. The result of the command is a list of all CodeQL packs in the workspace.

Source dependencies

Source dependencies are CodeQL packs that are resolved from the local file system outside of the CodeQL package cache. These dependencies can be in the same CodeQL workspace, or specified as a path option using the--additional-packs argument. When you compile and run queries locally, source dependencies override any dependencies found in the CodeQL package cache as well as version constraints defined in theqlpack.yml. All references to CodeQL packs in the same workspace are resolved as source dependencies.

This is particularly useful in the following situations:

• One of the dependencies of the query pack you are running is not yet published. Resolving from source is the only way to reference that pack.

• You are making changes to multiple packs at the same time and want to test them together. Resolving from source ensures that you are using the version of the pack with your changes in it.

CodeQL workspaces and query resolution

All CodeQL packs in a workspace are available as source dependencies for each other when you run any CodeQL command that resolves queries or packs. For example, when you runcodeql pack install in a pack directory in a workspace, any dependency that can be found in the workspace will be used instead of downloading that dependency to the package cache and adding it to thecodeql-pack.lock.yml file. For more information, seeCreating and working with CodeQL packs.

Similarly, when you publish a CodeQL query pack to the GitHub container registry usingcodeql pack publish the command will always use the dependencies from the workspace instead of using dependencies found in the local package cache.

This ensures that any local changes you make to a query library in a dependency are automatically reflected in any query packs you publish from that workspace.

Example

Consider the followingcodeql-workspace.yml file:

provide:-"**/qlpack.yml"

And the following CodeQL library packqlpack.yml file in the workspace:

name:my-company/my-librarylibrary:trueversion:1.0.0

And the following CodeQL query packqlpack.yml file in the workspace:

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

Notice that thedependencies block for the CodeQL query pack,my-company/my-queries, specifies"*" as the version of the library pack. Since the library pack is already defined as a source dependency incodeql-workspace.yml, the library pack’s content is always resolved from inside the workspace. Any version constraint you define will be ignored in this case. We recommend that you use"*" for source dependencies to make it clear that the version is inherited from the workspace.

When you executecodeql pack install from the query pack directory, an appropriate version ofcodeql/cpp-all is downloaded to the local package cache. Also, acodeql-pack.lock.yml file is created that contains the resolved version ofcodeql/cpp-all. The lock file won’t contain an entry formy-company/my-library since it is resolved from source dependencies. Thecodeql-pack.lock.yml file will look something like this:

dependencies:codeql/cpp-all:version:0.2.2

When you executecodeql pack publish from the query pack directory, thecodeql/cpp-all dependency from the package cache and themy-company/my-library from the workspace are bundled withmy-company/my-queries and published to the GitHub container registry.

Using${workspace} as a version range inqlpack.yml files

CodeQL packs in a workspace can use the special${workspace},~${workspace}, and^${workspace} version range placeholders. These placeholders indicate that this pack depends on the version of the specified pack that is currently in the workspace. This placeholder is typically used for dependencies inside of library packs to ensure that when they are published, the dependencies in theirqlpack.yml file reflect the state of the workspace when they were published.

Example

Consider the following two library packs in the same workspace:

name:my-company/my-librarylibrary:trueversion:1.2.3dependencies:my-company/my-library2:${workspace}

name:my-company/my-library2library:trueversion:4.5.6

Whenmy-company/my-library is published to the GitHub container registry, the version of themy-company/my-library2 dependency in the publishedqlpack.yml file will be written as4.5.6.

Similarly, if the dependency ismy-company/my-library2: ^${workspace} in the source pack, and then the pack is published, the version of themy-company/my-library2 dependency in the publishedqlpack.yml file will be written as^4.5.6, indicating that versions>= 4.5.6 and< 5.0.0 are all compatible with this library pack.

If the dependency ismy-company/my-library2: ~${workspace} in the source pack, and then the pack is published, the version of themy-company/my-library2 dependency in the publishedqlpack.yml file will be written as~4.5.6, indicating that versions>= 4.5.6 and< 4.6.0 are all compatible with this library pack.