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
docs: address review comments and finalize markdown workflows
- Add 'md' file type support to detect-relevant-changes action
- Enable workflow_call support in markdown-fix.yaml
- Pin markdownlint actions to specific SHAs with full version annotations
- Ensure all action checkouts use full version numbers in annotations (e.g., v6.0.2)
- Unified bot command parsing in markdown-fix.yaml to support @<repo>bot format
Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>
Copy file name to clipboardExpand all lines: .github/CodeQL-README.md
+6-16Lines changed: 6 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,4 @@
1
+
```markdown
1
2
# CodeQL scanning for this repository
2
3
3
4
This repository uses C++ (C++20 / moving to C++23) built with CMake under the phlex-src directory, plus some Python and CI bits (Bash). The repository includes a CodeQL GitHub Actions workflow on branch `copilot/codeql-workflow` that:
@@ -8,26 +9,22 @@ This repository uses C++ (C++20 / moving to C++23) built with CMake under the ph
8
9
- Uses RelWithDebInfo build type in CI so debug symbols are present while keeping realistic optimization.
9
10
10
11
Important workflow-specific notes
11
-
12
12
- The workflow sets `autobuild: false` during the CodeQL init so the repository's own configure / build steps run. This is intentional: the Phlex build actions are used to build exactly what you ship.
13
13
- The workflow tries to locate and copy a compile_commands.json (from `phlex-src/build/` or `phlex-build/`) to the workspace root so diagnostic tools and manual inspection have a predictable path.
14
14
- The workflow runs inside the repository container image (if provided) so it uses the same toolchain and environment your CI expects.
15
15
16
16
How the workflow is targeted at phlex-src
17
-
18
17
- The CMake configure & build steps are run with `-S phlex-src -B phlex-src/build` (or your Phlex-specific helpers are invoked in that context) so compile units, compiler flags, and generated compile_commands reference files under `phlex-src`.
19
18
- The CodeQL config (`.github/codeql/codeql-config.yml`) contains an explicit `paths.include: - phlex-src/**` entry and excludes common vendor/build directories. This ensures CodeQL focuses on the intended code and not third-party or generated artifacts.
20
19
21
20
Recommended build type for CodeQL runs
22
-
23
21
- Use RelWithDebInfo (the workflow is already set to use this). Rationale:
24
22
- RelWithDebInfo produces debug symbols (required for better mapping of findings to source/stack traces) while compiling with optimizations closer to production.
25
23
- Pure Debug (-O0 -g) can be used for local triage of tricky alerts but is slower and sometimes produces analysis results that differ from optimized builds.
26
24
- Release (no debug info) is not recommended for CodeQL because missing debug symbols reduce the quality of evidence and traces in findings.
27
25
28
26
How to run CodeQL locally (examples)
29
-
30
-
1. Install the CodeQL CLI: <https://codeql.github.com/docs/codeql-cli/getting-started/>
27
+
1. Install the CodeQL CLI: https://codeql.github.com/docs/codeql-cli/getting-started/
31
28
2. Create a C++ database for the phlex-src tree (example):
@@ -39,20 +36,17 @@ How to run CodeQL locally (examples)
39
36
5. Open the SARIF in VS Code via the CodeQL extension or upload results via the GitHub UI.
40
37
41
38
Triage tips and workflows
42
-
43
39
- Start with high-confidence, high-severity alerts.
44
40
- Use the evidence shown in the CodeQL alert to locate the vulnerable trace. RelWithDebInfo gives better evidence than Release.
45
41
- When marking false positives, add a short rationale in the Code Scanning UI (this helps future auditors).
46
42
- If the repo has many historical findings, consider a triage sprint to baseline or create a SARIF baseline to ignore existing alerts temporarily while blocking new ones.
47
43
48
44
How to add or change query packs
49
-
50
45
- The repository currently selects the language security-and-quality packs for C++ and Python. That is a good default.
51
46
- If you want to add additional packs (experimental or specialized) you can:
52
47
- Edit `.github/codeql/codeql-config.yml` and add additional packs there (use the canonical pack name), or
53
48
- Add them to the init step in the workflow (`with: queries:`).
54
49
- Example of adding packs in the workflow init:
55
-
56
50
```yaml
57
51
uses: github/codeql-action/init@v4
58
52
with:
@@ -65,14 +59,12 @@ How to add or change query packs
65
59
```
66
60
67
61
Action-specific / workflow scanning
68
-
69
62
- There are CodeQL query packs that specifically analyze GitHub Actions workflow files (YAML) to find insecure patterns (for example: unsafe use of secrets, untrusted inputs in workflow run steps, usage of unpinned actions, etc.). If you rely on custom workflows or pass secrets/inputs to actions, consider enabling the GitHub Actions query pack if it is available in your CodeQL pack index.
70
63
- To discover whether an official GitHub Actions pack exists or to find its exact name, see the CodeQL packs index (the canonical source) or search the public CodeQL repository:
- Search for "github-actions" or "actions" in the CodeQL repo to find action-related packs and their exact pack names.
73
66
74
67
Recommended query packs for this repository (starting point)
75
-
76
68
- github/codeql/cpp-security-and-quality
77
69
- Purpose: Core security and quality queries for C and C++ codebases. Good coverage of common memory safety, API misuse, and typical C/C++ pitfalls.
78
70
- Why: Phlex is primarily C++, so this pack is the most important starting point.
@@ -81,7 +73,6 @@ Recommended query packs for this repository (starting point)
81
73
- Why: Phlex contains some Python; include this pack so those files are analyzed.
82
74
83
75
Other useful pack categories to consider
84
-
85
76
- Language experimental packs (e.g., "cpp-experimental" / "python-experimental")
86
77
- These provide newer/experimental queries that are not yet in the stable security-and-quality pack. Use cautiously: they can produce more findings and more false positives.
87
78
- Action/workflow packs (GitHub Actions specific)
@@ -90,17 +81,15 @@ Other useful pack categories to consider
90
81
- If Phlex heavily uses a certain third-party library that has its own pack, consider enabling it to get library-specific rules.
91
82
92
83
How to find the exact pack names and descriptions
93
-
94
84
- Official source: the GitHub CodeQL packs and QL repos:
- CodeQL CLI (partial support for pack discovery):
98
88
- You can use `codeql pack` and `codeql resolve` commands to inspect installed packs. The CodeQL CLI documentation shows usage for installing and listing packs.
99
89
- GitHub docs:
100
90
- Code scanning docs and the CodeQL repo README often list recommended packs and query categories.
101
91
102
92
Suggested immediate next steps
103
-
104
93
1. Keep the current packs (cpp-security-and-quality and python-security-and-quality) enabled in `.github/codeql/codeql-config.yml` — they are the right baseline.
105
94
2. Search the CodeQL packs index for any GitHub Actions pack and enable it if you want workflow-level checks.
106
95
3. If you want more thorough coverage, enable the experimental packs temporarily in a non-blocking run, review the alerts, then decide whether to include them in CI permanently.
@@ -136,3 +125,4 @@ When a PR is opened from a fork, the `GITHUB_TOKEN` does not have permission to
136
125
## Contact / Ownership
137
126
138
127
- Consider adding a CODEOWNERS file for the phlex-src tree so triage notifications reach the most appropriate maintainers.
Copy file name to clipboardExpand all lines: .github/REUSABLE_WORKFLOWS.md
+29-29Lines changed: 29 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,13 +28,13 @@ Once you have done this, you can trigger the auto-fix workflows by commenting on
28
28
For workflows that automatically commit fixes to pull requests (e.g., formatters), you must create a Personal Access Token (PAT) and add it as a secret to your repository.
29
29
30
30
1.**Create a PAT:** Follow the GitHub documentation to [create a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
31
-
- Give it a descriptive name (e.g., `WORKFLOW_FIXES_PAT`).
32
-
- Grant it the following repository permissions:
33
-
-`Contents`: `Read and write`
34
-
-`Pull requests`: `Read and write`
31
+
-Give it a descriptive name (e.g., `WORKFLOW_FIXES_PAT`).
32
+
-Grant it the following repository permissions:
33
+
-`Contents`: `Read and write`
34
+
-`Pull requests`: `Read and write`
35
35
2.**Add the PAT as a Repository Secret:**
36
-
- In your repository, go to `Settings` > `Secrets and variables` > `Actions`.
37
-
- Create a new repository secret named `WORKFLOW_PAT` and paste your PAT as the value.
36
+
-In your repository, go to `Settings` > `Secrets and variables` > `Actions`.
37
+
-Create a new repository secret named `WORKFLOW_PAT` and paste your PAT as the value.
38
38
39
39
### Calling a Reusable Workflow from a Different Repository
40
40
@@ -80,14 +80,14 @@ jobs:
80
80
81
81
#### All Inputs
82
82
83
-
- `checkout-path` (string, optional): Path to check out code to.
84
-
- `build-path` (string, optional): Path for build artifacts.
85
-
- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
86
-
- `build-combinations` (string, optional): A space-separated list of build combinations to run.
87
-
- `ref` (string, optional): The branch or ref to check out.
88
-
- `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
89
-
- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
90
-
- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
83
+
- `checkout-path` (string, optional): Path to check out code to.
84
+
- `build-path` (string, optional): Path for build artifacts.
85
+
- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
86
+
- `build-combinations` (string, optional): A space-separated list of build combinations to run.
87
+
- `ref` (string, optional): The branch or ref to check out.
88
+
- `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
89
+
- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
90
+
- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
91
91
92
92
### 2. `python-check.yaml`
93
93
@@ -103,10 +103,10 @@ jobs:
103
103
104
104
#### All Inputs
105
105
106
-
- `checkout-path` (string, optional): Path to check out code to.
107
-
- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
108
-
- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
109
-
- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
106
+
- `checkout-path` (string, optional): Path to check out code to.
107
+
- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
108
+
- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
109
+
- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
110
110
111
111
### 3. `cmake-format-fix.yaml`
112
112
@@ -140,9 +140,9 @@ jobs:
140
140
141
141
#### All Inputs
142
142
143
-
- `checkout-path` (string, optional): Path to check out code to.
144
-
- `ref` (string, **required**): The branch or ref to check out.
145
-
- `repo` (string, **required**): The repository to check out from.
143
+
- `checkout-path` (string, optional): Path to check out code to.
144
+
- `ref` (string, **required**): The branch or ref to check out.
145
+
- `repo` (string, **required**): The repository to check out from.
146
146
147
147
### 4. `python-fix.yaml`
148
148
@@ -154,23 +154,23 @@ Automatically formats and fixes Python code using `ruff` and commits the changes
154
154
155
155
#### All Inputs
156
156
157
-
- `checkout-path` (string, optional): Path to check out code to.
158
-
- `ref` (string, **required**): The branch or ref to check out.
159
-
- `repo` (string, **required**): The repository to check out from.
157
+
- `checkout-path` (string, optional): Path to check out code to.
158
+
- `ref` (string, **required**): The branch or ref to check out.
159
+
- `repo` (string, **required**): The repository to check out from.
160
160
161
161
### 5. `markdown-fix.yaml`
162
162
163
163
Automatically formats Markdown files using `markdownlint` and commits the changes. Typically triggered by an `issue_comment`.
164
164
165
-
#### Usage Example: `markdown-fix.yaml` (in a workflow triggered by `issue_comment`)
165
+
#### Usage Example (in a workflow triggered by `issue_comment`)
166
166
167
167
*Similar to `cmake-format-fix.yaml`, but triggered by a command like `@<repo>bot markdown-fix`.*
168
168
169
-
#### All Inputs: `markdown-fix.yaml`
169
+
#### All Inputs
170
170
171
-
- `checkout-path` (string, optional): Path to check out code to.
172
-
- `ref` (string, **required**): The branch or ref to check out.
173
-
- `repo` (string, **required**): The repository to check out from.
171
+
- `checkout-path` (string, optional): Path to check out code to.
172
+
- `ref` (string, **required**): The branch or ref to check out.
173
+
- `repo` (string, **required**): The repository to check out from.
Copy file name to clipboardExpand all lines: DEVELOPING.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -114,6 +114,7 @@ The project automatically runs coverage analysis on every PR and push to main/de
114
114
115
115
Coverage reports are uploaded to Codecov for tracking and PR integration, with automatic comments on PRs showing coverage changes.
116
116
117
+
117
118
## On GitHub Copilot
118
119
119
120
The `.github/copilot-instructions.md` contains various "ground rules" to be observed by GitHub Copilot for every session. They are intended to be useful for everyone, but you can override or augment them yourself by creating a `<workspace>/.github/copilot-instructions.md` file. If this file exists, its contents will be merged with—but take precedence over—the repository level instructions.
Copy file name to clipboardExpand all lines: INSTALLATION.md
+4-11Lines changed: 4 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Overview
1
+
##Overview
2
2
3
3
These instructions are intended to get users (not developers) of Phlex to a working environment, starting from scratch.
4
4
This is not the only way in which this can be done, but this method has been verified on the primary supported OS (Alma Linux 9) and will be supported by the Phlex development team on that platform.
@@ -7,7 +7,7 @@ We assume that you do *not* have an installation of Spack already.
7
7
We only support Spack v1.0 and newer, so if you have an older version of Spack we recommend installation of a new one according to these instructions.
8
8
If you already have a new-enough version of Spack installed, you can skip to step 6.
9
9
10
-
## Installing Spack
10
+
###Installing Spack
11
11
12
12
Step 1: create a working directory for phlex use:
13
13
@@ -22,27 +22,22 @@ cd ${PHLEX_WORK_DIR}
22
22
```
23
23
24
24
Then make sure you don't already have a spack command on your PATH:
If you encounter trouble, consult the [installation instructions from the Spack project](https://spack-tutorial.readthedocs.io/en/latest/tutorial_basics.html#basics-tutorial).
![google-labs-jules[bot]](https://avatars.githubusercontent.com/in/842251?v=4&size=40){kind=avatar}
0 commit comments