作业设置 | TeamCity On-Premises 文档

编辑作业设置

要查看和编辑作业设置，请点击右上角的设置切换，然后点击任意作业图块（或点击“添加”图块以创建新作业）。

您还可以从可视化编辑器切换到代码，直接编辑标记。

步数

使用本节可以定义作业所执行的操作，例如构建与测试项目、运行自定义脚本、上传 Docker 镜像等。

目前，管道支持四种类型的可添加步骤。这些都是对应经典构建配置步骤的轻量版本。

脚本

这是一个通用步骤，可直接在代理机器终端中执行命令。因此，您可以与安装在代理上的任何工具进行交互：cURL、Python、MSBuild、Homebrew 等。

例如，以下步骤会下载由目标构建配置生成的工件：

jobs:
  Job1:
    name: Job 1
    steps:
      - type: script
        script-content: >-
          curl --location
          'https://example.com/app/rest/builds/buildType:BuildConfigID/artifacts/archived/?locator=pattern%3A*.zip'
          \
          --header 'Content-Type: application/zip' \
          --header 'Accept: application/zip' \
          --header 'Authorization: Bearer %bearer-token%' \
          --output output.zip \
          --data ''
    files-publication:
      - path: output.zip
        share-with-jobs: true
        publish-artifact: true
secrets:
  bearer-token: credentialsJSON:12e5c38b-16a1-4201-a913-5b5411bd7bfe

   

Gradle

此步骤专为与 Gradle 构建工具交互而构建，可以用于构建、测试和打包 Java、Kotlin、Groovy、Scala、Swift 等项目。

name: Gradle Project
jobs:
  Job1:
    name: 'Job 1: Gradle Build'
    steps:
      - type: gradle
        tasks: clean build -x test
        use-gradle-wrapper: 'true'
  Job1_2:
    name: 'Job 2: Test Suite 1'
    runs-on: Linux-Medium
    steps:
      - type: gradle
        working-directory: test1
        tasks: clean test
        build-file: build.gradle
        use-gradle-wrapper: 'true'
    dependencies:
      - Job1

   

Maven

Maven 构建步骤旨在使用 Apache Maven处理 Java、Kotlin、Groovy 等项目。

jobs:
  Job1:
    name: Job 1
    steps:
      - type: maven
        maven-version: bundled_3_6
        pom-location: pom.xml
        goals: '-B -DskipTests clean package'
        jdk-home: '%env.JDK_21_0%'

   

优化

本节介绍可显著加快 Pipeline 运行速度的设置，从而节省时间、资源，对于云代理还能节省基础架构成本。

并行测试 — 允许 Maven 和 Gradle 步骤将测试套件拆分为多个批次，在不同构建代理上并行启动 N 个虚拟构建。
TeamCity 根据测试所属类或测试用例将其分组为批次，因此实际批次数可能少于指定数量。例如，单个大型测试类中的测试无法有效拆分。有关 TeamCity 如何选择和运行测试批次的详细信息，请参阅此构建配置文章：并行测试。
重用作业结果 — 如果所有启用的仓库中没有新更改，TeamCity 将跳过重新运行该作业，并重用先前运行中的工件、状态和结果。这样可确保仅执行受最近更改影响的作业。
有关 TeamCity 如何识别可重用构建的信息，请参阅本文：适合的构建。
重用的作业将在 UI 中明确标记，以避免混淆。
请注意上方的“优化”图块：TeamCity 此次运行速度几乎比上次快 5 倍，重用运行节省了约 80% 的时间。

Agent Requirements（代理要求）

TeamCity 会自动跟踪代理软件，以确保仅将排队的运行分配给兼容的代理。例如，如果 Maven 步骤必须在容器中运行，则不安装 Docker 或 Podman 的代理将被标记为不兼容。

同样，如果作业使用了未在 pipeline或 job参数部分中定义的参数，TeamCity 会将代理计算机视为该参数值的最后可能来源。例如，如果命令行步骤运行 echo %myParam% 时引用了未知参数，则仅参数 "myParam" 不为空的代理可以运行该作业。

代理要求部分允许您为符合条件的代理定义附加条件，如名称、硬件规格或已安装的工具。

TeamCity 会显示适用于大多数基本代理硬件要求的预设选项：CPU 核心数、代理内存总量及 CPU 架构。

点击添加自定义要求以定义您自己的要求。每个要求都是一个 <agent.parameter> <运算符> [值] 表达式。 TeamCity 会针对每个已授权代理计算这些表达式，并将返回 "true" 的代理标记为符合条件，其他代理标记为不兼容。

