Gitlab CI/CD Shell执行器无法读取本地文件/运行Python脚本求助

背景 #

从事嵌入式软件项目（为不同MCU编程），近期学习GitLab CI/CD优化开发流程，希望发布前自动运行硬件级测试（如切换GPIO引脚、发送串口指令等），已开发可通过命令行运行的Python工具。使用树莓派4搭建GitLab Runner，配置为Shell执行器。

Runner配置 #

concurrent = 1
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "Raspberry PI TestTool runner"
  url = "https://xxx-gitlab=xxxxxxx.lt/"
  id = 12
  token = "XXXXXXXXXXXXXXXX"
  token_obtained_at = 2024-01-02T07:51:55Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "shell"
  shell = "bash"

流水线配置 #

# List of stages for jobs, and their order of execution
stages:
  - test

test-job1:
  stage: test
  script:
    - echo "This job tests something"
    - ls -l
    - cd ~
    - ls -l
    - cat Desktop/test.txt

本地执行情况 #

在树莓派本地终端以lukas用户执行正常：

lukas@raspberrypi:/etc $ cd ~
lukas@raspberrypi:~ $ cat Desktop/test.txt
hello123

CI执行报错 #

流水线运行时找不到目标文件，报错日志如下：

Running with gitlab-runner 16.7.0 (102c81ba)
  on Raspberry PI TestTool runner htiDWYJ2, system ID: s_0ae6b2582ae5
Preparing the "shell" executor
00:00
Using Shell (bash) executor...
Preparing environment
00:01
Running on raspberrypi...
Getting source from Git repository
00:01
Fetching changes with git depth set to 20...
Reinitialized existing Git repository in /home/gitlab-runner/builds/htiDWYJ2/0/embeded-programmers/gitchangelog-test/.git/
Checking out 7f12264a as detached HEAD (ref is main)...
Skipping Git submodules setup
Executing "step_script" stage of the job script
00:00
$ echo "This job tests something"
This job tests something
$ ls -l
total 120
drwxr-xr-x 8 gitlab-runner gitlab-runner  4096 Jan  2 08:13 build
-rw-r--r-- 1 gitlab-runner gitlab-runner   235 Jan  2 08:13 CMakeLists.txt
drwxr-xr-x 2 gitlab-runner gitlab-runner  4096 Jan  2 08:22 main
-rw-r--r-- 1 gitlab-runner gitlab-runner  2921 Jan  2 08:13 Readme.md
-rw-r--r-- 1 gitlab-runner gitlab-runner     2 Jan  2 08:13 release_notes.md
-rw-r--r-- 1 gitlab-runner gitlab-runner 48870 Jan  2 08:13 sdkconfig
-rw-r--r-- 1 gitlab-runner gitlab-runner     0 Jan  2 08:13 sdkconfig.ci
-rw-r--r-- 1 gitlab-runner gitlab-runner 48870 Jan  2 08:13 sdkconfig.old
-rw-r--r-- 1 gitlab-runner gitlab-runner  1325 Jan  2 08:13 working_ci_scripts.txt
$ cd ~
$ ls -l
total 4
drwxr-xr-x 3 gitlab-runner gitlab-runner 4096 Jan  2 08:13 builds
$ cat Desktop/test.txt
cat: Desktop/test.txt: No such file or directory
Cleaning up project directory and file based variables
00:00
ERROR: Job failed: exit status 1

疑问 #

1. 是否误解了Shell执行器的工作机制？
2. Shell执行器是否无法访问Runner上的所有文件？
3. 该Runner无需克隆Git仓库，只需执行本地脚本、读取本地文件，若Shell执行器无法实现，有何替代方案？

核心原因 #

Shell执行器的作业是通过gitlab-runner系统用户运行的，而非你本地登录的lukas用户。从报错日志可看到，作业运行时的~指向/home/gitlab-runner/，而你本地操作的~是/home/lukas/，因此找不到lukas用户Desktop下的文件。另外，默认情况下Shell执行器会自动克隆代码仓库到gitlab-runner用户的build目录下。

解决方法 #

方法1：调整文件路径与权限 #

• 将测试文件/工具移动到gitlab-runner用户可访问的路径，比如/home/gitlab-runner/Desktop/test.txt；
• 或直接使用绝对路径访问/home/lukas/Desktop/test.txt，需确保gitlab-runner用户有读取权限，可执行sudo chmod o+r /home/lukas/Desktop/test.txt（如果是目录，还需调整目录权限）。

方法2：跳过代码克隆 #

如果不需要克隆仓库，可在流水线配置中添加git-strategy: none，Runner将不会拉取代码，直接执行指定脚本：

test-job1:
  stage: test
  git-strategy: none
  script:
    - echo "跳过代码克隆"
    - cat /home/lukas/Desktop/test.txt  # 使用绝对路径访问目标文件

方法3：修改Runner运行用户（不推荐） #

修改GitLab Runner的配置，让它以lukas用户运行：

1. 编辑Runner配置文件（通常在/etc/gitlab-runner/config.toml），在[[runners]]段添加user = "lukas"：

[[runners]]
  # 其他配置保持不变
  user = "lukas"

2. 重启GitLab Runner服务：sudo gitlab-runner restart

注意：此方法可能带来权限安全风险，gitlab-runner用户原本是受限的系统用户，切换到普通用户后会获得更高权限。

方法4：封装自定义脚本 #

把硬件测试的Python工具和相关逻辑封装成脚本，放在gitlab-runner用户可访问的路径（如/usr/local/bin/），然后在流水线脚本中直接调用该脚本的绝对路径。

内容的提问来源于stack exchange，提问作者TheBestPlayer