我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

GitHub 操作的虚拟环境

GitHub 使用托管的虚拟机运行工作流程。 虚拟机包含可供 GitHub 操作 使用的工具、包和设置。

GitHub 操作 目前在有限公测阶段,可能会有变动。强烈建议在公测期间不要将此功能用于高价值工作流程和内容。

更多信息请参阅“关于 GitHub 操作”。

本文内容

关于虚拟环境

Linux 和 Windows GitHub 操作 虚拟环境托管于安装有 GitHub 操作 运行程序的 Microsoft Azure 中的 Standard_DS2_v2 虚拟机上。 GitHub 操作 运行程序是 Azure Pipelines Agent 的复刻。 有关 Standard_DS2_v2 机器资源的更多信息,请参阅 Microsoft Azure 文档中的“DSv2-系列”。 GitHub 使用 MacStadium 托管 macOS 虚拟环境。

使用 GitHub 托管的设备时,设备维护和升级由您负责。 您可以直接在虚拟机上或 Docker 容器中运行工作流程。

GitHub 通过 Linux、macOS 和 Windows 环境托管虚拟机。 工作流程中的每项作业都在全新的虚拟环境实例中执行。 作业中的所有步骤在同一虚拟环境实例中执行,让该作业中的操作使用文件系统共享信息。

可以为工作流程中的每项作业指定虚拟环境。 您可以配置每项作业在不同的虚拟环境中运行,或者在同一环境中运行所有作业。

支持的虚拟环境和硬件资源

每台虚拟机都有相同的硬件资源。

GitHub 提供多个虚拟环境。 For a list of supported software, tools, and packages in each virtual environment, see "Software in virtual environments for GitHub 操作."

虚拟环境 YAML 工作流程标签
Windows Server 2019 windows-latestwindows-2019
Windows Server 2016 R2 windows-2016
Ubuntu 18.04 ubuntu-latestubuntu-18.04
Ubuntu 16.04 ubuntu-16.04
macOS X Mojave 10.14 macOS-latestmacOS-10.14

GitHub 托管的计算机上的文件系统

GitHub 创建供操作使用的目录。 在 Docker 容器中运行的操作在 /github 路径下有静态目录。 运行 JavaScript 和 shell 脚本操作的虚拟机上的 GitHub 特定路径不是静态的。 GitHub 提供可用于为 GitHub 操作 使用的 homeworkspaceworkflow 目录构建文件路径的环境变量。 有关 GitHub 为每个操作创建的环境变量列表,请参阅“默认环境变量”。

Docker 容器文件系统

强烈建议使用默认环境变量在 Docker 容器中构建文件路径。

GitHub 保留 /github 路径前缀,并为操作创建三个目录。

环境变量

GitHub sets default environment variables available to every step in a workflow run. Additional environment variables are set in the workflow file. 操作可以创建、读取和修改环境变量。

You can define environment variables for a step in a workflow file using the jobs.<job_id>.steps.env keyword. For more information, see "[Workflow syntax for

GitHub ](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepsenv)."

GitHub converts environment variables names to upper case. For example, if you set the variables first_name, middle_name, and last_name for a step in your workflow, you could read the FIRST_NAME, MIDDLE_NAME, and LAST_NAME environment variables.

steps:
  - name: Hello world
    run: echo Hello world ${FIRST_NAME} ${MIDDLE_NAME} ${LAST_NAME}!
    env:
      first_name: Mona
      middle_name: The
      last_name: Octocat

默认环境变量

强烈建议操作使用环境变量访问文件系统,而非硬编码的文件路径。 GitHub 设置供操作用于所有虚拟环境中的环境变量。

环境变量 描述
HOME 用于存储用户数据的 GitHub 主目录路径。 例如 /github/home
GITHUB_WORKFLOW 工作流程的名称。
GITHUB_ACTION 操作的名称。
GITHUB_ACTOR 发起工作流程的个人或应用程序的名称。 例如 octocat
GITHUB_REPOSITORY 所有者和仓库名称。 例如 octocat/Hello-World
GITHUB_EVENT_NAME 触发工作流程的 web 挂钩事件的名称。
GITHUB_EVENT_PATH 具有完整 web 挂钩事件有效负载的文件路径。 例如 /github/workflow/event.json
GITHUB_WORKSPACE GitHub 工作空间目录路径。 如果您的工作流程使用 actions/checkout 操作,工作空间目录将包含存储仓库副本的子目录。 如果不使用 actions/checkout 操作,该目录将为空。 例如 /home/runner/work/my-repo-name/my-repo-name
GITHUB_SHA 触发工作流程的提交 SHA。 例如 ffac537e6cbbf934b08745a378932722df287a53
GITHUB_REF 触发工作流程的分支或标记参考。 例如 refs/heads/feature-branch-1。 如果分支或标记都不适用于事件类型,则变量不会存在。
GITHUB_HEAD_REF 仅为复刻的仓库设置。 头部仓库的分支。
GITHUB_BASE_REF 仅为复刻的仓库设置。 基础仓库的分支。

命名约定

注: GitHub 会保留 GITHUB_ 环境变量前缀供 GitHub 内部使用。 设置有 GITHUB_ 前缀的环境变量或密码将导致错误。

您设置的指向文件系统上某个位置的任何新环境变量都应该有 _PATH 后缀。 HOMEGITHUB_WORKSPACE 默认变量例外于此约定,因为 "home" 和 "workspace" 一词已经暗示位置。

