GitLab Docker执行器文档存歧义：$SSH_PRIVATE_KEY变量应配置什么？

你遇到的问题核心是对GitLab文件类型CI/CD变量的特性理解偏差。

正确的变量配置 #

$SSH_PRIVATE_KEY确实应该填入你的私钥内容（比如~/.ssh/id_ed25519里的全部文本），但必须确保变量的类型是File（不是默认的Variable类型）。

为什么之前的命令会失败？ #

GitLab的文件类型变量会自动将你输入的私钥内容写入一个临时文件，变量的值其实是这个临时文件的绝对路径，而不是直接返回私钥文本。如果你误把变量当成内容来用，chmod和ssh-add自然会报错——它们接收的是路径参数，不是纯文本。

正确的.gitlab-ci.yaml写法 #

直接使用变量指向的临时文件路径即可，不需要手动创建文件：

deploy:
  script:
    # 给临时私钥文件设置正确权限
    - chmod 400 "$SSH_PRIVATE_KEY"
    # 将私钥添加到ssh-agent
    - ssh-add "$SSH_PRIVATE_KEY"
    # 执行你的SSH操作，比如远程部署
    - ssh user@your-host "echo 'CI connected successfully'"

额外注意事项 #

• 不要将变量值设置为本地私钥的路径（比如~/.ssh/id_ed25519），CI环境里不存在这个路径
• 文件类型变量比普通变量更安全，因为私钥内容不会出现在CI日志中
• 建议使用无密码的私钥，避免CI过程中需要手动输入密码

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