Jenkins

Jenkins 将交付工作组织为作业和 Pipeline。应将 Pipeline 存放在版本化的 Jenkinsfile 中，因为构建逻辑、应用代码和工具版本必须在同一审查流程下变更。

控制器、代理与工作区 #

控制器存储配置和构建记录、评估调度决策、提供用户界面并协调代理。构建不应在控制器上运行。代理提供一个或多个执行器；每个执行器一次只能运行一个 Pipeline 任务。标签描述 linux, arm64, or docker, and a Pipeline’s agent selection constrains where its workspace is allocated.

工作区是可变的检出和构建状态，而不是工件仓库。 Concurrent builds can receive distinct workspace paths, and an ephemeral agent can disappear after a stage. Publish outputs with archiveArtifacts, transfer small files between stages with stash and unstash, or upload release artifacts to a dedicated repository. Do not rely on files left by a previous build.

Agents should have only the tools, network paths, and credentials required by their labels. Ephemeral agents reduce cross-build contamination, but reproducible builds still require pinned container images, toolchains, plugins, and dependency inputs.

声明式与脚本式 Pipeline #

声明式 Pipeline 围绕 pipeline、agent、stages、steps、environment、options 和 post 提供经过验证的结构。脚本式 Pipeline 在 node 和其他 Pipeline 步骤中使用 Groovy 控制流。 Declarative script { ... } can contain an imperative section, but large scripted regions discard declarative validation and stage semantics. Put reusable policy in a versioned Shared Library rather than copying Groovy between repositories.

pipeline {
  agent { label 'linux && container' }
  options {
    timeout(time: 20, unit: 'MINUTES')
    disableConcurrentBuilds()
  }
  stages {
    stage('Test') {
      steps {
        retry(2) {
          sh './mvnw --batch-mode verify'
        }
      }
      post {
        always { junit 'target/surefire-reports/*.xml' }
      }
    }
    stage('Package') {
      steps {
        sh './mvnw --batch-mode package -DskipTests'
        archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
      }
    }
  }
  post {
    always { deleteDir() }
  }
}

Pipeline 步骤会持久化执行状态，使持久任务能够经受控制器重启，但外部命令仍必须能够安全重启。 Use timeout to bound stalled work and retry only for operations known to be idempotent. Deployment retries can duplicate side effects. parallel reduces latency when branches do not mutate the same workspace or external resource; use separate workspaces or agents when isolation is required.

凭据与最小权限 #

将密钥存储在 Jenkins 凭据中，并在尽可能小的作用域内绑定：

withCredentials([file(credentialsId: 'registry-token-file',
                      variable: 'REGISTRY_TOKEN_FILE')]) {
  sh 'registry-client --token-file "$REGISTRY_TOKEN_FILE"'
}

掩码可以减少日志意外泄露，但无法保护密钥免受 untrusted build code running in the same scope. Avoid Groovy interpolation of string secrets because the value can enter process arguments or Jenkins-generated scripts before masking. File credentials supply a temporary protected file, but untrusted code in the same build context can still read it. Restrict credential IDs by folder, isolate untrusted pull requests from deployment jobs, and grant agents short-lived credentials for one environment.

运行 Pipeline #

使用多分支作业或受信任的 Webhook，将执行关联到确切的提交。 Preserve test reports and immutable artifacts according to a retention policy. Configure post actions for cleanup and notifications even when a stage fails. Protect the controller with authentication and authorization, review plugin updates as controller code, back up JENKINS_HOME, and keep build agents outside the controller’s trust boundary.