Help us learn about your current experience with the documentation. Take the survey.

教程：设置 CI/CD 步骤

本教程向您展示如何在流水线中创建和使用步骤。

步骤是作业中可重用和可组合的组件。每个步骤定义了结构化的输入和输出，可以被其他步骤使用。您可以在本地文件、GitLab.com 仓库或其他任何 Git 源中配置步骤。

在本教程中，使用 GitLab CLI (glab) 来：

  1. 创建一个输出 “hello world” 的步骤。
  2. 配置流水线以使用该步骤。
  3. 向作业添加多个步骤。
  4. 使用远程步骤回显所有输出。

开始之前

  • 您必须安装并登录到 GitLab CLI (glab)。

创建步骤

首先，创建一个具有以下特性的步骤：

  • exec 类型。
  • 由系统执行 API 启动的 command。

  1. 在您的命名空间中创建一个名为 zero-to-steps 的 GitLab 项目：

    glab project create zero-to-steps

  2. 进入项目仓库的根目录：

    cd zero-to-steps

  3. 创建一个 step.yml 文件。

    touch step.yml

  4. 使用文本编辑器向 step.yml 添加规范：

    spec:
  inputs:
    who:
      type: string
      default: world
    • spec 有一个名为 who 的输入。
    • 输入 who 是可选的，因为有默认值。

  5. 要向 step.yml 添加实现，在 spec 之后添加第二个 YAML 文档，包含 exec 键：

    spec:
  inputs:
    who:
      type: string
      default: world
---
exec:
  command:
    - bash
    - -c
    - echo 'hello ${{inputs.who}}'

三连破折号 (---) 将文件分成两个 YAML 文档：

  • 第一个文档是规范，类似于函数签名。
  • 第二个文档是实现，类似于函数体。

bash 和 -c 参数启动一个 Bash shell，并从命令行参数获取脚本输入。除了 shell 脚本，您还可以使用 command 来执行像 docker 或 terraform 这样的程序。

echo 'hello ${{input.name}}' 参数包含在 ${{ 和 }} 之间的表达式。表达式在最后可能的时刻被求值，并且可以访问当前的执行上下文。此表达式访问 inputs 并读取 who 的值：

  • 如果调用者提供了 who，则该值会替换表达式。
  • 如果省略了 who，则默认的 world 会替换表达式。

配置流水线以使用步骤

  1. 在仓库的根目录中，创建一个 .gitlab-ci.yml 文件：

    touch .gitlab-ci.yml

  2. 在 .gitlab-ci.yml 中，添加以下作业：

    hello-world:
  run:
    - name: hello_world
      step: .
    • run 关键字包含一个步骤调用列表。
      • 每个调用都给定一个 name，以便您可以在后续步骤中引用输出。
      • 每个调用指定要运行的 step。本地引用 (.) 指向仓库的根目录。

    有关此代码在您的仓库中应该是什么样子的示例，请参阅 Steps tutorial, part 1。

  3. 提交这两个文件并推送项目仓库。这将触发一个运行该作业的流水线：

    git add .
git commit -m 'Part 1 complete'
git push --set-upstream origin main
glab ci status

  4. 在 “View Logs” 下跟踪作业，直到流水线完成。以下是成功作业的示例：

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
hello world
Cleaning up project directory and file based variables
Job succeeded

您现在已经创建并使用了您的第一个步骤！

向作业添加多个步骤

您可以在一个作业中有多个步骤。

  1. 在 .gitlab-ci.yml 文件中，向您的作业添加另一个名为 hello_steps 的步骤：

    hello-world:
  run:
    - name: hello_world
      step: .
    - name: hello_steps
      step: .
      inputs:
        who: gitlab steps

    此 hello_steps 步骤提供了一个非默认输入 who，值为 gitlab steps。

    有关此代码在您的仓库中应该是什么样子的示例，请参阅 Steps tutorial, part 2a。

  2. 提交并推送更改：

    git commit -a -m 'Added another step'
git push
glab ci status

  3. 在终端中，选择 View Logs 并跟踪流水线直到完成。以下是成功输出的示例：

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
hello world
hello gitlab steps
Cleaning up project directory and file based variables
Job succeeded

