Job's Done

关于

Job's Done是一个深受Travis启发的工具，它以相同的方式工作，即在存储库根目录中配置.jobs_done.yaml文件以创建和触发持续集成作业。

.jobs_done.yaml文件的示例

matrix:
  platform:
  - "win64"
  - "redhat64"

platform-win64:build_batch_commands:
- |
  python -m venv .env3   || goto eof
  call .env3\Scripts\activate   || goto eof
  pytest --junitxml=tests-{platform}.xml

platform-redhat64:build_shell_commands:
- |
  python3 -m venv .env3
  source .env3/bin/activate
  pytest --junitxml=tests-{platform}.xml

junit_patterns:
- "tests.*.xml"

假设此文件位于存储库根目录myproject中，并已推送到分支feat-71，这将生成两个Jenkins作业

• myproject-feat-71-win64
• myproject-feat-71-linux64

命令行

已完成的任务可以在命令行中执行。

要使用它，从您想要创建作业的存储库文件夹中执行

$ jobs_done jenkins --username USER https://example.com/jenkins

这将创建/更新现有作业。

以下是可能的安装选项。

PyPI

1. 使用Python 3.10创建虚拟环境并激活它

   $ python -m venv .env
   $ .env\Scripts\activate  # Windows
   $ source .env/bin/activate  # Linux
   

2. 安装jobs_done10

   $ pip install jobs_done10
   

开发

1. 克隆仓库

   git clone git@github.com:ESSS/jobs_done10.git
   cd jobs_done10
   

2. 使用Python 3.10创建虚拟环境并激活它

   $ python -m venv .env
   $ .env\Scripts\activate  # Windows
   $ source .env/bin/activate  # Linux
   

3. 以可编辑模式安装依赖项和项目

   $ pip install -r requirements.txt -e .
   

升级依赖项

我们使用pip-tools来锁定版本，按照文档中的说明添加新库或更新现有版本，使用--extra dev来包含开发依赖项。

服务器

jobs done在jobs_done10.server中包含一个flask服务器，可以使用Docker进行部署。

它提供了两个端点用于PUSH和GET

• /stash：专门用于接收BitBucket Server（以前称为Stash）的推送事件。
• /github：专门用于接收GitHub的推送事件。重要：webhook必须配置为application/json的内容类型和secret。

对任一端点的GET请求将返回JobsDone版本，这有助于检查安装的版本以及端点是否正确。

向/发送的请求与向/stash发送的请求相同，以保持向后兼容（可能在未来被移除）。

配置

通过在仓库根目录下创建一个.env文件（由python-dotenv提供）进行配置，其中包含以下变量

JD_JENKINS_URL=https://example.com/jenkins
JD_JENKINS_USERNAME=jenkins-user
JD_JENKINS_PASSWORD=some password

JD_STASH_URL=https://example.com/stash
JD_STASH_USERNAME=stash-user
JD_STASH_PASSWORD=some password

JD_GH_TOKEN=github-user-personal-access-token
JD_GH_WEBHOOK_SECRET=webhook-secret

JD_EMAIL_USER=mail-sender@example.com
JD_EMAIL_FROM=JobsDone Bot <mail-sender@example.com>
JD_EMAIL_PASSWORD=email password
JD_EMAIL_SERVER=smtp.example.com
JD_EMAIL_PORT=587

构建

克隆仓库并检出标签

$ git clone https://github.com/ESSS/jobs_done10.git
$ cd jobs_done10
$ git checkout <VERSION>

构建Docker镜像

$ docker build . --tag jobsdone:<VERSION> --build-arg SETUPTOOLS_SCM_PRETEND_VERSION=<VERSION>

运行服务器

$ docker run --publish 5000:5000 jobsdone:<VERSION>

Hello World

这是一个Job's Done文件的示例，以及您可能期望其内容。

build_batch_commands:
- "echo MESSAGE: Hello, world!"

description_regex: "MESSAGE\\:(.*)"

将此文件添加到连接到我们的CI系统的仓库中，将创建一个单独的作业，当执行时运行Windows批处理命令，然后稍后捕获回显的消息并将其设置为构建描述。

测试

这是一个包含测试的简单应用程序示例

build_batch_commands:
- "pytest --junitxml=pytest_results.xml"

junit_patterns:
- "pytest_results.xml"

此作业在仓库中运行pytest并将测试结果输出到文件。我们还配置了作业以查找该文件，并在构建结束时向我们展示测试结果。

多个平台

与上述相同的程序，但现在在多个平台上运行。

platform-win64:build_batch_commands:
- "pytest --junitxml=pytest_results-{platform}.xml"

platform-redhat64:build_shell_commands:
- "pytest --junitxml=pytest_results-{platform}.xml"

junit_patterns:
- "pytest_results.*.xml"

matrix:
  platform:
  - "win64"
  - "redhat64"

在这里，我们添加一个matrix部分来定义此作业的变体。在这种情况下，我们有平台变量，有两个可能的值，win64和redhat64。

