18.7.1 Jenkins与Git集成与触发策略

Jenkins与Git集成与触发策略#

导语
本节围绕 Jenkins 与 Git 的集成、触发策略与实战配置，提供可执行命令、配置示例、排错思路与练习。

---

1. 原理与架构草图#

---

2. 安装与插件准备（示例）#

（1）必要插件安装
在 Jenkins → Manage Jenkins → Plugins 安装：
- Git
- GitHub / GitLab / Gitee（按实际仓库类型）
- Pipeline
- Multibranch Pipeline

（2）Linux 环境安装 git（示例）

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y git

# CentOS/RHEL
sudo yum install -y git

命令说明：
- apt-get install -y git：安装 Git 客户端，Jenkins 拉取代码依赖。

---

3. 凭据配置与仓库接入#

（1）添加 SSH 凭据
Jenkins → Manage Jenkins → Credentials → System → Global → Add Credentials
- 类型：SSH Username with private key
- Username：git
- Private Key：粘贴私钥

（2）示例：Jenkins 主机生成 SSH Key

ssh-keygen -t ed25519 -C "jenkins@ci.local"
# 生成后将 ~/.ssh/id_ed25519.pub 添加到 Git 平台

命令说明：
- ssh-keygen -t ed25519：生成 Jenkins 用于访问 Git 的密钥。

（3）测试 Git 连接

ssh -T git@github.com
# 预期输出：Hi <user>! You've successfully authenticated...

---

4. Pipeline 与 Git 触发配置示例#

（1）Jenkinsfile（Webhook + 分支/路径控制）

pipeline {
  agent any
  triggers {
    githubPush()
  }
  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }
    stage('Build') {
      when {
        branch 'main'
      }
      steps {
        sh 'echo "build on main"'
      }
    }
    stage('Test') {
      when {
        changeset "src/**"
      }
      steps {
        sh 'echo "run tests for src changes"'
      }
    }
  }
}

关键参数解释：
- githubPush()：GitHub Webhook 触发
- branch 'main'：仅 main 分支执行构建
- changeset "src/**"：仅 src 目录变更触发测试

（2）多分支流水线
配置 Multi-branch Pipeline，Jenkins 会自动扫描分支并检测 Jenkinsfile。
- 分支过滤：main|develop|release/.*
- Jenkinsfile 路径：Jenkinsfile（默认）

---

5. Webhook 配置示例#

GitHub Webhook URL 示例

http://jenkins.example.com/github-webhook/

GitLab Webhook URL 示例

http://jenkins.example.com/project/myjob

验证方式
- Jenkins → 构建历史查看是否触发
- Git 平台 Webhook 日志查看返回 200

---

6. 轮询触发示例（Poll SCM）#

适用于无法使用 Webhook 的场景。

pipeline {
  agent any
  triggers { pollSCM('H/5 * * * *') }
  stages {
    stage('Checkout') {
      steps { checkout scm }
    }
    stage('Build') {
      steps { sh 'make build' }
    }
  }
}

说明：
- H/5 * * * *：每 5 分钟轮询一次，可能增加 Jenkins 负载。

---

7. 常见排错与定位命令#

问题1：Webhook 无触发
- 检查回调 URL 是否可达：

curl -I http://jenkins.example.com/github-webhook/

• Jenkins 系统日志：
• Manage Jenkins → System Log
• 或查看 jenkins.log

问题2：SSH 权限拒绝

ssh -vvv git@github.com

说明：
- -vvv 输出详细握手过程，定位密钥与权限问题。

问题3：仓库拉取失败

git ls-remote git@github.com:org/repo.git

说明：
- 快速验证 Jenkins 凭据是否可读取仓库。

---

8. 练习任务#

1. 配置一个 Git 仓库与 Jenkins 多分支流水线，提交 Jenkinsfile 后观察自动创建分支 Job。
2. 将 src/ 目录修改触发测试阶段，修改 docs/ 目录不触发测试。
3. 将 Webhook 改为轮询触发，比较构建触发延迟。

---

9. 最佳实践#

• Webhook 优先，轮询仅作为兜底
• Jenkinsfile 与代码同库维护，便于审计
• 使用分支/路径过滤减少无效构建
• 凭据最小权限，避免泄露与误操作