Jenkins GitHub Pipeline

适用于 GitHub 私有仓库 / 公有仓库，任何语言项目均可复用。

1. GitHub -> Jenkins Webhook 配置（自动触发构建）

🔹 Step 1：在 Jenkins 获取 Webhook 地址

访问：

http://<JENKINS_URL>/github-webhook/

示例：

https://documents.v2ep.com/jenkins/github-webhook/

🔹 Step 2：到 GitHub Repository 设置

进入 GitHub Repo：

Settings -> Webhooks -> Add webhook

填写：

Payload URL：https://documents.v2ep.com/jenkins/github-webhook/
Content type：application/json
Secret：可留空 or 填一个字符串
Events：Just the push event（推荐）或 Send me everything

点击 Add webhook。

2. Jenkins 侧配置 GitHub 认证

使用 Personal Access Token（PAT）

（建议最常用）

GitHub -> Settings -> Developer settings -> Tokens (classic) -> Generate new token -> Generate new token (classic)

Expiration:

No expiration

Select scopes（权限）：

repo
workflow（可选）
admin:repo_hook（管理 webhook）

生成 Token 后，到 Jenkins：

Jenkins -> Manage Jenkins -> Security -> Credentials -> (global) -> Add Credentials
Kind: Username with password (不要选择 Secret Text !!!)
Scope: Global (Jenkins, nodes, items, all child items, etc)
Username: septvean
Password: xxx
ID: github-user-septvean

3. Jenkins 任务配置（Multibranch Pipeline）

⭐ 企业推荐一定使用 Multibranch Pipeline，而不是单任务 Pipeline。

优势：

自动识别 GitHub 分支
自动识别 PR
每个分支单独流水线
自动扫描新分支并构建

创建 Multibranch Pipeline

Jenkins -> New Item -> Multibranch Pipeline

Enter an item name：Documents
Select an item type：Multibranch Pipeline

配置（Configure the project）：

🔹 Display Name：Documents

🔹 Branch Source -> GitHub

Credentials：github-user-septvean
Repository HTTPS URL：https://github.com/septvean/documents.git

4. Jenkinsfile 配置（最标准版）

以下是一个通用、所有语言都适用的 Jenkinsfile 基础模板。

✅ Jenkinsfile（企业标准模板）

pipeline {
    agent any

    triggers {
        githubPush()   // <- Webhook 入口
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }

        stage('Test') {
            steps {
                sh 'echo "Running tests..."'
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                sh 'echo "Deploying to production..."'
            }
        }
    }

    post {
        always {
            echo "Build finished."
        }
        failure {
            echo "Build failed!"
        }
    }
}

5. 高级 Jenkinsfile（含 Docker 构建 + 推送 + K8s 部署）

如果你项目需要容器化，可使用以下模板：

✅ Jenkinsfile（Docker + GitHub）

pipeline {
    agent { label 'docker' }

    triggers {
        githubPush()
    }

    environment {
        REGISTRY = "ghcr.io/<your_username>/<project>"
        IMAGE_TAG = "${BUILD_NUMBER}"
    }

    stages {
        stage('Checkout') {
            steps { checkout scm }
        }

        stage('Build Docker') {
            steps {
                sh """
                docker build -t $REGISTRY:$IMAGE_TAG .
                docker push $REGISTRY:$IMAGE_TAG
                """
            }
        }

        stage('Deploy K8s') {
            when { branch 'main' }
            steps {
                sh """
                kubectl set image deploy/myapp myapp=$REGISTRY:$IMAGE_TAG
                kubectl rollout status deploy/myapp
                """
            }
        }
    }
}

6. GitHub Pull Request 构建（PR Build）

Multibranch Pipeline 默认支持：

PR opened
PR updated
PR synchronized

自动触发构建。

PR 构建时自动使用分支变量：

CHANGE_ID
CHANGE_URL
CHANGE_AUTHOR

在 Jenkinsfile 中加：

when {
    changeRequest()
}

示例：

stage('PR Test') {
    when { changeRequest() }
    steps {
        echo "Testing Pull Request #${CHANGE_ID}"
    }
}

7. 常见配置坑（非常重要）

❌ 1. Webhook 不触发

原因：

GitHub 无法访问 Jenkins（需要公网）
Jenkins URL 配置错误
GitHub 403（Token 权限不足）
Job 不是 Multibranch Pipeline（Freestyle 无法 auto-scan）

解决方式：

打开 GitHub -> Webhooks -> Recent Deliveries -> 查看 Response

应为：

HTTP 200

❌ 2. GitHubToken 403

PAT 必须启用：

repo
admin:repo_hook

❌ 3. Jenkinsfile 不生效

检查：

分支不是 main -> 使用 branch indexing
Jenkinsfile 名称必须是 Jenkinsfile

❌ 4. 内网 Jenkins 无法被 GitHub 调用

方案：

使用 Cloudflare Tunnel（推荐）
使用 frp（内网穿透）
使用公网 Nginx -> Proxy 到 Jenkins

8️⃣ 额外：GitHub -> Jenkins 环境变量（非常有用）

Jenkins 自动提供 GitHub 环境变量：

变量	说明
GIT_BRANCH	当前构建分支
GIT_COMMIT	提交 SHA
GIT_PREVIOUS_COMMIT	上一次构建的提交
CHANGE_ID	PR 编号
CHANGE_AUTHOR	PR 作者