Docs: Add GitHub Actions as a supported language #19190
Conversation
Include GitHub Actions (identifier `actions`) everywhere we list supported languages, query packs, and library packs. Query and library documentation link targets do not exist yet.
There was a problem hiding this comment.
Pull Request Overview
This PR updates documentation to add support for GitHub Actions as a recognized language in query guides and to adjust the ordering and naming of related language entries.
- Added GitHub Actions queries entries to both the query metadata and query help style guides.
- Renamed "Java queries" to "Java/Kotlin queries" and updated "JavaScript queries" to "JavaScript/TypeScript queries" for clarity.
- Added Ruby and Swift queries entries to ensure completeness in the supported languages list.
Reviewed Changes
Copilot reviewed 2 out of 8 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/query-metadata-style-guide.md | Added GitHub Actions entry and updated existing language entries to reflect broader language support. |
| docs/query-help-style-guide.md | Introduced GitHub Actions entry and updated Java/JavaScript entries to accommodate expanded language names. |
Files not reviewed (6)
- docs/codeql/codeql-overview/codeql-tools.rst: Language not supported
- docs/codeql/reusables/actions-further-reading.rst: Language not supported
- docs/codeql/reusables/extractors.rst: Language not supported
- docs/codeql/reusables/supported-frameworks.rst: Language not supported
- docs/codeql/reusables/supported-versions-compilers.rst: Language not supported
- docs/codeql/writing-codeql-queries/about-codeql-queries.rst: Language not supported
Tip: Copilot only keeps its highest confidence comments to reduce noise and keep you focused. Learn more
Create the basic structure, state the key importable libraries. Describe a workflow. State the extensible predicates available. Other elements are to be filled in later.
docs/codeql/codeql-language-guides/codeql-library-for-actions.rst
Outdated
Show resolved
Hide resolved
| - An Actions workflow. This is a mapping at the top level of an Actions YAML workflow file. See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions. | ||
| - `getAJob()` - Gets a job within the `jobs` mapping of this workflow. | ||
| - `getEnv()` - Gets an `env` mapping within this workflow declaring workflow-level environment variables, if any. | ||
| - `getJob(string jobId)` - Gets a job within the `jobs` mapping of this workflow with the given job ID. |
There was a problem hiding this comment.
For my education. Is there a preference in having this defined as a function (getJob("potato")) rather than a relation (getJob().getName() = "potato") in the query?
There was a problem hiding this comment.
Without taking the string as a parameter, to reason about the specific job by that name, it would look something like
exists(Job job |
job = workflow.getAJob() and
job.getName() = "potato" and
// whatever else you want to say about the job
)One can also do
workflow.getAJob().getName() = "potato"but that only asserts that there is a job with this name, it doesn't let you perform any further reasoning involving that specific job.
| @@ -40,3 +41,4 @@ | |||
| .. [9] Requires glibc 2.17. | |||
| .. [10] Support for the analysis of Swift requires macOS. | |||
| .. [11] TypeScript analysis is performed by running the JavaScript extractor with TypeScript enabled. This is the default. | |||
| .. [12] Support for GitHub Actions is in public preview. | |||
There was a problem hiding this comment.
Note: This will need updating for GA, but I agree to merge this initial version of the docs ASAP and iterate.
There was a problem hiding this comment.
Yup - will drop this footnote for GA.
Next steps are to finish the corresponding docs build changes in the internal CodeQL monorepo, and then run a docs update in the internal |
Fixes warnings in Sphinx build.
docs/codeql/codeql-language-guides/codeql-library-for-actions.rst
Outdated
Show resolved
Hide resolved
| Customizing Library Models for GitHub Actions | ||
| ========================================= | ||
|
|
||
| .. include:: ../reusables/beta-note-customizing-library-models.rst |
There was a problem hiding this comment.
Wait...this is still in beta?
There was a problem hiding this comment.
Yeah we need to drop this separately.
|
|
||
| .. include:: ../reusables/beta-note-customizing-library-models.rst | ||
|
|
||
| GitHub Actions analysis can be customized by adding library models in data extension files. |
There was a problem hiding this comment.
Would it make sense to link to the main documentation page for data extensions? Or maybe to include links to some examples in the code.
There was a problem hiding this comment.
I think so but I would rather do it separately for all the languages.
|
Thanks for quick and helpful reviews! Comments are addressed, Sphinx build is passing, and I'll keep improving these over time. |
Include GitHub Actions (identifier
actions) everywhere we list supported languages, query packs, and library packs.Create basic structure for query and library documentation, although the full generated contents do not exist yet and will require a separate internal PR to generate.
Also add some missing language names in existing lists.
Reviewer note: This is the first language where the human-readable name and the extractor ID aren't alphabetically similar. I've placed the new entries in each list/table based on the order that seemed most intuitive for that list/table.