codeql-action/pr-checks/sync.ts at default-setup-testing · github/codeql-action

executable file
849 lines (751 loc) · 24.6 KB
#!/usr/bin/env npx tsx
import * as fs from "fs";
import * as path from "path";
import * as yaml from "yaml";
import { BuiltInLanguage } from "../src/languages";
 * Returns a `uses` value for `action` pinned to a commit SHA, with the
 * human-readable version recorded in a trailing comment.
function pinnedUses(action: string, sha: string, version: string): yaml.Scalar {
  const node = new yaml.Scalar(`${action}@${sha}`);
  node.comment = ` ${version}`;
  return node;
/** Known workflow input names. */
enum KnownInputName {
  GoVersion = "go-version",
  JavaVersion = "java-version",
  PythonVersion = "python-version",
  DotnetVersion = "dotnet-version",
 * Represents workflow input definitions.
interface WorkflowInput {
  type: string;
  description: string;
  required: boolean;
  default: string;
/** A partial mapping from known input names to input definitions. */
type WorkflowInputs = Partial<Record<KnownInputName, WorkflowInput>>;
/** An operating system identifier. */
type OperatingSystemIdentifier = "ubuntu" | "macos" | "windows";
 * Represents an operating system matrix entry for a generated PR check workflow.
 * Either a string containing the OS identifier or an object containing the OS identifier and an
 * optional runner image label.
type OperatingSystem =
  | OperatingSystemIdentifier
      /** OS identifier. */
      os: OperatingSystemIdentifier;
      /** Optional runner image label. */
      "runner-image"?: string;
       * Optional CodeQL versions to run on this entry. If specified, this entry runs only these
       * versions. A sibling entry for the same OS that omits `codeql-versions` runs all versions
       * not claimed by any sibling entry. This allows pinning specific CodeQL versions to a
       * particular runner image while letting the remaining versions default to another.
      "codeql-versions"?: string[];
 * Represents PR check specifications.
interface Specification extends JobSpecification {
  /** Workflow-level input definitions forwarded to `workflow_dispatch`/`workflow_call`. */
  inputs?: Record<string, WorkflowInput>;
  /** CodeQL bundle versions to test against. Defaults to `DEFAULT_TEST_VERSIONS`. */
  versions?: string[];
  /** Operating system prefixes, either as strings or with explicit runner image labels. */
  operatingSystems?: OperatingSystem[];
  /** Per-OS version overrides. If specified for an OS, only those versions are tested on that OS. */
  osCodeQlVersions?: Record<string, string[]>;
  /** Whether to use the all-platform CodeQL bundle. */
  useAllPlatformBundle?: string;
  /** Values for the `analysis-kinds` matrix dimension. */
  analysisKinds?: string[];
  /** Container image configuration for the job. */
  container?: any;
  /** Service containers for the job. */
  services?: any;
  /** Additional jobs to run after the main PR check job. */
  validationJobs?: Record<string, JobSpecification>;
  /** If set, this check is part of a named collection that gets its own caller workflow. */
  collection?: string;
/** Minimal type to represent steps in Actions workflows. */
interface Step {
  name?: string;
  [other: string]: any;
/** Represents job specifications. */
interface JobSpecification {
  /** The display name for the check. */
  name: string;
  /** Custom permissions override for the job. */
  permissions?: Record<string, string>;
  /** Extra environment variables for the job. */
  env?: Record<string, any>;
  /** The workflow steps specific to this check. */
  steps: Step[];
  installNode?: boolean;
  installGo?: boolean;
  installJava?: boolean;
  installPython?: boolean;
  installDotNet?: boolean;
  installYq?: boolean;
/** Describes language/framework-specific steps and inputs. */
interface LanguageSetup {
  specProperty: keyof JobSpecification;
  /** The names of the known inputs which are required for this setup step. */
  inputs?: KnownInputName[];
  steps: Step[];
/** Describes partial mappings from built-in languages to their specific setup information. */
type LanguageSetups = Partial<Record<BuiltInLanguage, LanguageSetup>>;
// The default set of CodeQL Bundle versions to use for the PR checks.
const defaultTestVersions = [
  // The oldest supported CodeQL version. If bumping, update `CODEQL_MINIMUM_VERSION` in `codeql.ts`
  "stable-v2.19.4",
  // The last CodeQL release in the 2.20 series.
  "stable-v2.20.7",
  // The last CodeQL release in the 2.21 series.
  "stable-v2.21.4",
  // The last CodeQL release in the 2.22 series.
  "stable-v2.22.4",
  // The last CodeQL release in the 2.23 series.
  "stable-v2.23.9",
  // The last CodeQL release in the 2.24 series.
  "stable-v2.24.3",
  // The default version of CodeQL for Dotcom, as determined by feature flags.
  "default",
  // The version of CodeQL shipped with the Action in `defaults.json`. During the release process
  // for a new CodeQL release, there will be a period of time during which this will be newer than
  // the default version on Dotcom.
  "linked",
  // A nightly build directly from the our private repo, built in the last 24 hours.
  "nightly-latest",
/** The default versions we use for languages / frameworks, if not specified as a workflow input. */
const defaultLanguageVersions = {
  javascript: "20.x",
  go: ">=1.21.0",
  java: "17",
  python: "3.13",
  csharp: "9.x",
} as const satisfies Partial<Record<BuiltInLanguage, string>>;
/** A mapping from known input names to their specifications. */
const inputSpecs: WorkflowInputs = {
  [KnownInputName.GoVersion]: {
    type: "string",
    description: "The version of Go to install",
    required: false,
    default: defaultLanguageVersions.go,
  [KnownInputName.JavaVersion]: {
    type: "string",
    description: "The version of Java to install",
    required: false,
    default: defaultLanguageVersions.java,
  [KnownInputName.PythonVersion]: {
    type: "string",
    description: "The version of Python to install",
    required: false,
    default: defaultLanguageVersions.python,
  [KnownInputName.DotnetVersion]: {
    type: "string",
    description: "The version of .NET to install",
    required: false,
    default: defaultLanguageVersions.csharp,
/** Obtains a `WorkflowInputs` object for all the inputs given by `requiredInputs`. */
function getSetupInputs(requiredInputs: Set<KnownInputName>): WorkflowInputs {
  const inputs: WorkflowInputs = {};
  // Copy the input specifications for the requested inputs into the output.
  for (const requiredInput of requiredInputs) {
    inputs[requiredInput] = inputSpecs[requiredInput];
  return inputs;
/** A partial mapping from known languages to their specific setup information. */
const languageSetups: LanguageSetups = {
  javascript: {
    specProperty: "installNode",
    steps: [
        name: "Install Node.js",
        uses: pinnedUses(
          "actions/setup-node",
          "48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e",
          "v6.4.0",
        with: {
          "node-version": defaultLanguageVersions.javascript,
          cache: "npm",
        name: "Install dependencies",
        run: "npm ci",
    specProperty: "installGo",
    inputs: [KnownInputName.GoVersion],
    steps: [
        name: "Install Go",
        uses: pinnedUses(
          "actions/setup-go",
          "4a3601121dd01d1626a1e23e37211e3254c1c06c",
          "v6.4.0",
        with: {
          "go-version": `\${{ inputs.go-version || '${defaultLanguageVersions.go}' }}`,
          // to avoid potentially misleading autobuilder results where we expect it to download
          // dependencies successfully, but they actually come from a warm cache
          cache: false,
    specProperty: "installJava",
    inputs: [KnownInputName.JavaVersion],
    steps: [
        name: "Install Java",
        uses: pinnedUses(
          "actions/setup-java",
          "ad2b38190b15e4d6bdf0c97fb4fca8412226d287",
          "v5.3.0",
        with: {
          "java-version": `\${{ inputs.java-version || '${defaultLanguageVersions.java}' }}`,
          distribution: "temurin",
  python: {
    specProperty: "installPython",
    inputs: [KnownInputName.PythonVersion],
    steps: [
        name: "Install Python",
        uses: pinnedUses(
          "actions/setup-python",
          "a309ff8b426b58ec0e2a45f0f869d46889d02405",
          "v6.2.0",
        with: {
          "python-version": `\${{ inputs.python-version || '${defaultLanguageVersions.python}' }}`,
  csharp: {
    specProperty: "installDotNet",
    inputs: [KnownInputName.DotnetVersion],
    steps: [
        name: "Install .NET",
        uses: pinnedUses(
          "actions/setup-dotnet",
          "9a946fdbd5fb07b82b2f5a4466058b876ab72bb2",
          "v5.3.0",
        with: {
          "dotnet-version": `\${{ inputs.dotnet-version || '${defaultLanguageVersions.csharp}' }}`,
// This is essentially an arbitrary version of `yq`, which happened to be the one that
// `choco` fetched when we moved away from using that here.
// See https://github.com/github/codeql-action/pull/3423
const YQ_VERSION = "v4.50.1";
const THIS_DIR = __dirname;
const CHECKS_DIR = path.join(THIS_DIR, "checks");
const OUTPUT_DIR = path.join(THIS_DIR, "..", ".github", "workflows");
 * Loads and parses a YAML file.
function loadYaml(filePath: string): yaml.Document {
  const content = fs.readFileSync(filePath, "utf8");
  return yaml.parseDocument(content);
/** Computes the union of all given `sets`. */
function unionAll<T>(sets: Array<Set<T>>): Set<T> {
  return sets.reduce((prev, cur) => prev.union(cur), new Set<T>());
 * Serialize a value to YAML and write it to a file, prepended with the
 * standard header comment.
function writeYaml(filePath: string, workflow: any): void {
  const header = `# Warning: This file is generated automatically, and should not be modified.
# Instead, please modify the template in the pr-checks directory and run:
#     pr-checks/sync.sh
# to regenerate this file.
  const workflowDoc = new yaml.Document(workflow, {
    aliasDuplicateObjects: false,
  const yamlStr = yaml.stringify(workflowDoc, {
    aliasDuplicateObjects: false,
    singleQuote: true,
    lineWidth: 0,
  fs.writeFileSync(filePath, stripTrailingWhitespace(header + yamlStr), "utf8");
 * Strip trailing whitespace from each line.
function stripTrailingWhitespace(content: string): string {
  return content
    .split("\n")
    .map((line) => line.trimEnd())
    .join("\n");
/** Generates the matrix for a job. */
function generateJobMatrix(
  checkSpecification: Specification,
): Array<Record<string, any>> {
  let matrix: Array<Record<string, any>> = [];
  const operatingSystems = checkSpecification.operatingSystems ?? ["ubuntu"];
  // For each OS, collect the CodeQL versions explicitly claimed by entries that specify
  // `codeql-versions`. A sibling entry for the same OS that omits `codeql-versions` runs all
  // versions not in this set.
  const claimedVersionsByOs = new Map<string, Set<string>>();
  for (const operatingSystemConfig of operatingSystems) {
    if (typeof operatingSystemConfig === "string") {
      continue;
    const entryVersions = operatingSystemConfig["codeql-versions"];
    if (!entryVersions) {
      continue;
    const claimed =
      claimedVersionsByOs.get(operatingSystemConfig.os) ?? new Set<string>();
    for (const entryVersion of entryVersions) {
      claimed.add(entryVersion);
    claimedVersionsByOs.set(operatingSystemConfig.os, claimed);
  for (const version of checkSpecification.versions ?? defaultTestVersions) {
    if (version === "latest") {
      throw new Error(
        `Did not recognise "version: ${version}". Did you mean "version: linked"?`,
    const defaultRunnerImages = [
      "ubuntu-latest",
      "macos-latest",
      "windows-latest",
    for (const operatingSystemConfig of operatingSystems) {
      const operatingSystem =
        typeof operatingSystemConfig === "string"
          ? operatingSystemConfig
          : operatingSystemConfig.os;
      // If osCodeQlVersions is set for this OS, only include the specified CodeQL versions.
      const allowedVersions =
        checkSpecification.osCodeQlVersions?.[operatingSystem];
      if (allowedVersions && !allowedVersions.includes(version)) {
        continue;
      // An entry that specifies `codeql-versions` runs only those versions. A sibling entry for
      // the same OS that omits `codeql-versions` runs all versions not claimed by its siblings.
      const entryVersions =
        typeof operatingSystemConfig === "string"
          ? undefined
          : operatingSystemConfig["codeql-versions"];
      const runsThisVersion = entryVersions
        ? entryVersions.includes(version)
        : !claimedVersionsByOs.get(operatingSystem)?.has(version);
      if (!runsThisVersion) {
        continue;
      const runnerImagesForOs =
        typeof operatingSystemConfig === "string" ||
        operatingSystemConfig["runner-image"] === undefined
          ? defaultRunnerImages.filter((image) =>
              image.startsWith(operatingSystem),
          : [operatingSystemConfig["runner-image"]];
      for (const runnerImage of runnerImagesForOs) {
        matrix.push({
          os: runnerImage,
          version,
        });
  if (checkSpecification.analysisKinds) {
    const newMatrix: Array<Record<string, any>> = [];
    for (const matrixInclude of matrix) {
      for (const analysisKind of checkSpecification.analysisKinds) {
        newMatrix.push({
          ...matrixInclude,
          "analysis-kinds": analysisKind,
        });
    matrix = newMatrix;
  return matrix;
 * Retrieves setup steps and additional input definitions based on specific languages or frameworks
 * that are requested by the `checkSpecification`.
 * @returns An object containing setup steps and required input names.
function getSetupSteps(checkSpecification: JobSpecification): {
  inputs: Set<KnownInputName>;
  steps: Step[];
  const inputs: Array<Set<KnownInputName>> = [];
  const steps: Step[] = [];
  for (const language of Object.values(BuiltInLanguage).sort()) {
    const setupSpec = languageSetups[language];
      setupSpec === undefined ||
      checkSpecification[setupSpec.specProperty] !== true
      continue;
    steps.push(...setupSpec.steps);
    inputs.push(new Set(setupSpec.inputs));
  const installYq = checkSpecification.installYq;
  if (installYq) {
    steps.push({
      name: "Install yq",
      if: "runner.os == 'Windows'",
      env: {
        YQ_PATH: "${{ runner.temp }}/yq",
        YQ_VERSION,
        'gh release download --repo mikefarah/yq --pattern "yq_windows_amd64.exe" "$YQ_VERSION" -O "$YQ_PATH/yq.exe"\n' +
        'echo "$YQ_PATH" >> "$GITHUB_PATH"',
  return { inputs: unionAll(inputs), steps };
 * Generates an Actions job from the `checkSpecification`.
 * @param specDocument
 * The raw YAML document of the PR check specification.
 * Used to extract `jobs` without losing the original formatting.
 * @param checkSpecification The PR check specification.
 * @returns The job and additional workflow inputs.
function generateJob(
  specDocument: yaml.Document,
  checkSpecification: Specification,
  const matrix: Array<Record<string, any>> =
    generateJobMatrix(checkSpecification);
  const useAllPlatformBundle = checkSpecification.useAllPlatformBundle
    ? checkSpecification.useAllPlatformBundle
    : "false";
  // Determine which languages or frameworks have to be installed.
  const setupInfo = getSetupSteps(checkSpecification);
  const workflowInputs = setupInfo.inputs;
  // Construct the workflow steps needed for this check.
  const steps: Step[] = [
      name: "Check out repository",
      uses: pinnedUses(
        "actions/checkout",
        "df4cb1c069e1874edd31b4311f1884172cec0e10",
        "v6.0.3",
    ...setupInfo.steps,
      name: "Prepare test",
      id: "prepare-test",
      uses: "./.github/actions/prepare-test",
      with: {
        version: "${{ matrix.version }}",
        "use-all-platform-bundle": useAllPlatformBundle,
        // If the action is being run from a container, then do not setup kotlin.
        // This is because the kotlin binaries cannot be downloaded from the container.
        "setup-kotlin": "container" in checkSpecification ? "false" : "true",
  // Extract the sequence of steps from the YAML document to persist as much formatting as possible.
  const specSteps = specDocument.get("steps") as yaml.YAMLSeq;
  // A handful of workflow specifications use double quotes for values, while we generally use single quotes.
  // This replaces double quotes with single quotes for consistency.
  yaml.visit(specSteps, {
    Scalar(_key, node) {
      if (node.type === "QUOTE_DOUBLE") {
        node.type = "QUOTE_SINGLE";
  // Add the generated steps in front of the ones from the specification.
  specSteps.items.unshift(...steps);
  const checkJob: Record<string, any> = {
    strategy: {
      "fail-fast": false,
      matrix: {
        include: matrix,
    name: checkSpecification.name,
    if: "github.triggering_actor != 'dependabot[bot]'",
    permissions: {
      contents: "read",
      "security-events": "read",
    "timeout-minutes": 45,
    "runs-on": "${{ matrix.os }}",
    steps: specSteps,
  if (checkSpecification.permissions) {
    checkJob.permissions = checkSpecification.permissions;
  for (const key of ["env", "container", "services"] as const) {
    if (checkSpecification[key] !== undefined) {
      checkJob[key] = checkSpecification[key];
  checkJob.env = checkJob.env ?? {};
  if (!("CODEQL_ACTION_TEST_MODE" in checkJob.env)) {
    checkJob.env.CODEQL_ACTION_TEST_MODE = true;
  return { checkJob, workflowInputs };
/** Generates a validation job. */
function generateValidationJob(
  specDocument: yaml.Document,
  jobSpecification: JobSpecification,
  checkName: string,
  name: string,
  // Determine which languages or frameworks have to be installed.
  const { inputs, steps } = getSetupSteps(jobSpecification);
  // Extract the sequence of steps from the YAML document to persist as much formatting as possible.
  const specSteps = specDocument.getIn([
    "validationJobs",
    "steps",
  ]) as yaml.YAMLSeq;
  // Add the generated steps in front of the ones from the specification.
  specSteps.items.unshift(...steps);
  const validationJob: Record<string, any> = {
    name: jobSpecification.name,
    if: "github.triggering_actor != 'dependabot[bot]'",
    needs: [checkName],
    permissions: {
      contents: "read",
      "security-events": "read",
    "timeout-minutes": 5,
    "runs-on": "ubuntu-slim",
    steps: specSteps,
  if (jobSpecification.permissions) {
    validationJob.permissions = jobSpecification.permissions;
  for (const key of ["env"] as const) {
    if (jobSpecification[key] !== undefined) {
      validationJob[key] = jobSpecification[key];
  validationJob.env = validationJob.env ?? {};
  if (!("CODEQL_ACTION_TEST_MODE" in validationJob.env)) {
    validationJob.env.CODEQL_ACTION_TEST_MODE = true;
  return { validationJob, inputs };
/** Generates additional jobs that run after the main check job, based on the `validationJobs` property. */
function generateValidationJobs(
  specDocument: yaml.Document,
  checkSpecification: Specification,
  checkName: string,
  validationJobs: Record<string, any>;
  workflowInputs: Set<KnownInputName>;
  if (checkSpecification.validationJobs === undefined) {
    return { validationJobs: {}, workflowInputs: new Set() };
  const validationJobs: Record<string, any> = {};
  const workflowInputs: Array<Set<KnownInputName>> = [];
  for (const [jobName, jobSpec] of Object.entries(
    checkSpecification.validationJobs,
    if (checkName === jobName) {
      throw new Error(
        `Validation job '${jobName}' cannot have the same name as the main job.`,
    const { validationJob, inputs } = generateValidationJob(
      specDocument,
      jobSpec,
      checkName,
      jobName,
    validationJobs[jobName] = validationJob;
    workflowInputs.push(inputs);
    validationJobs,
    workflowInputs: unionAll(workflowInputs),
 * Main entry point for the sync script.
function main(): void {
  // Ensure the output directory exists.
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
  // Discover and sort all check specification files.
  const checkFiles = fs
    .readdirSync(CHECKS_DIR)
    .filter((f) => f.endsWith(".yml"))
    .sort()
    .map((f) => path.join(CHECKS_DIR, f));
  console.log(`Found ${checkFiles.length} check specification(s).`);
  const collections: Record<
    string,
    Array<{
      specification: Specification;
      checkName: string;
      inputs: Record<string, WorkflowInput>;
  for (const file of checkFiles) {
    const checkName = path.basename(file, ".yml");
    const specDocument = loadYaml(file);
    const checkSpecification = specDocument.toJS() as Specification;
    console.log(`Processing: ${checkName} — "${checkSpecification.name}"`);
    const { checkJob, workflowInputs } = generateJob(
      specDocument,
      checkSpecification,
    const { validationJobs, workflowInputs: validationJobInputs } =
      generateValidationJobs(specDocument, checkSpecification, checkName);
    const combinedInputs = getSetupInputs(
      workflowInputs.union(validationJobInputs),
    // If this check belongs to a named collection, record it.
    if (checkSpecification.collection) {
      const collectionName = checkSpecification.collection;
      if (!collections[collectionName]) {
        collections[collectionName] = [];
      collections[collectionName].push({
        specification: checkSpecification,
        checkName,
        inputs: combinedInputs,
    let extraGroupName = "";
    for (const inputName of Object.keys(combinedInputs)) {
      extraGroupName += `-\${{inputs.${inputName}}}`;
    const cron = new yaml.Scalar("0 5 * * *");
    cron.type = yaml.Scalar.QUOTE_SINGLE;
    const workflow = {
      name: `PR Check - ${checkSpecification.name}`,
      env: {
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}",
        GO111MODULE: "auto",
      on: {
        push: {
          branches: ["main", "releases/v*"],
        pull_request: {},
        merge_group: {
          types: ["checks_requested"],
        schedule: [{ cron }],
        workflow_dispatch: {
          inputs: combinedInputs,
        workflow_call: {
          inputs: combinedInputs,
      defaults: {
        run: {
          shell: "bash",
      concurrency: {
        "cancel-in-progress":
          "${{ github.event_name == 'pull_request' || false }}",
        group: `${checkName}-\${{github.ref}}${extraGroupName}`,
      jobs: {
        [checkName]: checkJob,
        ...validationJobs,
    const outputPath = path.join(OUTPUT_DIR, `__${checkName}.yml`);
    writeYaml(outputPath, workflow);
  // Write workflow files for collections.
  for (const collectionName of Object.keys(collections)) {
    const jobs: Record<string, any> = {};
    let combinedInputs: Record<string, WorkflowInput> = {};
    for (const check of collections[collectionName]) {
      const { checkName, specification, inputs: checkInputs } = check;
      const checkWith: Record<string, string> = {};
      combinedInputs = { ...combinedInputs, ...checkInputs };
      for (const inputName of Object.keys(checkInputs)) {
        checkWith[inputName] = `\${{ inputs.${inputName} }}`;
      jobs[checkName] = {
        name: specification.name,
        permissions: {
          contents: "read",
          "security-events": "read",
        uses: `./.github/workflows/__${checkName}.yml`,
        with: checkWith,
    const collectionWorkflow = {
      name: `Manual Check - ${collectionName}`,
      env: {
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}",
        GO111MODULE: "auto",
      on: {
        workflow_dispatch: {
          inputs: combinedInputs,
      jobs,
    const outputPath = path.join(OUTPUT_DIR, `__${collectionName}.yml`);
    writeYaml(outputPath, collectionWorkflow);
  console.log(
    `\nDone. Wrote ${checkFiles.length} workflow file(s) to ${OUTPUT_DIR}`,
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

sync.ts

Latest commit

History

sync.ts

File metadata and controls
