在 GitHub Actions 中使用 env 文件

1. 概述

敏感信息如 API 密钥、数据库凭证等，不应随意存储。一旦泄露，可能引发严重的安全问题，影响个人和组织。通过环境变量，我们可以将这些敏感信息从代码中分离出来进行管理。然而，在自动化工作流中安全地集成这些变量并不容易。

在本教程中，我们将探讨如何在 GitHub Actions 工作流中使用 .env 文件来安全地存储和管理环境变量。

2. 理解环境变量

环境变量是一种在运行时影响程序行为的动态配置方式。它们常用于保存配置设置和敏感信息，如 API 密钥和数据库凭证，是应用正常运行所必需的。

2.1. 环境变量的重要性

环境变量之所以重要，主要体现在以下几点：

✅ 安全性：将敏感信息从源代码中移除，降低泄露风险
✅ 配置管理：方便在不同环境（开发、测试、生产）中切换配置
✅ 可移植性：使应用更容易适应不同的运行环境，尤其在 CI/CD 流水线、容器化部署和云环境中非常有用

2.2. 环境变量的工作原理

应用程序和脚本可以在运行时访问环境变量。这种动态配置方式增强了安全性与灵活性，尤其在像 GitHub Actions 这样的 CI/CD 流水线中。

例如，GitHub Actions 利用环境变量来动态配置流水线，比如指定环境或提供部署信息：

name: Deploy Application

on:
    push:
        branches:
            - main

jobs:
    deploy:
        runs-on: ubuntu-latest
        env:
            ENVIRONMENT: production
            DEPLOYMENT_URL: https://example.com
        steps:
            - name: Checkout code
              uses: actions/checkout@v4

            - name: Deploy to Server
              run: |
                  curl -X POST ${{ env.DEPLOYMENT_URL }} \
                  -H "Content-Type: application/json" \
                  -d '{"environment":"${{ env.ENVIRONMENT }}"}'

上面的例子在工作流中直接定义了 ENVIRONMENT 和 DEPLOYMENT_URL 两个环境变量。部署步骤中动态使用这些变量来指定目标环境和部署地址。

2.3. 最佳实践

为确保环境变量的安全性和灵活性，建议遵循以下原则：

✅ 避免在代码中硬编码敏感数据
✅ 使用统一的命名规范
✅ 对变量进行文档说明
✅ 控制变量作用域，只在需要的地方暴露

正确使用环境变量可以显著提升应用的安全性和可维护性。

3. 在 GitHub Actions 中存储环境变量

GitHub Actions 提供了多种方法来管理环境变量，确保工作流的安全与高效。主要方法包括直接在工作流文件中使用 env 键，以及使用 GitHub Secrets 来存储敏感数据。

3.1. 在工作流文件中使用 `env` 键

我们可以在工作流文件中使用 env 键直接定义环境变量。这种方式适用于非敏感数据。

$ mkdir gh-action-env-files && cd gh-action-env-files

接着，在 .github/workflows 目录下创建一个新的 GitHub Actions 工作流文件：

$ mkdir -p .github/workflows
$ touch .github/workflows/env-key-example.yml

然后，在 env-key-example.yml 文件中添加以下内容：

name: Env Key Example

on: [push]

jobs:
    create-env-file:
        runs-on: ubuntu-latest
        env:
            SOME_API_KEY: "123456abcdef"
        steps:
            - name: Checkout repository
              uses: actions/checkout@v3

            - name: Create .env file
              run: echo "SOME_API_KEY=${{ env.SOME_API_KEY }}" > .env

该工作流定义了一个名为 Env Key Example 的流程，当有推送事件发生时触发。它包含一个名为 create-env-file 的任务，运行在最新的 Ubuntu 环境中。

任务中定义了一个环境变量 SOME_API_KEY，值为 123456abcdef。工作流包含两个步骤：首先使用 actions/checkout 拉取代码，然后使用 echo 命令将变量写入 .env 文件。

3.2. 推送至 GitHub

