This action reads the languages API for your repository and sets the CodeQL supported languages as the job matrix for your Actions run.
The default Actions workflow for CodeQL auto-populates the job matrix with your repo's supported CodeQL languages. However, as new code is added to a repository, that language matrix is not updated. You need to manually add those languages to the matrix definition to have CodeQL scan them.
This action reads the repository languages API and adds all supported languages to the job matrix. No additional configuration is required.
Learn more about the supported CodeQL languages here
Call this action before defining the CodeQL analyze job strategy, then set the matrix to the output from the action: ${{ fromJSON(needs.create-matrix.outputs.matrix) }}
Example
name: "CodeQL Auto Language"
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
schedule:
- cron: '17 19 * * 6'
jobs:
create-matrix:
runs-on: ubuntu-latest
permissions:
# required for all workflows
security-events: write
# required to fetch internal or private CodeQL packs
packages: read
# only required for workflows in private repositories
actions: read
contents: read
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Get languages from repo
id: set-matrix
uses: advanced-security/set-codeql-language-matrix@v1.6.0
with:
access-token: ${{ secrets.GITHUB_TOKEN }}
endpoint: ${{ github.event.repository.languages_url }}
analyze:
needs: create-matrix
if: ${{ needs.create-matrix.outputs.matrix != '[]' }}
name: Analyze
runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: false
matrix: ${{ fromJSON(needs.create-matrix.outputs.matrix) }}
steps:
- name: Checkout repository
uses: actions/checkout@v3
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
- if: matrix.build-mode == 'manual'
shell: bash
run: |
echo 'If you are using a "manual" build mode for one or more of the' \
'languages you are analyzing, replace this with the commands to build' \
'your code, for example:'
echo ' make bootstrap'
echo ' make release'
exit 1
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v3
with:
category: "/language:${{matrix.language}}"The samples above pin to a full release version (e.g. @v1.6.0) rather than a rolling major tag (e.g. @v1). This repository has immutable releases enabled, so a full version tag can't be moved or deleted once it's published, making it a secure alternative to pinning by commit SHA while remaining easy to read.
A workflow in this repository automatically opens a pull request to bump the version referenced in these samples whenever a new release is published.
It's possible you may choose to exclude specific languages from your CodeQL scans. In that case, use the exclude input.
Example:
create-matrix:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Get languages from repo
id: set-matrix
uses: advanced-security/set-codeql-language-matrix@v1.6.0
with:
access-token: ${{ secrets.GITHUB_TOKEN }}
endpoint: ${{ github.event.repository.languages_url }}
exclude: 'java, python'
By default, the action sets the build mode to:
nonefor most languages (python, javascript, ruby, rust, actions, etc.)manualfor languages that typically require custom build steps (go, swift, kotlin)
If you want to override this behavior and use manual build mode for specific languages, use the build-mode-manual-override input:
create-matrix:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Get languages from repo
id: set-matrix
uses: advanced-security/set-codeql-language-matrix@v1.6.0
with:
access-token: ${{ secrets.GITHUB_TOKEN }}
endpoint: ${{ github.event.repository.languages_url }}
build-mode-manual-override: 'java, csharp'By default, this action maps related languages to a single legacy CodeQL language name, for example both javascript and typescript map to javascript, both java and kotlin map to java, and both c and c++ map to cpp.
github/codeql-action also supports standard combined names for these same language groupings: javascript-typescript, java-kotlin, and c-cpp. The default GitHub-generated CodeQL workflow uses these combined names. If your workflow uses the legacy names (as this action does by default) while other workflows or the default setup use the combined names, CodeQL will treat them as different tools/configurations and show duplicate, differentiated entries (e.g. language:javascript and language:javascript-typescript) on the code scanning tools page.
Set the standard-language-names input to 'true' to have this action emit the standard combined names instead:
create-matrix:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- name: Get languages from repo
id: set-matrix
uses: advanced-security/set-codeql-language-matrix@v1.6.0
with:
access-token: ${{ secrets.GITHUB_TOKEN }}
endpoint: ${{ github.event.repository.languages_url }}
standard-language-names: 'true'This defaults to 'false' to preserve backward compatibility, since switching category names for an existing CodeQL setup starts a new analysis history for that language and disassociates previous findings until they age out.
The GitHub API for List repository languages does not by default include "YAML"/"GitHub Actions". This is particularly useful if your repository contains GitHub Actions workflows that you want to include in CodeQL analysis.
To add support for this to your repo, you must add a .gitattributes file with the following contents:
.github/workflows/*.yml linguist-detectable -linguist-vendored
.github/workflows/*.yaml linguist-detectable -linguist-vendored
These directives tell GitHub's linguist to detect YAML files in the .github/workflows/ directory as a language and not treat them as vendored code, making them visible in the repository languages API.
If you want to include Swift in your CodeQL analysis, you need to ensure that the action runs on a macOS runner. This is because Swift analysis with CodeQL requires a macOS environment. You can achieve this by making the runs-on field in your workflow conditional based on the language being analyzed.
Example:
analyze:
needs: create-matrix
if: ${{ needs.create-matrix.outputs.matrix != '[]' }}
name: Analyze
runs-on: ${{ matrix.language == 'swift' && 'macos-latest' || 'ubuntu-latest' }}
permissions:
actions: read
contents: read
security-events: writeIf you want to run all languages other than Swift on a specific group of runners, you can adjust the runs-on line in your workflow as shown in the following example:
runs-on: ${{ matrix.language == 'swift' && 'macos-latest' || fromJSON('{"group":"runner-group-name"}') }}This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.
Take a look at CODEOWNERS to identify the maintainers.
Contributions are welcome! If you have an idea for a new feature or improvement, please open an issue or submit a pull request. Maintainers should use the Contributing Guide to control version updates.
Got a question or issue? Open an issue in this repo and tag any of the folks in CODEOWNERS.