必须先完成指定版本安装、系统级服务配置与安全注册三步才能真正绑定到gitlab实例；需先确认uos为d系列（基于debian）或a系列（基于centos stream/rhel），再分别用apt或dnf安装gitlab runner，创建专用用户，执行sudo gitlab-runner register完成注册，并可选切换custom executor适配信创环境。
您需要在统信UOS上部署GitLab Runner以接入CI/CD流水线，但执行gitlab-runner register提示command not found，说明Runner既未安装也未注册，必须先完成指定版本安装、系统级服务配置与安全注册三步才能真正绑定到GitLab实例。
确认UOS系列并选择安装方式
统信UOS分D系列（基于Debian，如专业版23、个人版2024）和A系列（基于CentOS Stream/RHEL，如服务器版A23），包管理器不兼容，【绝不能在D系列上运行dnf命令，或在A系列上运行apt命令】。打开终端，先运行cat /etc/os-release | grep -E "(VERSION_CODENAME|ID_LIKE)"确认系统类型：若输出含ID_LIKE=debian则为D系列；若含ID_LIKE="centos rhel fedora"则为A系列。
D系列UOS安装指定版本GitLab Runner
方法一：APT源安装（推荐用于日常开发）
执行curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash→sudo apt update→sudo apt install gitlab-runner。该方式自动拉取最新稳定版，适合快速验证流程。
方法二：精确版本锁定安装（生产环境必需）
先查可用版本：apt-cache madison gitlab-runner→从列表中选一个如16.11.0→执行sudo apt install gitlab-runner=16.11.0-1。这一步防止自动升级引发CI脚本兼容性中断，【安装后立即执行sudo apt-mark hold gitlab-runner锁定版本】。
A系列UOS安装指定版本GitLab Runner
方法一：DNF源安装
运行curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash→sudo dnf makecache→sudo dnf install gitlab-runner。此方式依赖官方仓库元数据，安装路径统一为/usr/bin/gitlab-runner。
方法二：RPM包手动安装（离线或加固环境）
去GitLab Runner Releases页下载对应架构RPM包（如gitlab-runner-16.11.0-1.el8.x86_64.rpm）→执行sudo rpm -ivh gitlab-runner-16.11.0-1.el8.x86_64.rpm。注意：若提示failed dependencies，需先补全sudo dnf install systemd。
配置系统服务并启用Runner
第一步：创建专用运行用户sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash。这一步隔离权限，避免Runner以root身份执行作业带来安全风险。
第二步：注册Runner到GitLab实例
执行sudo gitlab-runner register，按提示依次输入：
• GitLab实例URL（如https://gitlab.example.com）
• Registration Token（从GitLab项目/群组Settings → CI/CD → Runners页面复制）
• Description（如uos-d23-arm64-runner）
• Tags（用英文逗号分隔，如build,python,arm64）
• Executor（选shell最简起步；若需信创适配，后续再切custom）
第三步：启动并设为开机自启sudo gitlab-runner start→sudo gitlab-runner status确认状态为running→sudo systemctl enable gitlab-runner。此时Runner已出现在GitLab Web界面的Active Runners列表中。
信创环境专用：切换Custom Executor
当目标环境禁用容器、要求国密算法或对接国产调度总线时，必须替换为Custom Executor：
① 停止当前服务：sudo gitlab-runner stop
② 编写三个脚本并赋予可执行权限：
• /opt/gitlab-runner/custom/prepare：校验CI_PROJECT_URL、调用国产Git客户端clone、加载BabaSSL库路径
• /opt/gitlab-runner/custom/run：流式读取.gitlab-ci.yml中的script字段，注入GCMODE=sm2等环境变量
• /opt/gitlab-runner/custom/cleanup：强制umount临时挂载点、用SM3计算workspace哈希写入审计日志
③ 修改/etc/gitlab-runner/config.toml：将executor = "shell"改为executor = "custom"，并在[runners.custom]段落下指定prepare_exec = "/opt/gitlab-runner/custom/prepare"等三项路径
④ 重启服务：sudo gitlab-runner start。此时Runner将完全绕过Docker依赖，所有作业生命周期由您控制的脚本接管。