重构您的步骤

要重构您的步骤，将它们从 .gitlab-ci.yml 移动到专用文件中：

  1. 将您创建的第一个步骤移动到名为 hello 的目录中：

    mkdir hello
mv step.yml hello/

  2. 在仓库的根目录创建一个新步骤。

    touch step.yml

  3. 向新的 step.yml 添加以下配置：

    spec:
---
run:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab steps

    这个新步骤没有输入，所以 spec 是空的。 它是一个 steps 类型，具有与 .gitlab-ci.yml 中步骤相同的语法。 但是，本地引用现在指向 hello 目录中的您的步骤。

  4. 要使用新步骤，修改 .gitlab-ci.yml：

    hello-world:
  run:
    - name: hello_everybody
      step: .

    现在您的作业只调用没有输入的新步骤。 您已将作业的详细信息重构到单独的文件中。

    有关此代码在您的仓库中应该是什么样子的示例，请参阅 Steps tutorial, part 2b。

  5. 提交并推送更改：

    git add .
git commit -m 'Refactored step config'
git push
glab ci status

  6. 在终端中，选择 View Logs。

  7. 要验证重构后的步骤执行与您最初创建的步骤相同的功能，请查看日志输出。日志输出应与您之前创建的步骤的输出匹配。以下是示例：

    $ /step-runner ci
hello world
hello gitlab steps
Cleaning up project directory and file based variables
Job succeeded

向步骤添加输出

向您的 hello 步骤添加一个输出。

  1. 在 hello/step.yml 中，向 spec 添加一个 outputs 结构：

    spec:
  inputs:
    who:
      type: string
      default: world
  outputs:
    greeting:
      type: string
---
exec:
  command:
    - bash
    - -c
    - echo '{"name":"greeting","value":"hello ${{inputs.who}}"}' | tee ${{output_file}}
    • 在此 spec 中，您定义了一个没有默认值的输出 greeting。因为 没有默认值，所以输出 greeting 是必需的。
    • 输出以 JSON Line 格式写入运行时提供的 ${{output_file}} 文件。写入输出文件的 每一行都必须是一个具有两个键 name 和 value 的 JSON 对象。
    • 此步骤运行 echo '{"name":"greeting","value":"hello ${{inputs.who}}"}' 并将输出发送到作业日志和 输出文件 (tee ${{output_file}})。

  2. 在 step.yml 中，向步骤添加一个输出：

    spec:
  outputs:
    all_greetings:
      type: string
---
run:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab steps
outputs:
  all_greetings: "${{steps.hello_world.outputs.greeting}} and ${{steps.hello_steps.outputs.greeting}}"

    您现在向此步骤添加了一个名为 all_greetings 的输出。

    此输出显示了表达式语法：${{steps.hello_world.outputs.greeting}}。 all_greetings 读取两个子步骤 hello_world 和 hello_steps 的输出。 两个子步骤的输出被连接成一个字符串输出。

使用远程步骤

在提交和运行代码之前，向您的作业添加另一个步骤，以查看主 step.yml 的最终 all_greetings 输出。

此步骤调用引用了一个名为 echo-step 的远程步骤。 echo 步骤接受单个输入 echo，将其打印到日志中，并将其作为 echo 输出。

  1. 编辑 .gitlab-ci.yml：

    hello-world:
  run:
    - name: hello_everybody
      step: .
    - name: all_my_greetings
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
      inputs:
        echo: "all my greetings say ${{steps.hello_everybody.outputs.all_greetings}}"

    有关此代码在您的仓库中应该是什么样子的示例，请参阅 Steps tutorial, part 2c。

  2. 提交并推送更改：

    git commit -a -m 'Added outputs'
git push
glab ci status

  3. 在 “View Logs” 下跟踪作业，直到流水线完成。以下是成功输出的示例：

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
{"name":"greeting","value":"hello world"}
{"name":"greeting","value":"hello gitlab steps"}
all my greetings say hello world and hello gitlab steps
Cleaning up project directory and file based variables
Job succeeded

就是这样！您刚刚在流水线中创建并实现了步骤。 有关步骤语法的更多信息，请参阅 CI/CD Steps。