Why Use container: debian:13 in the Loong64 CI Workflow? / 为什么在 Loong64 CI 工作流中使用 container: debian:13？

[xuxiaowei-com-cn]

Discussion: Why Use container: debian:13 in the Loong64 CI Workflow? / 为什么在 Loong64 CI 工作流中使用 container: debian:13？

---

Background / 背景

Our CI workflow (.github/workflows) is configured as runs-on: ubuntu-latest + container: debian:13 — running a Debian 13 container on an Ubuntu host to build the LoongArch 64-bit version of Kubernetes. This post explains the rationale behind this choice.

我们的 CI 工作流（.github/workflows）配置为 runs-on: ubuntu-latest + container: debian:13，即在 Ubuntu 宿主机上运行 Debian 13 容器来编译 Kubernetes 的 LoongArch 64 位版本。本文将阐述这一选择的原因。

---

Motivation / 动机

Core Reason: Ubuntu Lacks the LoongArch Cross-Compilation Toolchain / 核心原因：Ubuntu 缺少 LoongArch 交叉编译工具链

In Ubuntu's official repositories, the gcc-loongarch64-linux-gnu and binutils-loongarch64-linux-gnu packages do not exist. Running builds directly on the Ubuntu host would make it impossible to install these essential cross-compilers via apt install.

Debian 13 (Trixie), on the other hand, has officially adopted LoongArch as a supported architecture, and its repositories natively include these toolchains. Verified results:

在 Ubuntu 的官方软件源中，不存在 gcc-loongarch64-linux-gnu 和 binutils-loongarch64-linux-gnu 这两个包。如果直接在 Ubuntu 宿主机上执行构建，将无法通过 apt install 安装这些必需的 LoongArch 64 位交叉编译器。

而 Debian 13 (Trixie) 已将 LoongArch 列为官方支持架构，其软件源原生包含这些工具链。经实测：

Environment / 环境	gcc-loongarch64-linux-gnu	binutils-loongarch64-linux-gnu
Ubuntu Oracular	❌ Sorry, your search gave no results	❌ Not available / 不存在
Debian 13 (Trixie)	✅ gcc-loongarch64-linux-gnu (4:14.2.0-1)	✅ Available / 存在

Additional Benefits / 其他优势

1. GitHub Actions Has No Debian Host Runner / GitHub Actions 不提供 Debian 宿主机 runner — The only managed runners are Ubuntu, Windows, and macOS. Using container: debian:13 is the only way to get a Debian environment on GitHub-hosted runners. / 官方托管 runner 只有 Ubuntu、Windows、macOS。使用 container: debian:13 是当前平台限制下获得 Debian 环境的最优解。

2. Debian Is More Active in Supporting Emerging Architectures / Debian 对新兴架构的支持更积极 — Debian 13 actively includes cross-compilation packages for architectures like loongarch64 and riscv64, while Ubuntu lags behind. / Debian 13 积极收录 loongarch64、riscv64 等架构的交叉编译包，Ubuntu 相对滞后。

3. Docker Installation Compatibility / Docker 安装流程兼容性 — The workflow uses Docker's official Debian repository (https://download.docker.com/linux/debian). Having the container OS match the repo distribution avoids configuration mismatches. / 工作流使用了 Docker 官方 Debian 仓库，容器 OS 与仓库发行版一致，避免配置不匹配。

4. Consistency and Reproducibility / 环境一致性与可重现性 — ubuntu-latest gets upgraded over time (e.g., 24.04 → 26.04). Pinning container: debian:13 ensures a deterministic build environment. / ubuntu-latest 会随时间升级，固定 container: debian:13 保证了构建环境的确定性。

5. Environment Isolation / 环境隔离 — The container's independent filesystem avoids conflicts with pre-installed host tools, and package operations won't pollute the host. / 容器的独立文件系统避免了与宿主机预装工具的冲突，安装/卸载操作不会污染宿主环境。

6. Portability Beyond GitHub CI / 可脱离 GitHub CI 运行 — debian:13 is a standard, publicly available Docker image. The exact same build environment can be reproduced outside GitHub Actions — on a local machine (docker run -it debian:13), on a self-hosted server, or on any other CI platform (GitLab CI, Jenkins, etc.). This avoids vendor lock-in and makes local debugging of CI failures straightforward. / debian:13 是一个标准的、公开可用的 Docker 镜像。完全相同的构建环境可以在 GitHub Actions 之外复现——在本地机器（docker run -it debian:13）、自托管服务器或任何其他 CI 平台（GitLab CI、Jenkins 等）上都能运行。这避免了供应商锁定，也使 CI 故障的本地调试变得简单直接。

---

Proposal / 提案

This document captures the rationale for the current approach for the team and contributors. Discussion points welcome:

• Are there alternative ways to achieve the same result on GitHub Actions?
• Migration plan when Debian 14 is released?
• Has a custom runner or alternative CI platform been considered?

本文档记录了当前的选择理由，供团队成员和贡献者参考。欢迎讨论：

• 是否有其他方式可以在 GitHub Actions 上实现同等效果？
• Debian 13 升级到 Debian 14 后的迁移计划？
• 是否有考虑使用自定义 runner 或其他 CI 平台？

---

References / 参考

• Debian LoongArch Port
• GitHub Actions Runner Images
• CI Workflow / CI 工作流: .github/workflows

[wojiushixiaobai]

在 Ubuntu 24.04 中可以使用 gcc-13-loongarch64-linux-gnu，从 Ubuntu 26.04 开始可以和其他架构一样直接使用 gcc-loongarch64-linux-gnu

      - name: Install packages
        run: |
          sudo apt-get update
          sudo apt-get install gcc-13-loongarch64-linux-gnu -y
          sudo update-alternatives \
            --install /usr/bin/loongarch64-linux-gnu-gcc loongarch64-linux-gnu-gcc /usr/bin/loongarch64-linux-gnu-gcc-13 100 \
            --slave /usr/bin/loongarch64-linux-gnu-gcc-ar loongarch64-linux-gnu-gcc-ar /usr/bin/loongarch64-linux-gnu-gcc-ar-13 \
            --slave /usr/bin/loongarch64-linux-gnu-gcc-nm loongarch64-linux-gnu-gcc-nm /usr/bin/loongarch64-linux-gnu-gcc-nm-13 \
            --slave /usr/bin/loongarch64-linux-gnu-gcc-ranlib loongarch64-linux-gnu-gcc-ranlib /usr/bin/loongarch64-linux-gnu-gcc-ranlib-13 \
            --slave /usr/bin/loongarch64-linux-gnu-gcov loongarch64-linux-gnu-gcov /usr/bin/loongarch64-linux-gnu-gcov-13
          sudo update-alternatives \
            --install /usr/bin/loongarch64-linux-gnu-cpp loongarch64-linux-gnu-cpp /usr/bin/loongarch64-linux-gnu-cpp-13 100

为什么选择 gcc-13-loongarch64-linux-gnu，其他架构安装 gcc-<arch>-linux-gnu 也是指向 gcc-13-<arch>-linux-gnu

[xuxiaowei-com-cn]

谢谢，后面我试一下