将为矩阵中的每个可能的组合创建一个作业（在这种情况下，只有两个作业）。

由于我们无法在Linux上运行批处理命令，我们添加了另一个构建器部分build_shell_commands。使用一些标志定义部分之前，我们可以选择每个作业中将可用哪些部分。

矩阵中的值也可以用作变量，在这种情况下，{platform}将被替换为该作业中使用的平台（win64或redhat64）。

分支模式

分支模式用于过滤哪些分支将产生作业。此正则表达式列表（使用Python语法）确保只有当至少一个正则表达式与分支名称匹配时，分支才会产生作业。

以下是一个仅过滤master和功能分支的示例

branch_patterns:
- "master"
- "fb-*"

如果该文件中没有定义此部分，则所有分支都将产生作业。

作业矩阵

如上例所示，作业矩阵可以用于创建作业的多个变体。为此矩阵中的每个条目组合创建一个作业。

matrix:
  mode:
  - "app"
  - "cases"
  platform:
  - "win64"
  - "linux64"

在这种情况下，将生成4个作业

• app-win64
• app-linux64
• cases-win64
• cases-linux64

请注意，您可以使用所需的任何变量，Job's done不知道mode或platform的含义。

存在一个可以用来从矩阵中删除特定条目的exclude子句。

matrix:
  mode:
  - "app"
  - "cases"
  platform:
  - "win64"
  - "linux64"

mode-cases:platform-win.*:exclude: "yes"

这将排除所有来自Windows的作业案例。

字符串替换

在作业矩阵中定义的变量可以用来替换作业文件中的字符串。

除了矩阵变量之外，还有一些特殊字符串模板可以在任何作业中使用。

• name - 仓库的名称
• branch - 正在构建的分支

matrix:
  platform:
  - "win64"
  - "linux64"

platform-win.*:build_batch_commands:
- "echo Building project {name} in branch {branch} on platform {platform}"

注意，我们使用Python的格式语法，因此如果需要实际的{或}，请使用双大括号：{{，}}。

条件标志

在您的作业矩阵中定义的变量还可以用来控制作业文件中的一些内容。一个常见的例子是使用不同的构建器为Windows（bash）和Linux（shell）。

这是通过在YAML文件的部分添加前缀，并包含变量名和值来实现的，以便使用它

platform-win.*:build_batch_commands:
- "dir ."

platform-linux.*:build_shell_commands:
- "ls -la ."

matrix:
  platform:
  - "win32"
  - "linux64"

矩阵变量还可以定义别名，这对于使用这些标志时减少重复非常有用。要添加别名，只需使用逗号分隔矩阵值的附加名称即可

platform-windows:build_batch_commands:
- "dir ."

platform-linux:build_shell_commands:
- "ls -la ."

matrix:
  platform:
  - "win32,windows"
  - "win64,windows"
  - "linux64,linux"

除此之外，您还可以使用一个始终可用的特殊变量branch，它指向您的分支

branch-master:build_batch_commands:
- "echo Build"

branch-deploy:build_batch_commands:
- "echo Build + Deploy"

条件值可以使用Python正则表达式语法来提供额外的灵活性

branch-master:build_batch_commands:
- "echo Build"

branch-fb.*:build_batch_commands:
- "echo Feature branch!"

branch-rb.*:build_batch_commands:
- "echo Release branch!"

开发

创建虚拟环境并在开发模式下安装它

$ python -m virtualenv .env36
$ source .env36/bin/activate
$ pip install -e .

运行测试

$ pytest src

部署

打开一个更新CHANGELOG的PR，在其通过后，将标签推送到仓库。

这将自动将其发布到PyPI以及组织配置的Docker Registry。

所有选项

additional_repositories

此作业中将签出的附加仓库。

默认情况下包含此.jobs_done文件的仓库。

需要多个SCM插件和Git插件。

使用与git相同的选项。

additional_repositories:
- git:
    url: "https://project.git"
    branch: "{branch}"

auth_token

用于远程触发构建的作业认证令牌。

auth_token: "my_token"

boosttest_patterns

要查找测试结果的boosttest文件模式列表。

需要xUnit插件。

boosttest_patterns:
- "*.xml"

branch_patterns

用于匹配分支名称的正则表达式列表。只有匹配这些之一分支将创建作业。

branch_patterns:
- "master"
- "fb-*"

build_batch_commands

用于构建作业的Windows批处理命令列表。如果任何命令的errorcode不是0，则构建失败。

build_batch_commands:
- "pytest src"
- "echo Finished"

build_shell_commands

用于构建作业的shell命令列表。如果任何命令的errorcode不是0，则构建失败。

build_shell_commands:
- "pytest src"
- "echo Finished"

build_python_commands

用于构建作业的python命令列表。

需要Python插件。

build_python_commands:
- "print(5)"

console_color

启用对ANSI转义序列的支持，包括颜色，并将其输出到控制台。

需要AnsiColor插件。

接受值

