Migrating from Jenkins

原文：https://docs.gitlab.com/ee/ci/jenkins/

Migrating from Jenkins

许多 GitLab 用户已经从 Jenkins 成功迁移到 GitLab CI / CD. 为了使您入门时更容易，我们在这里收集了一些您可能会在使用之前可能会发现有用的资源.请将此页面视为” Jenkins 用户的 GitLab CI / CD”指南.

建议的步骤的以下列表是在观察能够快速完成此迁移的组织之后创建的：

  1. 首先阅读《 GitLab CI / CD 快速入门指南》和重要的产品差异 .
  2. 了解管理组织过渡的重要性.
  3. 将 Runners 添加到您的 GitLab 实例.
  4. 教育开发人员并使他们能够在他们的项目中独立执行以下步骤：
    1. 查看《 快速入门指南和管道配置参考》 .
    2. 使用Jenkins 包装器暂时维护脆弱的 Jenkins 作业.
    3. 迁移构建和 CI 作业并将其配置为直接在合并请求中显示结果. 他们可以使用Auto DevOps作为起点，并根据需要自定义或分解配置.
    4. 添加评论应用 .
    5. 使用云部署模板 ，添加环境和部署板来迁移部署作业.
    6. 使用 Jenkins 包装器解开仍在运行的所有作业的包装.
  5. 盘点所有常见的 CI / CD 作业定义，然后为其创建和共享模板 .

有关如何将 Jenkins 管道转换为 GitLab CI / CD 管道的示例，或如何使用 Auto DevOps 自动测试代码的示例，请观看从 Jenkins 迁移到 GitLab 的视频.

否则，请继续阅读以获取重要信息，这些信息将帮助您取得成功. 欢迎来到 GitLab！

如果您有未在此处回答的问题， GitLab 社区论坛将是一个很好的资源.

Managing the organizational transition

从詹金斯过渡到 GitLab 的一个重要部分是随之而来的文化和组织变革，并成功地对其进行了管理. 我们发现了一些有助于解决问题的方法：

  • 为您的迁移目标设定并传达清晰的愿景有助于您的用户理解为什么值得付出努力. 当工作完成时，该值将很明显，但是在进行过程中，人们也需要意识到.
  • 有关领导团队的赞助和配合有助于上述观点.
  • 花时间对用户进行不同的教育，与他们共享此文档等等，将有助于确保您成功.
  • 寻找顺序或延迟部分迁移的方法可能会很有帮助，但是您不想让事物长时间处于未迁移（或部分迁移）状态. 要获得 GitLab 的所有好处，仅将现有的 Jenkins 设置转移到原样上（包括任何当前问题）是不够的. 您需要利用 GitLab 提供的改进，这最终需要（最终）更新您的实现.

JenkinsFile Wrapper

我们正在构建一个JenkinsFile 包装器 ，它将允许您在 GitLab 作业（包括插件）中运行完整的 Jenkins 实例. 通过让您将不太紧急的管道的迁移延迟一段时间，可以帮助简化过渡过程.

如果您有兴趣帮助 GitLab 测试包装器，请加入我们的公共测试问题以获取说明并提供您的反馈.

Important product differences

值得一提的产品之间存在一些高级差异：

  • 使用 GitLab，您不需要根pipeline关键字即可包装所有内容.

  • 管道触发和触发其他管道的方式与詹金斯不同. 可以触发 GitLab 管道：

  • 您可以使用rules语法来控制在哪种情况下运行哪些作业，具体取决于触发方式.
  • GitLab 管道调度概念也与 Jenkins 不同.
  • 您可以使用include关键字和模板重复使用管道配置. 您的模板可以保存在中央存储库中（具有不同的权限），然后任何项目都可以使用它们. 这个中央项目也可以包含脚本或其他可重用的代码.
  • You can also use the extends keyword to reuse configuration within a single pipeline configuration.
  • 单个阶段中的所有作业始终并行运行，并且所有阶段均按顺序运行. 我们计划通过我们的有向无环图功能允许某些作业根据需要中断此排序.
  • parallel关键字可以自动并行化任务，例如支持并行化的测试.
  • 通常，单个阶段中的所有作业并行运行，并且所有阶段按顺序运行. 有不同的管道体系结构允许您更改此行为.
  • 建议使用新rules语法控制何时运行不同作业. 它比only/except语法更强大.
  • 一个重要的区别是，作业彼此独立运行，并且每个作业都具有全新的环境. 使用artifacts和dependencies关键字控制作业之间传递工件. 完成后，计划的工作区功能将使您能够更轻松地在串行作业之间持久保留公共工作区.
  • .gitlab-ci.yml文件已签入到存储库的根目录，非常类似于 Jenkinsfile，但采用 YAML 格式（请参阅完整参考 ）而不是 Groovy DSL. 它与声明性 Jenkinsfile 格式最相似.
  • 手动批准或登机口可以设置为以下when:manual作业 . 这些还可以利用protected environments来控制谁可以批准它们.
  • GitLab 带有容器注册表 ，我们建议使用容器映像来设置您的构建环境. 例如，设置一个管道来构建您自己的构建环境，并将其发布到容器注册表. 然后，让您的管道使用此方法，而不是每个管道都使用它们自己的环境，这将变得更慢，并且一致性可能会降低. 我们有大量有关如何使用 Container Registry 的文档.
  • 中央实用程序存储库是放置各种计划作业或其他功能类似于实用程序的手动作业的好地方. 詹金斯的装置中往往有一些.