定义好工作流后，我们可以将其推送到 GitHub 仓库以触发执行。首先在 GitHub 上创建一个新仓库，然后执行以下命令：

$ git init
$ git add .
$ git commit -m "Add GitHub Actions workflow to use env key"
$ git branch -M main
$ git remote add origin <your-github-repo-url>
$ git push -u origin main

推送完成后，进入 GitHub 仓库的 Actions 标签页查看工作流执行情况。

点击提交信息后展开详细信息，再点击 create-env-file 任务中的 Create .env file 步骤，可以看到 .env 文件成功创建，变量也正确写入。

使用 env 键直接在 GitHub Actions 工作流中定义环境变量，是一种处理非敏感数据的有效方式。接下来我们看看如何使用 GitHub Secrets 安全管理敏感数据。

3.3. 使用 GitHub Secrets

处理 API 密钥、数据库凭证等敏感信息时，必须确保这些信息不会暴露在源代码或工作流文件中。GitHub Secrets 提供了一种安全的方式来存储和引用这些数据。

这些密钥是加密存储的，可以在工作流中引用，而不会以明文形式暴露。要使用 GitHub Secrets，进入仓库的 Settings 标签页，展开左侧的 Secrets and variables，点击 Actions。

点击绿色的 New repository secret 按钮，输入密钥名称和内容。例如：

SECRET_KEY=your_sample_secret_key
DATABASE_URL=your_sample_database_url
API_KEY=your_sample_api_key
AWS_ACCESS_KEY_ID=your_sample_access_key_id
AWS_SECRET_ACCESS_KEY=your_sample_secret_access_key
GOOGLE_CLIENT_ID=your_sample_client_id
GOOGLE_CLIENT_SECRET=your_sample_client_secret
TWITTER_API_KEY=your_sample_api_key
TWITTER_API_SECRET=your_sample_api_secret
FACEBOOK_APP_ID=your_sample_app_id
FACEBOOK_APP_SECRET=your_sample_app_secret
GITHUB_TOKEN=your_sample_github_token
MAILGUN_API_KEY=your_sample_api_key
SENDGRID_API_KEY=your_sample_api_key
SLACK_API_TOKEN=your_sample_api_token
STRIPE_SECRET_KEY=your_sample_secret_key
TWILIO_ACCOUNT_SID=your_sample_account_sid
TWILIO_AUTH_TOKEN=your_sample_auth_token
MONGODB_URI=your_sample_mongodb_uri
REDIS_URL=your_sample_redis_url

保存后，我们可以在工作流中引用这些密钥。

创建一个新的工作流文件：

$ touch .github/workflows/using-github-secrets.yml

添加以下内容：

name: Using GitHub Secrets

on: [push]

jobs:
    using-github-secrets:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout repository
              uses: actions/checkout@v3

            - name: Create .env file
              run: |
                  touch .env
                  echo "${{ secrets.TEST_SECRETS }}" >> .env

            - name: Test printing your secret (Remove this step in production)
              run: |
                  cat .env

该工作流会在每次推送时触发，拉取代码后创建一个 .env 文件，并将密钥写入其中。最后一步用于测试，打印文件内容。

3.4. 推送至 GitHub

将更改提交并推送到 GitHub：

$ git add . && git commit -m "Use GitHub Secrets" && git push origin main

进入 GitHub 仓库的 Actions 标签页，查看工作流执行情况。你会发现密钥在日志中被屏蔽，确保了敏感信息的安全。

Using GitHub Secrets

4. 总结

本文介绍了如何在 GitHub Actions 中使用 .env 文件管理环境变量。

我们首先了解了环境变量的重要性，以及它们在 CI/CD 中的应用。接着，我们演示了如何在工作流中使用 env 键定义非敏感数据，并通过 GitHub Secrets 来安全存储敏感信息。

选择合适的管理方式取决于数据的敏感程度。GitHub Actions 提供了灵活的机制，但合理使用至关重要。

完整代码可在 GitHub 上找到。

Persistence

REST

Security