• xterm（默认）
• vga
• css
• gnome-terminal

console_color: "css"

coverage

启用代码覆盖率报告。

需要Cobertura插件。

选项

• report_pattern：必选，搜索XML覆盖率文件的模式。这些XML文件通常在Cobertura格式中，该格式也是pytest-cov XML输出（因为pytest-cov使用了覆盖率库）。
• healthy：可选，指定所需的方法、行和条件指标。省略的任何指标默认为80。
• unhealthy：可选，指定所需的方法、行和条件指标。省略的任何指标默认为0。低于这些阈值的构建将被标记为不健康。
• failing：可选，指定所需的方法、行和条件指标。省略的任何指标默认为0。低于这些阈值的构建将被标记为失败。

coverage:
  report_pattern: "**/build/coverage/*.xml"
  healthy:
    method: 100
    line: 100
    conditional: 90
  unhealthy:
    method: 95
    line: 95
    conditional: 85
  failing:
    method: 90
    line: 90
    conditional: 80

cron

定期运行的构建计划。

cron: |
  # Everyday at 22pm
  * 22 * * *

custom_workspace

为作业定义一个自定义工作空间目录。为了保持与默认工作空间目录相同的基目录，请在前面添加 "workspace/"。

custom_workspace: "workspace/devspace-user"

description_regex

用于在作业输出中搜索描述的正则表达式。如果找到匹配项，则将第一个组的内容设置为描述。

需要 描述设置插件。

description_regex: "OUTPUT: (.*)"

display_name

配置作业的显示名称。

display_name: "{branch} {name}"

email_notification

为失败的构建发送电子邮件。

email_notification: "email1@example.com email2@example.com"

# or

email_notification:
  recipients: "email1@example.com email2@example.com"
  notify_every_build: true
  notify_individuals: true

exclude

从矩阵中排除作业。

platform-linux64:exclude: "yes"

git

主项目额外的git选项。

需要 Git 插件。

这里可用的选项与 additional_repositories 共享。

git:
  branch: master
  clean_checkout: false
  lfs: true
  recursive_submodules: true
  reference: "/home/reference.git"
  shallow_clone: 50
  tags: true
  target_dir: "main_application"
  timeout: 30
  url: "ssh://server/somerepo.git"

注意：默认情况下，tags 是 false，因为我们注意到获取标签需要相当长的时间，而我们也没有使用标签。如果需要标签，请将 tags 设置为 true。

jsunit_patterns

要查找测试结果的 jsunit 文件模式列表。

需要 JSUnit 插件。

jsunit_patterns:
- "*.xml"

junit_patterns

要查找测试结果的 junit 文件模式列表。

需要 xUnit 插件。

junit_patterns:
- "*.xml"

label_expression

配置作业的标签表达式。

标签表达式用于确定哪些工作节点可以运行作业。

label_expression: "{platform}"

matrix

配置作业的变体。

matrix:
  python:
  - "27"
  - "36"

notify_github

通知 GitHub 作业构建状态。

目前它不支持任何参数，使用默认值。

需要 GitHub 插件。

notify_github:

notify_stash

通知 Stash 实例作业构建状态。

当没有提供参数时，使用 Jenkins 实例中设置的配置。

需要 StashNotifier 插件。

notify_stash:
  url: "example.com/stash"
  username: "user"
  password: "pass"

# Using default from Jenkins
notify_stash:

parameters

Jenkins 作业的作业参数。

目前，只有 choice 和 string 已实现。

parameters:
  - choice:
      name: "PARAM_BIRD"
      choices:
        - "African"
        - "European"
      description: "Area where the bird is from"
  - string:
      name: "PARAM_VERSION"
      default: "dev"
      description: "App version"

scm_poll

定期轮询源代码管理器以查找更改并触发构建。

scm_poll: |
  # Everyday at 22pm
  * 22 * * *

slack

使用 Slack 配置通知。

1. 在 Slack 上配置您的 Jenkins 集成
2. 获取令牌
3. 使用此选项配置您的作业以通知 Slack。

slack:
  team: esss
  channel: dev
  token: XXX
  url: https://example.com/jenkins

timeout

作业超时时间（分钟）。

timeout: 60

timestamps

在控制台输出左侧显示时间戳。

需要 时间戳器插件。

timestamps:

trigger_jobs

当前作业完成后触发其他作业。参数是可选的。

trigger_jobs:
  names:
    - myrepo-{branch}-synthetic-{platform}
  condition: SUCCESS  # can be one of: SUCCESS, UNSTABLE, FAILED, ALWAYS. Defaults to SUCCESS.
  parameters:  # optional
    - PARAM1=VALUE1
    - PARAM2=VALUE2

warnings

配置 CI 作业中警告和静态分析的解析。

需要 警告插件。

warnings:
  console:
    - parser: Clang (LLCM based)
    - parser: PyLint
  file:
    - parser: CppLint
      file_pattern: *.cpplint
    - parser: CodeAnalysis
      file_pattern: *.codeanalysis