Agents vs. Runners

Jenkins 代理和 GitLab Runners 都是运行作业的主机. 要转换 Jenkins 代理，只需将其卸载，然后安装并注册 Runner . 运行程序不需要太多的开销，因此您可以像使用的 Jenkins 代理一样调整它们的大小.

与代理相比，Runners 的工作方式存在一些重要差异：

如果您使用的是gitlab.com ，则可以利用我们共享的 Runner gitlab.com来运行作业，而无需置备自己的 Runners. 我们正在研究使它们也可用于自我管理实例 .

Groovy vs. YAML

Jenkins 管道基于Groovy ，因此管道规范以代码形式编写. GitLab 的工作方式略有不同，我们使用结构更高级的YAML格式，该格式将脚本元素放置在script:内部script:块与管道规范本身分开.

这是 GitLab 的优势，因为它有助于使学习曲线更简单地启动和运行，并且避免了一些不受限制的复杂性问题，这些问题会使您的 Jenkinsfile 难以理解和管理.

就是说，我们当然仍然重视 DRY（不要重复自己）的原则，并希望确保您的工作行为可以被一次编码并根据需要进行应用. 您可以使用extends:语法在您的作业中重用配置 ， include:可用于在不同项目的管道中重用管道配置 ：

  1. .in-docker:
  2.   tags:
  3.     - docker
  4.   image: alpine
  6. rspec:
  7.   extends:
  8.     - .in-docker
  9.   script:
  10.     - rake rspec

Artifact publishing

工件的工作方式可能与您与詹金斯一起使用时有所不同. 在 GitLab 中，任何作业都可以使用artifacts:关键字定义一组要保存的artifacts: . 可以将其配置为指向一个文件或一组文件，然后可以在每个作业之间将其持久化. 阅读更多关于我们详细的工件文档的信息 ：

  1. pdf:
  2.   script: xelatex mycv.tex
  3.   artifacts:
  4.     paths:
  5.       - ./mycv.pdf
  6.       - ./output/
  7.     expire_in: 1 week

此外，我们还具有包管理功能，例如可以利用的内置容器，NPM 和 Maven 注册表. 您可以在我们的文档的包装部分中查看打包功能的完整列表（包括指向文档的链接）.

Integrated features

在 Jenkins 中，您可能曾经使用插件来获得代码质量，单元测试，安全扫描等功能，但 GitLab 充分利用了我们连接的生态系统，将这些结果自动提取到您的合并请求，管道详细信息页面和其他位置. 您可能会发现实际上不需要配置任何内容即可显示这些内容.

如果它们无法正常工作，或者您想查看可用的功能 ，则我们的CI 功能索引将提供捆绑功能的完整列表，并提供每个功能的文档链接.

Templates

对于高级 CI / CD 团队，项目模板可以启用管道配置的重用，并鼓励内部采购.

In self-managed GitLab instances, you can build an Instance Template Repository. Development teams across the whole organization can select templates from a dropdown menu. A group administrator is able to set a group to use as the source for the custom project templates, which can be used by all projects in the group. An instance administrator can set a group as the source for instance project templates, which can be used by projects in that instance.

Converting a declarative Jenkinsfile

