CI/CD / 知识点

GitHub Actions 工作流语法速查

集成运行环境

在 Job 的 services 下定义数据库、Redis 等辅助容器,让测试步骤在同一 Runner 环境中访问依赖服务;适合集成测试和本地化 CI 环境。

配置服务容器

当集成测试需要 PostgreSQL、Redis、消息队列等临时依赖时,查 jobs.<job_id>.services。它让依赖随 Job 创建并在 Job 结束后销毁;访问方式取决于 Job 是直接跑在 Runner 上,还是运行在 container 中。

怎么判读

键 含义 建议动作
image 服务容器镜像,服务定义的核心字段 为可重复 CI 固定主版本或镜像摘要
env 传给服务容器的环境变量 只放服务启动所需配置,敏感值引用 Secrets
options 额外的 Docker 创建参数 常用于 --health-* 健康检查;--network 与 --entrypoint 不受支持
ports 将容器端口映射到 Docker 主机 Job 直接跑在 Runner 上时按需配置
credentials 拉取私有镜像时使用的注册表凭据 使用 Secrets 提供用户名和密码
volumes 服务容器卷挂载 只有确需共享 Job 内数据时再配置

快速配置

下面的完整工作流启动 PostgreSQL,并让 Runner 通过 GitHub 分配的随机主机端口确认 TCP 可连接。健康检查通过后,Job 步骤才继续执行。

yaml
name: Service container check

on:
  workflow_dispatch:

jobs:
  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432/tcp

    steps:
      - name: Verify PostgreSQL port
        env:
          PG_PORT: ${{ job.services.postgres.ports['5432'] }}
        run: |
          echo "PostgreSQL host port: $PG_PORT"
          timeout 5 bash -c "cat < /dev/null > /dev/tcp/127.0.0.1/$PG_PORT"
          echo "TCP connection OK"

预期输出:

text
PostgreSQL host port: <PORT>
TCP connection OK

<PORT> 是 Runner 上动态分配的实际端口,每次运行可能不同。

访问方式

Job 运行位置 服务地址 是否通常需要 ports
直接运行在 Linux Runner localhost 或 127.0.0.1 加映射后的主机端口 需要
Job 使用 container 服务标签作为主机名,例如 postgres:5432 不需要,同一 Docker 网络内端口可直接互通

服务只属于声明它的那个 Job,生命周期由 Runner 管理。若镜像健康检查失败,先看服务容器启动日志、环境变量和镜像自身要求,而不是继续重试测试步骤。

适用范围

GitHub Actions 的服务容器要求 Linux:GitHub 托管 Runner 使用 Ubuntu;自托管 Runner 需为 Linux 且安装 Docker。服务容器不能在 composite action 内部创建。具体镜像变量、健康检查命令和初始化行为以对应镜像文档为准。

表达式与上下文

制品与缓存

目录与阅读设置

记录一个想法

GitHub Actions 工作流语法速查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通