You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/code-security/concepts/code-scanning/codeql/about-codeql-workspaces.md
+49-43Lines changed: 49 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: About CodeQL workspaces
3
3
shortTitle: CodeQL workspaces
4
-
intro: '{% data variables.product.prodname_codeql %} workspaces allow you to develop and maintain a group of {% data variables.product.prodname_codeql %} packs that depend on each other.'
4
+
intro: '{% data variables.product.prodname_codeql %} workspaces let you develop and maintain multiple related {% data variables.product.prodname_codeql %} packs together, resolving dependencies between them directly from source.'
5
5
product: '{% data reusables.gated-features.codeql %}'
6
6
versions:
7
7
fpt: '*'
@@ -22,63 +22,39 @@ contentType: concepts
22
22
23
23
{% data reusables.code-scanning.codeql-action-version-ghes %}
24
24
25
-
You use a {% data variables.product.prodname_codeql %} workspace when you want to group multiple {% data variables.product.prodname_codeql %} packs together. A typical use case for a {% data variables.product.prodname_codeql %} workspace is to develop a set of {% data variables.product.prodname_codeql %} library and query packs that are mutually dependent. For more information on {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).
25
+
A {% data variables.product.prodname_codeql %} workspace is typically used to develop a set of library and query packs that depend on each other. When you use a {% data variables.product.prodname_codeql %} workspace, all the {% data variables.product.prodname_codeql %} packs in the workspace are available as _source dependencies_for each other when you run a {% data variables.product.prodname_codeql %} command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related {% data variables.product.prodname_codeql %} packs. For more information on {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).
26
26
27
-
The main benefit of a {% data variables.product.prodname_codeql %} workspace is that it makes it easier for you to develop and maintain multiple {% data variables.product.prodname_codeql %} packs. When you use a {% data variables.product.prodname_codeql %} workspace, all the {% data variables.product.prodname_codeql %} packs in the workspace are available as _source dependencies_ for each other when you run a {% data variables.product.prodname_codeql %} command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related {% data variables.product.prodname_codeql %} packs.
27
+
Workspaces are commonly stored in a single Git repository so that related packs can be developed and published together.
28
28
29
-
In most cases, you should store the {% data variables.product.prodname_codeql %} workspace and the {% data variables.product.prodname_codeql %} packs contained in it in one git repository. This makes it easier to share your {% data variables.product.prodname_codeql %} development environment.
30
-
31
-
## The `codeql-workspace.yml` file
32
-
33
-
A {% data variables.product.prodname_codeql %} workspace is defined by a `codeql-workspace.yml` yaml file. This file contains a `provide` block, and optionally `ignore` and `registries` blocks.
34
-
35
-
* The `provide` block contains a list of glob patterns that define the {% data variables.product.prodname_codeql %} packs that are available in the workspace.
36
-
37
-
* The `ignore` block contains a list of glob patterns that define {% data variables.product.prodname_codeql %} packs that are not available in the workspace.
38
-
39
-
* The `registries` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing {% data variables.product.prodname_codeql %} packs. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes).
40
-
41
-
Each entry in the `provide` or `ignore` section must map to the location of a `qlpack.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](https://github.com/actions/toolkit/tree/main/packages/glob#patterns).
42
-
43
-
For example, the following `codeql-workspace.yml` file defines a workspace that contains all the {% data variables.product.prodname_codeql %} packs recursively found in the `codeql-packs` directory, except for the packs in the `experimental` directory. The `registries` block specifies that `codeql/\*` packs should be downloaded from `https://ghcr.io/v2/`, which is {% data variables.product.prodname_dotcom %}’s default container registry. All other packs should be downloaded from and published to the registry at `GHE_HOSTNAME`.
44
-
45
-
```yaml
46
-
provide:
47
-
- "*/codeql-packs/**/qlpack.yml"
48
-
ignore:
49
-
- "*/codeql-packs/**/experimental/**/qlpack.yml"
50
-
51
-
registries:
52
-
- packages: 'codeql/*'
53
-
url: https://ghcr.io/v2/
54
-
55
-
- packages: '*'
56
-
url: https://containers.GHE_HOSTNAME/v2/
57
-
```
29
+
## Source dependencies
58
30
59
-
To verify that your `codeql-workspace.yml` file includes the {% data variables.product.prodname_codeql %} packs that you expect, run the `codeql pack ls` command in the same directory as your workspace. The result of the command is a list of all {% data variables.product.prodname_codeql %} packs in the workspace.
31
+
In a {% data variables.product.prodname_codeql %} workspace, all packs included in the workspace are treated as **source dependencies** of each other. This means they are resolved directly from the local file system rather than from the {% data variables.product.prodname_codeql %} package cache.
60
32
61
-
## Source dependencies
33
+
Because workspace packs resolve from source:
62
34
63
-
Source dependencies are {% data variables.product.prodname_codeql %} packs that are resolved from the local file system outside of the {% data variables.product.prodname_codeql %} package cache. These dependencies can be in the same {% data variables.product.prodname_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 {% data variables.product.prodname_codeql %} package cache as well as version constraints defined in the `qlpack.yml`. All references to {% data variables.product.prodname_codeql %} packs in the same workspace are resolved as source dependencies.
35
+
* Local changes in one pack are immediately visible to other packs in the workspace.
36
+
* Dependencies found in the workspace override versions in the package cache.
37
+
* Version constraints in `qlpack.yml` files are ignored for workspace dependencies, since the version is determined by the workspace content.
64
38
65
-
This is particularly useful in the following situations:
39
+
This behavior is particularly useful when developing multiple related packs at the same time. For example:
66
40
67
-
* 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.
41
+
* A dependency has not yet been published and exists only locally.
42
+
* You are making coordinated changes across several packs and need them to resolve against each other during testing.
68
43
69
-
* 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.
44
+
Outside of a workspace, dependencies are resolved from the package cache and must match the version constraints defined in `qlpack.yml`. Inside a workspace, resolution prioritizes local source content instead.
70
45
71
46
## {% data variables.product.prodname_codeql %} workspaces and query resolution
72
47
73
-
All {% data variables.product.prodname_codeql %} packs in a workspace are available as source dependencies for each other when you run any {% data variables.product.prodname_codeql %} command that resolves queries or packs. For example, when you run `codeql 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 the `codeql-pack.lock.yml` file. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies).
48
+
The workspace dependency model affects how packs are installed and published.
74
49
75
-
Similarly, when you publish a {% data variables.product.prodname_codeql %} query pack to the {% data variables.product.prodname_dotcom %} container registry using `codeql pack publish` the command will always use the dependencies from the workspace instead of using dependencies found in the local package cache.
50
+
* During installation, dependencies found in the workspace are not downloaded into the package cache and are not written to the `codeql-pack.lock.yml` file.
51
+
* During publishing, dependencies provided by the workspace are bundled using their local source content rather than versions from the package cache.
76
52
77
-
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.
53
+
For example, running `codeql pack install` in a pack directory within a workspace uses any dependencies found in the workspace instead of downloading them into the package cache or recording them in the `codeql-pack.lock.yml` file. See [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies).
78
54
79
55
### Example
80
56
81
-
Consider the following `codeql-workspace.yml` file:
57
+
A {% data variables.product.prodname_codeql %} workspace is defined by a YAML file named `codeql-workspace.yml`. Consider the following `codeql-workspace.yml` file:
82
58
83
59
```yaml
84
60
provide:
@@ -103,7 +79,7 @@ dependencies:
103
79
codeql/cpp-all: ~0.2.0
104
80
```
105
81
106
-
Notice that the `dependencies` block for the {% data variables.product.prodname_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 in `codeql-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.
82
+
Notice that the `dependencies` block for the {% data variables.product.prodname_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 in `codeql-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. Using `"*"` for source dependencies makes it explicit that the version is inherited from the workspace.
107
83
108
84
When you execute `codeql pack install` from the query pack directory, an appropriate version of `codeql/cpp-all` is downloaded to the local package cache. Also, a `codeql-pack.lock.yml` file is created that contains the resolved version of `codeql/cpp-all`. The lock file won’t contain an entry for `my-company/my-library` since it is resolved from source dependencies. The `codeql-pack.lock.yml` file will look something like this:
109
85
@@ -115,6 +91,36 @@ dependencies:
115
91
116
92
When you execute `codeql pack publish` from the query pack directory, the `codeql/cpp-all` dependency from the package cache and the `my-company/my-library` from the workspace are bundled with `my-company/my-queries` and published to the {% data variables.product.prodname_dotcom %} container registry.
117
93
94
+
## Example of a `codeql-workspace.yml` file
95
+
96
+
A {% data variables.product.prodname_codeql %} workspace is defined by a YAML file named `codeql-workspace.yml`. This file contains a `provide` block, and optionally `ignore` and `registries` blocks.
97
+
98
+
* The `provide` block contains a list of glob patterns that define the {% data variables.product.prodname_codeql %} packs that are available in the workspace.
99
+
100
+
* The `ignore` block contains a list of glob patterns that define {% data variables.product.prodname_codeql %} packs that are not available in the workspace.
101
+
102
+
* The `registries` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing {% data variables.product.prodname_codeql %} packs. See [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes).
103
+
104
+
Each entry in the `provide` or `ignore` section must map to the location of a `qlpack.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](https://github.com/actions/toolkit/tree/main/packages/glob#patterns).
105
+
106
+
For example, the following `codeql-workspace.yml` file defines a workspace that contains all the {% data variables.product.prodname_codeql %} packs recursively found in the `codeql-packs` directory, except for the packs in the `experimental` directory. The `registries` block specifies that `codeql/\*` packs should be downloaded from `https://ghcr.io/v2/`, which is {% data variables.product.prodname_dotcom %}’s default container registry. All other packs should be downloaded from and published to the registry at `GHE_HOSTNAME`.
107
+
108
+
```yaml
109
+
provide:
110
+
- "*/codeql-packs/**/qlpack.yml"
111
+
ignore:
112
+
- "*/codeql-packs/**/experimental/**/qlpack.yml"
113
+
114
+
registries:
115
+
- packages: 'codeql/*'
116
+
url: https://ghcr.io/v2/
117
+
118
+
- packages: '*'
119
+
url: https://containers.GHE_HOSTNAME/v2/
120
+
```
121
+
122
+
You can list the packs included in a workspace by running `codeql pack ls` in the workspace directory.
123
+
118
124
## Using `${workspace}` as a version range in `qlpack.yml` files
119
125
120
126
{% data variables.product.prodname_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 their `qlpack.yml` file reflect the state of the workspace when they were published.
0 commit comments