代理参数

代理计算机报告的一个参数，其值必须符合所需条件。以下是一些常见代理参数示例：

teamcity.agent.jvm.os.arch — 报告代理计算机的架构。例如，对于在 Apple ARM 设备上运行的 macOS 代理，结果为 aarch64。
env.ANDROID_SDK_HOME — 返回代理计算机上 Android SDK 的安装路径。例如， /home/builduser/android-sdk-linux。
teamcity.agent.jvm.user.timezone — 存储代理计算机的时区。例如， Etc/UTC。
MonoVersion — 返回 Mono 平台的版本信息。例如， 6.12.0.200。

导航至代理 | <TeamCity_Agent> | 代理参数选项卡，查看代理报告的参数，并查找存储硬件和软件数据的参数。

另见：预定义构建参数列表。

运算符

用于将实际代理参数值与给定值进行比较的逻辑运算符。例如，“小于”、“以...开头”、“包含”等。

另请参阅：需求条件

价值

要与代理参数值进行比较的自定义值。唯一不需要值的运算符是 exists ，用于检查代理是否报告了所需的参数，无论其实际值为何。

以下 YAML 示例定义了三个要求：16 GB 的 RAM、至少 10 GB 的可用磁盘空间，以及已安装的 Python 3。标准 TeamCity 要求使用较简洁的 别名：值 语法，自定义要求则使用完整的 <参数> <运算符> [值] 表达式（并带有用于公共标题的额外 名称 参数）。

jobs:
  Job1:
    name: Sample job
    steps:
      - type: script
        script-content: cat artifact.txt
    runs-on:
      self-hosted:
        - ram: 16GB
        - requirement: more-than
          name: Free disk space
          parameter: teamcity.agent.work.dir.freeSpaceMb
          value: '10240'
        - requirement: exists
          name: Python
          parameter: python3.executable

  

参数

参数是名称－值对，用于将原始值替换为引用。当 TeamCity 遇到参数引用（%\形参名称% ）时，会将其替换为实际的参数值。

TeamCity 支持两种参数层级：pipeline 参数和 job 参数。

管道参数旨在在该 pipeline 拥有的任何单独作业中访问。
jobs: Job1: name: Job 1 steps: - type: script script-content: echo %pipeline-param1% Job2: name: Job 2 dependencies: - Job1 steps: - type: script script-content: echo %pipeline-param2% parameters: pipeline-param1: foo pipeline-param2: bar
通常，这些是配置参数（不带 env. 名称前缀），主要用于存储多个作业共用的值或快速更改全局 pipeline 设置。
作业输入参数通常是环境变量（具有 env. 名称前缀），仅对该特定作业可用。若要将此值传递给其他作业，您需要在 output parameter 中引用它们。

以下示例展示了一个 pipeline 级别的 secret 参数 bearer_token ，以及一个作业级别的环境变量 env.SERVER_URL ，它们被用于命令行步骤中。请注意，具有 env. 前缀的参数可以通过常规 TeamCity %param_name% 语法引用，或在脚本中以原生代理变量（$param_name ）的形式访问。

jobs:
  Job1:
    name: Get all TeamCity builds
    steps:
      - type: script
        script-content: |-
          echo "Server URL is: %env.SERVER_URL%"
          curl -X GET "$SERVER_URL/builds" \
            -H "Accept: application/json" \
            -H "Authorization: Bearer %bearer-token%"
    parameters:
      env.SERVER_URL: https://example.com/app/rest
secrets:
  bearer-token: credentialsJSON:12e5c38b-16a1-4201-a913-5b5411bd7bfe

  

输出

本节说明作业如何共享其运行结果，包括计算得出的值与生成的文件。

文件

作业共享的文件可以作为工件、供下游作业使用的内部文件，或者两者兼而有之。

工件

工件是在运行结果页面的工件选项卡中显示的文件。具有查看项目权限的用户可以将这些文件下载到本地存储。

共享文件

共享文件将沿 pipeline 向下传递到后续作业。这些通常是内部文件或尚未完成的文件。无论哪种情况，它们都不应出现在工件选项卡上。

下面的 YAML 示例展示了一个作业创建并修改文件，然后另一个作业导入该文件并打印其内容。 “作业 2” 接着将该文件发布为工件。