声明性 Jenkinsfile 包含用于控制管道行为的” Sections”和” Directives”. GitLab 中有所有这些的等效项，我们在下面对此进行了介绍.

本节基于Jenkinsfile 语法文档 ，旨在将其中的概念映射到 GitLab 中的概念.

Sections

agent

代理部分用于定义如何执行管道. 对于 GitLab，我们使用GitLab Runner来提供此功能. 您可以在 Kubernetes 或任何主机上配置自己的运行程序，也可以利用我们的共享运行程序队列（请注意，共享运行程序队列仅适用于 GitLab.com 用户.）以上链接将带您进入说明文档的文档如何快速起步和运行. 我们还支持使用标签将不同的作业定向到不同的 Runner（执行代理）.

agent部分还允许您定义应使用哪些 Docker 映像执行，而我们使用image关键字. 该image可以设置在单个作业或顶层，在这种情况下，它将应用于管道中的所有作业：

  1. my_job:
  2.   image: alpine
  3.   ...

post

post部分定义了应在管道末尾执行的操作. GitLab 也通过阶段的使用来支持这一点. 您可以按以下方式定义阶段，分配给before_pipeline或after_pipeline阶段的所有作业都将按预期运行. 您可以根据需要将这些阶段称为：

  1. stages:
  2.   - before_pipeline
  3.   - build
  4.   - test
  5.   - deploy
  6.   - after_pipeline

可以通过before_script和after_script关键字设置要在任何作业之前和之后执行的步骤：

  1. default:
  2.   before_script:
  3.     - echo "I run before any jobs starts in the entire pipeline, and can be responsible for setting up the environment."

stages

GitLab CI / CD 也可以让您定义阶段，但是可以自由配置一些. GitLab stages关键字是一个顶级设置，它枚举了阶段列表，但是您不需要在” stages部分下嵌套单个作业. 通过使用stage:关键字，可以使.gitlab-ci.yml定义的任何作业成为任何阶段的一部分.

请注意，除非另有说明，否则每个管道都以build ， test和deploy阶段实例化，并按该顺序运行. 未定义stage作业默认情况下放置在test阶段. 当然，引用阶段的每个作业都必须引用管道配置中存在的阶段.

  1. stages:
  2.   - build
  3.   - test
  4.   - deploy
  6. my_job:
  7.   stage: build
  8.   ...

steps

The steps section is equivalent to the script section of an individual job. This is a simple YAML array with each line representing an individual command to be run:

  1. my_job:
  2.   script:
  3.     - echo "hello! the current time is:"
  4.     - time
  5.   ...

Directives

environment

在 GitLab 中，我们使用variables关键字在运行时定义不同的变量. 这些也可以通过 CI / CD 设置下的 GitLab UI 进行设置. 另请参阅我们有关变量的一般文档 ，包括有关受保护变量的部分，该部分可用于将对某些变量的访问限制为某些环境或运行程序：

  1. variables:
  2.   POSTGRES_USER: user
  3.   POSTGRES_PASSWORD: testing_password

options

这里，存在与所讨论的对象本身相关联的用于不同事物的选项. 例如，与作业相关的选项是相对于作业本身定义的. 如果您正在寻找某个选项，则应该可以通过搜索完整的配置参考页面来找到它的位置.

parameters

GitLab 不需要您定义在开始手动作业时希望可用的变量. 用户可以提供他们喜欢的任何变量.

triggers / cron

Because GitLab is integrated tightly with Git, SCM polling options for triggers are not needed. We support an easy to use syntax for scheduling pipelines.

tools

GitLab 不支持单独的tools指令. 我们的最佳实践建议是使用预构建的容器映像，该映像可以缓存，并且可以构建为包含管道所需的工具. 可以设置管道以根据需要自动构建这些映像，并将它们部署到容器注册表中 .

如果您没有在 Docker / Kubernetes 上使用容器映像，例如在 Mac 或 FreeBSD 上，则shell执行程序确实需要您预先设置环境或作为作业的一部分. 您可以创建一个before_script动作来为您处理.

input

与parameters关键字类似，这是不需要的，因为始终可以为运行时变量条目提供手动作业.

when

GitLab 确实支持when关键字 ，用于指示在（或尽管发生）故障的情况下应在何时运行作业，但是大多数用于控制管道的逻辑都可以在我们功能非常强大的only/except规则系统中找到 （另请参见高级语法 ）：

  1. my_job:
  2.   only: [branches]