GitHub CodeQL 支持 Linux ARM64 后如何调整扫描矩阵

如果你的工作流已经使用 GitHub CodeQL 做代码扫描，现在不需要把 Linux ARM64 当成“只能交叉编译、不能原生扫描”的特殊平台了。GitHub 在 2026 年 9 月发布的 CodeQL 2.27.0 已提供 Linux ARM64 的 CodeQL CLI 和 bundle。迁移时最稳妥的做法不是把原来的 x64 任务直接替换掉，而是把 runner 架构显式放进矩阵，先并行保留 x64，再让 ARM64 任务跑一段时间。

官方地址：https://github.com/github/codeql-action/

先把扫描矩阵拆成平台与分析器两层

这次变化的核心是 CodeQL 2.27.0 可以在 Linux ARM64 上原生运行，但它不会自动把你的工作流改成 ARM64。runs-on 决定作业落在哪种 runner，CodeQL Action 再负责取得适配的 bundle。GitHub Runner Images 的可用标签中，Ubuntu 24.04 ARM64 对应 ubuntu-24.04-arm；普通 Ubuntu 24.04 仍然是 x64。

因此先检查三处：工作流引用的 github/codeql-action 版本是否包含 2.27.0 之后的 bundle，runner 标签是否确实是 ARM64，以及项目的构建脚本有没有固定下载 x64 二进制。只改第一处，作业仍可能跑在 x64；只改第二处，旧 bundle 或旧缓存又可能在 ARM 上出现格式错误。

用 matrix 新增 ARM64，而不是覆盖原有基线

可以先把平台作为单独变量，让同一份初始化和分析步骤复用。下面的写法只展示矩阵改造重点；实际项目仍需按语言选择自动构建或手动构建模式。

name: codeql

on:
  push:
    branches: [main]
  pull_request:

jobs:
  analyze:
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: x64
            runner: ubuntu-24.04
          - arch: arm64
            runner: ubuntu-24.04-arm
    runs-on: ${{ matrix.runner }}
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - name: Print runner architecture
        run: |
          # 先记录平台，排查“标签改了但任务仍跑错架构”的问题
          echo "matrix_arch=${{ matrix.arch }}"
          echo "runner_arch=${{ runner.arch }}"
          uname -m
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: javascript
      - name: Build
        run: npm ci && npm run build
      - name: Analyze
        uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.arch }}"

这里的 category 让结果在代码扫描页面按架构区分，便于观察 ARM64 是否出现只在本平台暴露的构建或依赖问题。它不是“强制 CodeQL 下载 ARM64 bundle”的开关；真正的适配由 Action 和运行环境共同完成。

ARM64 迁移最容易卡在构建步骤

如果使用解释型语言或纯源码查询，迁移通常较轻；如果项目会编译 C/C++、Rust、Java/Kotlin 原生依赖，或构建脚本下载预编译工具，就要把构建阶段单独看待。依赖管理器可能仍在拉取 x86_64 包，容器基础镜像也可能只有 amd64 manifest。CodeQL 扫描启动成功，并不代表构建产物已经按 ARM64 正确生成。

CodeQL 官方文档还提醒，CLI 对基于 musl 的 Alpine Linux 并不兼容。不要因为 runner 是 ARM64，就顺手把执行环境切成 Alpine；先保证 glibc 和 bundle 的平台条件满足，再处理项目本身的容器差异。

先灰度，再决定 ARM64 是否阻断合并

第一轮建议让 ARM64 任务保持非必需检查，连续跑几次 push 和 pull request，记录失败属于 runner、依赖、构建还是 CodeQL 本身。若两种架构的扫描结果都能上传，再把 ARM64 加入保护分支规则。对需要发布多架构镜像的项目，保留两条扫描结果反而更有价值：x64 验证历史基线，ARM64 验证实际交付平台。

反向验证时至少看三条证据：作业日志中的 runner 架构、构建产物或容器的目标架构、CodeQL analyze 步骤是否完整结束并上传结果。只看到“Initialize CodeQL succeeded”不能证明整个 ARM64 迁移完成。

相关问题

只把 runs-on 改成 ubuntu-24.04-arm 可以吗？

不建议。还要确认 Action 使用的 bundle、构建依赖和缓存都支持 ARM64；否则最常见的结果是扫描器能启动，但构建阶段报 exec format error。

要不要删除原来的 x64 CodeQL 任务？

不要急着删。并行保留 x64 能提供基线和回滚路径，等 ARM64 的构建和结果上传稳定后，再按成本决定是否调整频率。

如何确认自己真的跑在 ARM64？

在作业中同时打印 runner.arch 和 uname -m，再结合构建工具输出判断。标签名称本身不是运行时证据。

官方资料

• GitHub Changelog：CodeQL 2.27.0 adds support for Linux ARM64
• GitHub Docs：Setting up the CodeQL CLI
• GitHub Actions Runner Images：可用镜像与 YAML 标签