jobs:
  Job1:
    name: Create file
    steps:
      - type: script
        script-content: |-
          touch sample.txt
          echo "File created by Job 1, build #%tc.build.number%" >> sample.txt
    files-publication:
      - path: sample.txt
        share-with-jobs: true
        publish-artifact: false
  Job2:
    name: Print file contents
    dependencies:
      - Job1
    steps:
      - type: script
        script-content: cat sample.txt
    files-publication:
      - path: sample.txt
        share-with-jobs: false
        publish-artifact: true

     

这两种类型并不互斥：添加输出文件时，您可以同时勾选共享文件和工件复选框。

输出参数

作业可以处理两种类型的参数：输入和输出。

输入参数是在作业运行期间使用的名称–值对。有关更多信息，请参阅参数部分。
输出参数用于存储作业在 pipeline 中向下传递给其他作业的值。

输出参数被设计为独立的实体，以防止跨 pipeline 出现意外的失败。例如，如果“作业 A”中变更（或移除）了一个参数，而“作业 B”依赖它，那么“作业 B”可能会被意外破坏。通过将参数标记为输出，TeamCity 表示该参数可能在其他地方使用，因此在更改之前应检查其依赖项，以避免意外。

以下 YAML 示例定义了一个包含两个作业的 pipeline，用于说明此概念：

作业 1 使用 env.INPUT 参数计算一个值。
作业的脚本通过发送 setParameter service message 将该值写入 result_param 输入参数。 .
然后，该参数被映射到 output_param 输出参数。
作业 2 使用 job.<source_job_ID>.<output-parameter-name> 语法获取此输出参数。

jobs:
  Job1:
    name: Calculate value
    steps:
      - type: script
        script-content: |-
          RESULT=$((%env.INPUT% * 2))
          echo $RESULT
          echo "##teamcity[setParameter name='result_param' value='$RESULT']"
    parameters:
      env.INPUT: '5'
      result_param: ''
    output-parameters:
      output_param: The calculated value is %result_param%
  Job2:
    name: Use calculated value
    dependencies:
      - Job1
    steps:
      - type: script
        script-content: echo %job.Job1.output_param%

   

通过遵循此模式，您可以将仅在作业中使用的参数与在 pipeline 中显式共享的参数区分开来。

存储库

本节允许您选择该作业应签出哪些远程仓库。要添加仓库，请在仓库部分中创建一个新条目，位于 pipeline settings 中。

默认情况下，源代码将签出至代理工作目录的一个子文件夹中。为确保代理在运行其他作业时不会频繁丢失某个作业的源代码，该子文件夹的名称是自动生成的，并对每个作业唯一（例如， /mnt/agent/work/6fa95896c6cadf54）。

您可以通过存储库部分项的相应选项，指定用于签出源代码的自定义目录。签出目录的路径可以是绝对路径，但强烈建议使用相对路径（MyCustomFolder ）或引入预定义 TeamCity 参数的路径（%teamcity.agent.work.dir%/MyCustomFolder）。

 Job1:
    name: Job 1
    repositories:
      - main:
          path: MainRepo # Custom checkout directory (relative path)
          enabled: true
      - https://github.com/Johndoe/MySampleApp:
          path: ''' # Default value, will use a directory that matches the repository name
          enabled: true

  

下图概述了构建过程中涉及的核心目录之间的关系。

请参阅以下文章以了解更多信息：

Agent Home Directory（代理主目录）—— 构建代理的安装目录。
Agent Work Directory（代理工作目录）—— 构建代理主目录中的子文件夹，用于存储构建相关文件。
Build Checkout Directory（构建检出目录）—— 构建代理工作目录中的子文件夹，用于存放所有签出的源代码。
Build Working Directory（构建工作目录）—— 构建步骤开始所使用的目录（默认等于“构建签出目录”）。

集成

pipeline 和作业设置面板都包含一个集成部分，用于连接私有 Docker 和 NPM 注册表。

在 pipeline 设置中，您可以管理作业可用集成的完整列表。
在作业设置中，开关允许您选择该作业应自动登录哪些注册表，从而确保构建步骤能够访问所需数据。

传统 TeamCity 构建配置通过“连接 + 构建功能”组合支持此功能：

Docker Registry 连接与 Docker 注册表连接 Docker 构建功能。
NPM Registry 连接与相关构建功能，用于 Node.js 注册表。

如果某个项目中已有 Docker 或 NPM 连接，则该 pipeline 会在其“集成”部分下显示该连接。

这些继承的集成无法直接通过 pipelines 设置面板编辑，您需要在项目设置中修改其源连接。