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

教程：创建并运行你的第一个 GitLab CI/CD pipeline

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

本教程向你展示如何在 GitLab 中配置并运行你的第一个 CI/CD pipeline。

如果你已经熟悉基本 CI/CD 概念，可以在教程：创建复杂 pipeline 中了解常用关键词。

前置条件

开始之前，请确保你拥有：

一个想要使用 CI/CD 的 GitLab 项目。
项目的 Maintainer 或 Owner 角色。

如果你没有项目，可以在 https://gitlab.com 上免费创建一个公开项目。

步骤

要创建并运行你的第一个 pipeline：

确保你有可用的 runners 来运行你的 jobs。

如果你使用的是 GitLab.com，可以跳过这一步。GitLab.com 为你提供了 instance runners。
创建一个 .gitlab-ci.yml 文件在你的仓库根目录。这个文件是你定义 CI/CD jobs 的地方。

当你将文件提交到仓库时，runner 会运行你的 jobs。 job 结果会在 pipeline 中显示。

确保你有可用的 runners

在 GitLab 中，runners 是运行你的 CI/CD jobs 的代理。

如果你使用的是 GitLab.com，可以跳过这一步。GitLab.com 为你提供了 instance runners。

要查看可用的 runners：

在左侧边栏，选择 Search or go to 并找到你的项目。
选择 Settings > CI/CD。
展开 Runners。

只要你有一个活跃的 runner（旁边有绿色圆圈），你就有一个可用的 runner 来处理你的 jobs。

如果你无法访问这些设置，请联系你的 GitLab 管理员。

如果你没有 runner

如果你没有 runner：

在你的本地机器上安装 GitLab Runner。
为你的项目注册 runner。选择 shell 执行器。

当你的 CI/CD jobs 运行时，在后续步骤中，它们将在你的本地机器上运行。

创建 `.gitlab-ci.yml` 文件

现在创建一个 .gitlab-ci.yml 文件。这是一个 YAML 文件，你在其中指定 GitLab CI/CD 的指令。

在这个文件中，你定义：

runner 应该执行的 jobs 的结构和顺序。
runner 在遇到特定条件时应该做出的决定。

要在你的项目中创建 .gitlab-ci.yml 文件：

在左侧边栏，选择 Search or go to 并找到你的项目。
选择 Code > Repository。
在文件列表上方，选择你想要提交到的分支。如果不确定，保留 master 或 main。然后选择加号图标 ( ) 和 New file：

对于 Filename，输入 .gitlab-ci.yml，在较大的窗口中，粘贴这个示例代码：

build-job:
  stage: build
  script:
    - echo "Hello, $GITLAB_USER_LOGIN!"

test-job1:
  stage: test
  script:
    - echo "This job tests something"

test-job2:
  stage: test
  script:
    - echo "This job tests something, but takes more time than test-job1."
    - echo "After the echo commands complete, it runs the sleep command for 20 seconds"
    - echo "which simulates a test that runs 20 seconds longer than test-job1"
    - sleep 20

deploy-prod:
  stage: deploy
  script:
    - echo "This job deploys something from the $CI_COMMIT_BRANCH branch."
  environment: production

这个示例展示了四个 jobs：build-job、test-job1、test-job2 和 deploy-prod。 echo 命令中列出的注释在查看 jobs 时会显示在 UI 中。预定义变量 $GITLAB_USER_LOGIN 和 $CI_COMMIT_BRANCH 的值在 jobs 运行时会被填充。

选择 Commit changes。

pipeline 启动并运行你在 .gitlab-ci.yml 文件中定义的 jobs。

查看 pipeline 和 jobs 的状态

现在来看看你的 pipeline 和其中的 jobs。

转到 Build > Pipelines。应该会显示一个包含三个 stages 的 pipeline：
通过选择 pipeline ID 查看 pipeline 的可视化表示：
通过选择 job 名称查看 job 的详细信息。例如，deploy-prod：

你已经在 GitLab 中成功创建了你的第一个 CI/CD pipeline。恭喜！

现在你可以开始自定义你的 .gitlab-ci.yml 并定义更高级的 jobs。

`.gitlab-ci.yml` 提示

这里有一些帮助你开始使用 .gitlab-ci.yml 文件的提示。

关于完整的 .gitlab-ci.yml 语法，请参阅完整的 CI/CD YAML 语法参考。

使用 pipeline 编辑器来编辑你的 .gitlab-ci.yml 文件。
每个 job 都包含一个 script 部分，并属于一个 stage：
- stage 描述了 jobs 的顺序执行。如果有可用的 runners，单个 stage 中的 jobs 会并行运行。
- 使用 needs 关键字来按非 stage 顺序运行 jobs，以提高 pipeline 的速度和效率。
你可以设置额外的配置来自定义你的 jobs 和 stages 的执行方式：
- 使用 rules 关键字来指定何时运行或跳过 jobs。 only 和 except 传统关键字仍然受支持，但不能与 rules 在同一个 job 中使用。
- 使用 cache 和 artifacts 在 pipeline 中跨 jobs 和 stages 保持信息持久化。这些关键字是存储依赖项和 job 输出的方式，即使每个 job 都使用临时运行器也是如此。
- 使用 default 关键字来指定应用于所有 jobs 的额外配置。这个关键字通常用于定义应该在每个 job 上运行的 before_script 和 after_script 部分。