GitHub Actions中多行PEM密钥的环境变量传递指南_石家庄创泽智能科技有限公司

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

GitHub Actions中多行PEM密钥的环境变量传递指南

2025-11-05

浏览次数：次

返回列表

GitHub Actions中多行PEM密钥的环境变量传递指南

本文详细介绍了在github actions工作流中，如何正确地将包含多行内容的`.pem`密钥从github secrets安全地传递给环境变量，以避免因yaml解析错误导致的工作流失败。核心解决方案是利用yaml的多行字符串字面量（`|`）语法，确保密钥的完整性和格式在传递过程中得以保留。

在自动化工作流中，尤其是在持续集成/持续部署（CI/CD）场景下，我们经常需要处理敏感信息，例如API密钥、SSH私钥或应用程序凭证。GitHub Actions通过其Secrets机制提供了一种安全存储这些敏感数据的方式。然而，当这些密钥是多行文本（如.pem格式的私钥）时，将其直接传递到工作流的环境变量中可能会遇到YAML解析问题。

问题分析：多行密钥与YAML解析冲突

.pem格式的私钥通常包含多行文本，例如：

-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEAw...
...
-----END RSA PRIVATE KEY-----

当尝试将一个包含换行符的GitHub Secret直接赋值给环境变量时，GitHub Actions的YAML解析器可能会错误地将其中的换行符或特定字符序列（如-----END RSA PRIVATE KEY-----）识别为YAML文档的分隔符或语法错误，导致工作流失败并报错，例如：

error: error parsing STDIN: invalid Yaml document separator: --END RSA PRIVATE KEY-----"

这表明YAML解析器未能将整个多行字符串视为一个单一的值，而是试图将其内部的某些行解析为独立的YAML结构。

解决方案：使用YAML多行字符串字面量（|）

YAML提供了一种优雅的方式来处理多行字符串，即使用块标量样式。其中，字面量样式（|）是解决此问题的关键。字面量样式会保留字符串中的所有换行符和末尾的空行（如果存在），这对于需要精确保留格式的多行密钥（如.pem文件）至关重要。

不正确的做法（导致解析错误）：

  - name: 执行特定步骤
    run:  echo "执行命令"
    env:
      GITHUBAPP_KEY: "${{ secrets.GITHUBAPP_KEY }}" # 直接引用，可能导致YAML解析错误

在这种情况下，即使使用了双引号，YAML解析器仍可能在某些复杂的场景下无法正确处理内部的换行符和特殊字符。

正确的做法（使用字面量样式 |）：

VALL-E

VALL-E是一种用于文本到语音生成 (TTS) 的语言建模方法

134 查看详情 VALL-E

通过在环境变量名称后添加 | 符号，YAML解析器会将后续缩进的内容视为一个完整的、包含换行符的字符串。

  - name: 执行特定步骤
    run:  echo "执行命令"
    env:
      GITHUBAPP_KEY: |
        ${{ secrets.GITHUBAPP_KEY }} # 使用 | 确保多行字符串被正确解析

工作原理：

当YAML解析器遇到 | 符号时，它会知道接下来的内容（直到缩进级别改变或文件结束）都应该被视为一个连续的字符串值，包括所有的换行符。这样，.pem 密钥的完整结构得以保留，不会被误解为YAML语法的一部分。

完整示例工作流片段

以下是一个GitHub Actions工作流的示例，展示了如何正确地将多行.pem密钥传递给环境变量：

name: Deploy Application

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 配置GitHub App密钥
        run: |
          # 假设你的应用程序需要将密钥写入一个文件
          echo "$GITHUBAPP_KEY" > github_app_key.pem
          chmod 600 github_app_key.pem
          # 在这里执行你的应用程序部署命令，它将使用 github_app_key.pem
          # 例如：your_deployment_tool --key-file github_app_key.pem
          echo "GitHub App密钥已成功配置并写入文件。"
        env:
          GITHUBAPP_KEY: |
            ${{ secrets.GITHUBAPP_KEY }} # 从GitHub Secret安全地获取多行密钥

在这个示例中，secrets.GITHUBAPP_KEY 存储了你的.pem密钥。通过 GITHUBAPP_KEY: |，整个密钥内容（包括所有换行符）被作为一个单一的字符串赋值给环境变量 GITHUBAPP_KEY。随后，在 run 步骤中，你可以安全地访问这个环境变量，并将其内容写入文件或直接用于命令。

注意事项与最佳实践

Secret管理： 始终将敏感密钥存储在GitHub仓库或组织级别的Secrets中，而不是直接硬编码在工作流文件中。
缩进： 使用 | 后，其下的内容必须保持正确的缩进。GitHub Actions通常要求两格空格缩进。Secret的值本身不应该有额外的缩进，因为 | 会处理其后的内容块。
其他多行样式： YAML还提供了折叠样式（>），它会将换行符替换为空格，将多行文本折叠成单行。但对于密钥文件，由于其格式的严格性，字面量样式（|）是唯一正确的选择。
文件写入： 如果你的应用程序需要密钥以文件形式存在，可以在 run 步骤中将环境变量的内容写入一个临时文件，并确保设置正确的文件权限（例如 chmod 600）。
安全性： 避免在日志中输出敏感密钥内容。在 run 脚本中处理密钥时要格外小心，确保它们不会意外地被打印出来。GitHub Actions会自动尝试过滤掉日志中的Secrets，但仍需谨慎。