security-codeql.yml

# Copyright 2026 The ARCORIS Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"name": "CodeQL"

"on":
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "main"
  schedule:
    # Weekly scheduled scan.
    #
    # Keep at least one scheduled run even when normal PR traffic is low, so
    # CodeQL still revisits the repository against newer query packs and newer
    # vulnerability knowledge over time.
    - cron: "0 4 * * 1"
  workflow_dispatch:

permissions:
  # Checkout.
  contents: "read"

concurrency:
  # Avoid piling up multiple CodeQL runs for the same branch / PR revision.
  group: "codeql-${{ github.workflow }}-${{ github.ref }}"
  cancel-in-progress: true

jobs:
  analyze:
    name: "analyze (${{ matrix.language }})"
    runs-on: "ubuntu-latest"
    permissions:
      contents: "read"
      actions: "read"
      security-events: "write"
      pull-requests: "read"

    strategy:
      fail-fast: false
      matrix:
        include:
          # This repository is a Go library. Keeping the matrix explicit avoids
          # a generic multi-language workflow that obscures what is actually
          # scanned here.
          - language: "go"

    steps:
      - name: "Checkout repository"
        # actions/checkout v6
        uses: "actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd"
        with:
          persist-credentials: false

      # CodeQL initialization.
      #
      # Query choice:
      # - `security-extended` keeps the scan focused on security-relevant checks
      #   plus broader but still useful coverage beyond the narrowest default.
      # - `security-and-quality` could be used later, but for a small library
      #   this often creates more noise than signal during initial adoption.
      #
      # Build model:
      # - Go is a compiled language for CodeQL purposes.
      # - GitHub documents `autobuild` as a supported mode for Go.
      # - This repository is intentionally simple enough that autobuild is the
      #   right default until proven otherwise.
      - name: "Initialize CodeQL"
        # github/codeql-action/init v4
        uses: "github/codeql-action/init@95e58e9a2cdfd71adc6e0353d5c52f41a045d225"
        with:
          languages: "${{ matrix.language }}"
          build-mode: "autobuild"
          queries: "security-extended"

      # No explicit autobuild step is needed because `build-mode: autobuild`
      # delegates that responsibility to the CodeQL action itself.
      #
      # If analysis ever fails with an automatic-build error for Go, switch this
      # workflow to `build-mode: manual` and add explicit `go build` / `go test`
      # commands for the package set you want CodeQL to analyze.
      #
      # GitHub's compiled-language documentation explicitly recommends that path
      # when autobuild is not sufficient.

      - name: "Perform CodeQL analysis"
        # github/codeql-action/analyze v4
        uses: "github/codeql-action/analyze@95e58e9a2cdfd71adc6e0353d5c52f41a045d225"
        with:
          category: "/language:${{ matrix.language }}"