常量、描述、源码示例以及渲染
GitHub Actions 关键字常量
| 关键字 | 描述 | 示例 YAML (源码) | 渲染后的示例 |
|---|---|---|---|
name |
工作流、作业或步骤的名称。 | name: CI Workflow |
CI Workflow |
on |
触发工作流的事件类型（例如 push、pull_request、workflow_run 等）。 |
on: push |
push |
jobs |
定义工作流中的多个作业，包含每个作业的详细配置。 | jobs: build |
build |
runs-on |
设置作业执行的虚拟环境或操作系统。 | runs-on: ubuntu-latest |
ubuntu-latest |
steps |
作业中的各个步骤，每个步骤可以包含执行的命令或调用外部 Action。 | steps: |
[Checkout code, Run tests] |
uses |
调用外部动作或脚本。 | uses: actions/checkout@v2 |
actions/checkout@v2 |
with |
向步骤传递输入参数。 | with: {version: '1.0.0'} |
version: 1.0.0 |
env |
定义环境变量，可以传递给整个工作流或特定步骤。 | env: {MY_ENV_VAR: 'value'} |
MY_ENV_VAR: value |
name |
定义步骤的名称。 | name: Checkout code |
Checkout code |
run |
直接运行命令或脚本。 | run: echo "Hello, World" |
echo "Hello, World" |
id |
定义作业节点的唯一标识。 | id: Hello |
id: Hello |
continue-on-error |
如果步骤出错是否继续执行后续步骤。 | continue-on-error: true |
true |
timeout-minutes |
设置步骤的超时时间，单位为分钟。 | timeout-minutes: 10 |
10 |
if |
条件表达式，控制步骤是否执行。 | if: success() |
success() |
matrix |
在矩阵作业中，定义不同的环境组合（例如多个操作系统或多个版本）。 | matrix.os |
ubuntu-20.04 |
timeout-minutes |
设置作业或步骤的最大执行时间（单位：分钟）。 | timeout-minutes: 10 |
10 |
fail-fast |
控制矩阵作业是否在遇到失败时提前终止。 | fail-fast: true |
true |
cancel-in-progress |
在运行新作业时，是否取消尚未完成的作业。 | cancel-in-progress: true |
true |
runs |
设置作业的运行环境，如操作系统、容器、或者自定义运行器。 | runs: ubuntu-latest |
ubuntu-latest |
path |
定义文件路径，用于步骤中的文件存储和操作。 | path: ./my-folder/* |
./my-folder/* |
services |
配置在作业中运行的外部服务（如数据库、缓存等）。 | services: mysql: image: mysql:5.7 |
mysql:5.7 |
permissions |
配置工作流的权限，控制对资源的访问权限。 | permissions: write-all |
write-all |
outputs |
作业或步骤的输出结果，可以在工作流的后续作业中使用。 | outputs: result: ${{ steps.step1.outputs.result }} |
result: success |
secrets |
用于传递机密信息，通常是加密的密钥，适用于保护敏感数据。 | secrets.MY_SECRET |
my_secret_value |
permissions |
控制工作流和作业的权限。 | permissions: contents: read |
contents: read |
needs |
定义作业之间的依赖关系，某个作业完成后才能执行另一个作业。 | needs: [job1] |
job1 |
strategy |
用于定义作业的策略，如矩阵（matrix）策略。 | strategy: matrix: os: [ubuntu-20.04, ubuntu-18.04] |
matrix: os: ubuntu-20.04 |
status |
用于查看当前工作流或作业的状态，常与 if 结合使用。 |
if: failure() |
failure() |
artifact |
上传并存储作业结果或工件。 | name: my-artifactuses: actions/upload-artifact@v3 |
upload-artifact |
事件和条件表达式常量
| 常量/表达式 | 描述 | 示例 YAML (源码) | 渲染后的示例 |
|---|---|---|---|
if |
控制步骤是否执行的条件表达式。 | if: success() |
success() |
success() |
检查上一个步骤是否成功。 | if: success() |
true |
failure() |
检查上一个步骤是否失败。 | if: failure() |
false |
matrix |
在矩阵作业中，定义不同的环境组合。 | matrix.os |
ubuntu-20.04 |
| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ |
github.actor |
触发工作流的 GitHub 用户名。 | github.actor |
octocat |
github.event |
事件的详细数据，例如 push、pull_request 等。 |
github.event_name |
push |
github.event_name |
当前触发工作流的事件名称。 | github.event_name |
push |
github.event_path |
事件的完整数据路径（JSON 格式）。 | github.event_path |
/tmp/github-events/event.json |
github.repository |
仓库的全名，包括用户名和仓库名。 | github.repository |
octocat/Hello-World |
github.repository_owner |
仓库的所有者（用户名）。 | github.repository_owner |
octocat |
github.ref |
当前触发工作流的 Git 参考（如分支或标签）。 | github.ref |
refs/heads/main |
github.sha |
提交的 SHA 值。 | github.sha |
f1f2f3f4f5f6f7f8f9f0f1f2f3f4f5f6f7f8f9f0f1 |
github.head_ref |
拉取请求的源分支，仅在 pull_request 事件触发时有效。 |
github.head_ref |
feature-branch |
github.base_ref |
拉取请求的目标分支，仅在 pull_request 事件触发时有效。 |
github.base_ref |
main |
github.ref_type |
引用的类型（例如 branch 或 tag）。 |
github.ref_type |
branch |
github.workflow |
当前运行的工作流名称。 | github.workflow |
CI Workflow |
github.run_id |
当前工作流的运行 ID。 | github.run_id |
1234567890 |
github.run_number |
当前工作流的运行编号。 | github.run_number |
42 |
github.job |
当前作业的名称。 | github.job |
build |
github.os |
当前运行的操作系统。 | github.os |
Ubuntu |
github.workspace |
当前运行作业的工作空间目录。 | github.workspace |
/home/runner/work/Hello-World/Hello-World |
github.token |
用于 GitHub API 调用的自动生成的 token。 | env.GITHUB_TOKEN |
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
github.api_url |
GitHub API 的 URL 地址。 | github.api_url |
https://api.github.com |
github.server_url |
GitHub 服务器的 URL 地址。 | github.server_url |
https://github.com |
github.action |
当前触发的动作名称。 | github.action |
checkout |
github.event_actor |
触发当前事件的 GitHub 用户名或机器人账号。 | github.event_actor |
octocat |
环境变量和机密
| 常量 | 描述 | 示例 YAML (源码) | 渲染后的示例 |
|---|---|---|---|
GITHUB_TOKEN |
自动生成的 token，用于 GitHub API 调用。 | env.GITHUB_TOKEN |
xxxxxxxxxxxxxxx |
RUNNER_OS |
GitHub runner 使用的操作系统类型。 | runner.os |
Ubuntu |
CI |
通常用于标识 CI 环境。 | env.CI |
true |
HOME |
当前用户的主目录。 | env.HOME |
/home/runner |
PATH |
当前系统的 PATH 环境变量。 | env.PATH |
/usr/local/bin:/usr/bin:/bin |
SECRET_KEY |
GitHub Secrets 中定义的机密。 | secrets.SECRET_KEY |
supersecretkey |
常用 GitHub Actions 仓库
每个仓库都有版本号，可通过对应仓库的查询。这里只告知常用库具体使用可前往仓库详勘README.md如：
actions/checkout仓库为：https://github.com/actions/checkout
目前最新的发行版本是v4.2.2，则使用时的版本为：actions/checkout@4
| Action 类型/功能 | uses 示例 |
|---|---|
| Checkout 代码 | uses: actions/checkout |
| 登录 Docker 仓库 | uses: docker/login-action |
| 设置 Docker Buildx 环境 | uses: docker/setup-buildx-action |
| 设置 QEMU 环境 | uses: docker/setup-qemu-action |
| 为多种架构构建和推送Docker镜像 | uses: docker/build-push-action |
| 上传工件 | uses: upload-artifact |
通用案例
name: XXX Docker Image CI
on:
# 推送触发`支持分支、标签等等`
#push:
# cron定时触发
#schedule:
# 拉取请求触发`支持创建、更新、同步等等`
#pull_request:
# 其他工作流完成时触发
#workflow_run:
# 镜像或软件包被发布或更新时触发
#registry_package:
# 手动触发`支持主动输入参数`
workflow_dispatch:
jobs:
build:
# Action的作业环境`ubuntu-latest`、`windows-latest`、`macOS-latest`
# 其他：https://docs.github.com/zh/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job
runs-on: ubuntu-latest
steps:
# 迁出仓库代码
- name: Checkout code
uses: actions/checkout@v4
with:
ref: ${{ github.ref }}
# 设置 Docker Buildx 环境
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
# 设置仓库域名变量
- name: Set registry environment variable
run: echo "REGISTRY=ghcr.io" >> $GITHUB_ENV
# 登录仓库
- name: Log in to the Container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# 读取软件版本，这里将`nodejs`的项目作为案例
- name: Extract version from package.json
id: version
run: |
VERSION=$(jq -r '.version' package.json)
echo "VERSION=$VERSION" >> $GITHUB_ENV
echo "Version extracted: $VERSION"
# 构建并推送镜像
- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
# 指定`docker`目录位置，`.`则表示当前
context: .
# 启用推送，反之只编译
push: true
tags: |
# 假设仓库是：https://github.com/hypothesis/super-application
# 那么打出的镜像就为：ghcr.io/hypothesis/super-application:latest
${{ env.REGISTRY }}/${{ github.repository }}:latest
${{ env.REGISTRY }}/${{ github.repository }}:${{ env.VERSION }}
# 需要支持的CPU平台
platforms: linux/amd64,linux/arm64
# =====================假设不仅需要推送仓库还需打包镜像`tar`文件下载=====================
# 打包镜像
- name: Pack Docker Images
env:
latest: ${{ env.REGISTRY }}/${{ github.repository }}:latest
definition: ${{ env.REGISTRY }}/${{ github.repository }}:${{ env.VERSION }}
run: |
docker save "$latest" -o "${latest//[:\/]/-｝.tar"
docker save "$definition" -o "${definition//[:\/]/-}.tar"
# 为工件名称生成时间戳
- name: Generate timestamp for artifact name
id: timestamp
run: echo "timestamp=$(TZ="Asia/Shanghai" printf "%(%Y%m%d%H%M%S)T")" >> $GITHUB_ENV
# 上传工件
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
# 工件名称
name: docker-images-${{ env.timestamp }}
# 打包文件路径
path: "*.tar"
# 保留天数: 1~90
retention-days: 1
# 压缩等级: 1~9
compression-level: 9
# 如果找不到文件: `warn`、`error`、`ignore`
if-no-files-found: error
如果对各位佬们有帮助希望能给个赞~