创建和使用密码(加密的变量)

对仓库具有 write 权限的任何人都可以读取和使用密码。

密码是仓库中创建的加密环境变量,只能被 GitHub 操作 使用。 GitHub 使用公钥验证的加密和 Poly1305 密码算法对 web 浏览器中的密码进行加密。 更多信息请参阅“TweetNaCl.js”文档。 为使密码用于操作,必须将密码设置为工作流程文件中的输入或环境变量。

GitHub 自动将密码编写到日志,但您应避免有意将密码打印到日志。

密码名称不能包含任何空格。 为确保 GitHub 在日志中编写密码,请勿将结构化数据用作密码的值,如 JSON 或编码的 Git blob。

  1. 在 GitHub 上,导航到仓库的主页面。

  2. 在仓库名称下,单击 Settings(设置)

    仓库设置按钮

  3. 在左侧边栏中,单击 Secrets(密码)

  4. 在 "Name"(名称)输入框中输入密码的名称。

  5. 输入密码的值。

  6. 单击 Add secret(添加密码)

To pass a secret to an action, set the secret as an input or environment variable in your workflow. Review the action's README file to learn about which inputs and environment variables the action expects. For more information, see "Workflow syntax for GitHub 操作."

With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository.

steps:

  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

GITHUB_TOKEN 密码

The GITHUB_TOKEN secret is a GitHub 应用程序 installation token scoped to the repository that contains your workflow. GitHub 默认为您创建 GITHUB_TOKEN 密码,但您必须将其包含在工作流程中才可供操作使用。 您可以使用 GITHUB_TOKEN 密码来代表操作进行验证的 GitHub API 调用。

为工作流程文件中每个需要访问 GITHUB_TOKEN 密码的操作创建环境变量:

steps:

  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - name: My second action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
令牌权限

有关 GitHub Apps 可通过各种权限访问的 API 端点的信息,请参阅 GitHub 开发者文档 中的“GitHub 应用程序 权限”。

权限 访问类型 通过复刻的仓库访问
检查 读/写 读取
内容 读/写 读取
部署 读/写 读取
议题 读/写 读取
元数据 读取 读取
读/写 读取
拉取请求 读/写 读取
仓库项目 读/写 读取
状态 读/写 读取

密码的限制

工作流程最多可有 100 个密码,且密码环境变量的名称对每个仓库必须唯一。

密码大小限于 64 KB。 要使用大于 64 KB 的密码,可以将加密的密码存储在仓库中,并将解密短语在 GitHub 上存储为密码。 例如,在将文件检入您在 GitHub 上的仓库之前,可以使用 gpg 在本地对您的凭据加密。 更多信息请参阅“gpg manpage”。

警告:请注意,您的密码在操作运行时不会印出。 使用此解决方法时,GitHub 不会编写日志中印出的密码。

  1. 从终端运行以下命令,以使用 gpg 和 AES256 密码算法对 my_secret.json 文件加密。

    $ gpg --symmetric --cipher-algo AES256 my_secret.json
  2. 将会提示您输入密码短语。 请记住该密码短语,因为需要在使用该密码短语作为值的 GitHub 上创建新密码。

  3. 在仓库中创建新密码来存储密码短语。 例如,使用名称 LARGE_SECRET_PASSPHRASE 创建新密码,并将密码的值设为上一步所选的密码短语。

  4. 将加密的文件复制到仓库并提交。 在本例中,加密的文件是 my_secret.json.gpg

  5. 创建 shell 脚本对密码解密。 将此文件另存为 decrypt_secret.sh

    #!/bin/sh
    
    # Decrypt the file
    mkdir $HOME/secrets
    # --batch to prevent interactive command --yes to assume "yes" for questions
    gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
    --output $HOME/secrets/my_secret.json my_secret.json.gpg
  6. 确保 shell 脚本在检入仓库之前可执行。

    $ chmod +x decrypt_secret.sh
    $ git add decrypt_secret.sh
    $ git commit -m "Add new decryption script"
    $ git push
  7. 从工作流程使用 step 调用 shell 脚本并对密码解密。 要在工作流程运行的虚拟环境中创建仓库的副本,需要使用 actions/checkout 操作。 使用与仓库根目录相关的 run 命令引用 shell 脚本。

    name: Workflows with large secrets
    
    on: push
    
    jobs:
      my-job:
        name: My Job
        runs-on: ubuntu-latest
        steps:
    
          - uses: actions/checkout@v1
          - name: Decrypt large secret
            run: ./.github/scripts/decrypt_secret.sh
            env:
              LARGE_SECRET_PASSPHRASE: $
          # This command is just an example to show your secret being printed
          # Ensure you remove any print statements of your secrets. GitHub does
          # not hide secrets that use this workaround.
          - name: Test printing your secret (Remove this step in production)
            run: cat $HOME/secrets/my_secret.json

退出代码和状态

您可以使用退出代码提供操作的状态。 GitHub uses the exit code to set the GitHub 操作's check run status, which can be success or failure.

退出状态 检查运行状态 描述
0 success 操作已成功完成,依赖它的其他操作可以开始。
非零值 failure 任何其他退出代码都表示操作失败。 当操作失败时,所有同时进行的操作都会取消,且跳过未来的操作。 检查运行和检查套件都将收到 failure 状态。

有关检查 API 的更多信息,请参阅 GitHub 开发者文档 中的“检查”。

问问别人

找不到要找的内容?

联系我们