存储在Bitbucket变量中的SSH Key格式无效问题排查

核心原因 #

Bitbucket环境变量在存储和传递过程中会自动处理换行符（比如将换行转为空格或直接丢失），破坏了SSH密钥的原始格式；而本地构建时通过$(cat)命令完整保留了密钥的换行结构，因此不会出现格式错误。

解决方案 #

方案1：Base64编码传递（最直接） #

1. 本地编码SSH密钥
   在本地终端执行命令，将密钥转为无换行的Base64字符串：

base64 -w 0 /path/to/your/ssh_key

复制输出的完整字符串，替换Bitbucket中存储的SSH_KEY变量值。

2. 流水线脚本解码并构建
   在Bitbucket流水线的构建脚本中，先解码Base64字符串，再传递给Docker：

# 解码还原密钥
SSH_KEY=$(echo "$SSH_KEY" | base64 -d)
# 执行Docker构建
docker build --build-arg SSH_KEY="${SSH_KEY}" .

3. Dockerfile中正确写入密钥
   确保Dockerfile写入密钥时保留完整格式：

ARG SSH_KEY
RUN mkdir -p /root/.ssh && \
    echo "$SSH_KEY" > /root/.ssh/id_rsa && \
    chmod 600 /root/.ssh/id_rsa && \
    ssh-keyscan your-git-host.com >> /root/.ssh/known_hosts

方案2：使用Docker BuildKit的Secret功能（更安全） #

该方式避免将密钥作为构建参数暴露，同时完整保留密钥格式：

1. 流水线中写入临时密钥文件

pipelines:
  default:
    - step:
        name: Build Docker Image
        script:
          # 将变量写入临时文件并设置权限
          echo "$SSH_KEY" > ./temp_ssh_key
          chmod 600 ./temp_ssh_key
          # 启用BuildKit并传递secret
          DOCKER_BUILDKIT=1 docker build --secret id=ssh_key,src=./temp_ssh_key .

2. Dockerfile中挂载Secret

# 必须指定BuildKit语法
# syntax=docker/dockerfile:1.2

RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa \
    mkdir -p /root/.ssh && \
    chmod 600 /root/.ssh/id_rsa && \
    ssh-keyscan your-git-host.com >> /root/.ssh/known_hosts && \
    # 执行需要SSH密钥的操作，比如克隆私有仓库
    git clone git@your-git-host.com:your/repo.git

额外注意事项 #

• 确保Bitbucket变量的类型设置为"Secured"，避免密钥明文暴露。
• 流水线脚本中引用变量时必须用双引号包裹（"$SSH_KEY"），防止Shell分割换行符或空格。

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