-
Git
Git
官网地址：
Git
git 插件为 Jenkins 项目提供了基本的 git 操作。它可以轮询、获取、签出、分支、列出、合并、标记和推送存储库。
Pipelines
git 插件提供了一个 SCM 实现，用于 Pipeline SCM
checkout step
。
Pipeline Syntax Snippet Generator
引导用户选择签出选项。
Multibranch Pipelines
git 插件包括用于 Jenkins
Multibranch Pipelines
和 Jenkins
Organization Folders
的多分支提供程序。git 插件多分支提供程序是使用命令行 git 的 “基本实现”。当 git 提供者可用时，用户应该更喜欢其 git 提供者的多分支实现。特定 git 提供者的多分支实现可以使用 REST API 调用来改善 Jenkins 体验并添加其他功能。多分支实现可用于 GitHub、Bitbucket、GitLab、Gitea 和 Tuleap。
git 插件包括 Jenkins Multibranch Pipelines 和 Jenkins Organization Folders 的多分支提供程序。git 插件多分支提供程序是使用命令行 git 的“基本实现”。当一个可用的时候，用户应该更喜欢他们的 git 提供者的多分支实现。特定 git 提供者的多分支实现可以使用 REST API 调用来改善 Jenkins 体验并添加其他功能。多分支实现可用于
GitHub
、
Bitbucket
、
GitLab
、
Gitea
和
Tuleap
。
Git Credentials Binding
git 插件提供
Git Username and Password
绑定，允许在管道作业中使用命令行 git 通过
HTTP
和
HTTPS
协议进行经过身份验证的 git 操作。
git 凭据绑定可以通过
Credentials Binding
插件的
withCredentials
步骤进行访问。绑定从
Credentials
插件检索凭据。
Git Username and Password Binding
此绑定在管道作业中使用命令行 git 通过
HTTP
协议提供身份验证支持。
Procedure
-
单击管道语法片段生成器并选择
withCredentials
步骤，添加 Git 用户名和密码绑定。 - 选择所需的凭据和 Git 工具名称，具体到生成的管道代码段。
使用了两个变量绑定，
GIT_USERNAME
和
GIT_PASSWORD
，将用户名和密码传递给管道作业的
withCredentials
块内的
sh
、
bat
和
powershell
步骤。即使使用
JGit
或
JGit with Apache HTTP Client
git 实现，变量绑定也可用。
Shell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
sh 'git fetch --all'
}
Batch example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
bat 'git submodule update --init --recursive'
}
Powershell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
powershell 'git push'
}
Configuration
Repositories
git 插件从一个或多个远程存储库中获取提交，并在代理工作区中执行签出。存储库及其相关信息包括：
Repository URL
远程存储库的 URL。git 插件将远程存储库 URL 传递给 git 实现（命令行或 JGit）。有效的存储库 URL 包括
https
、
ssh
、
scp
、
git
、
local file
和其他形式。
git documentation
中描述了有效的存储库 URL 表单。
Credentials
凭据是使用 Jenkins
credentials plugin
定义的。它们从下拉列表中选择，其标识符存储在作业定义中。有关支持的凭据类型的更多详细信息，请参阅
using credentials
。
Name
Git 使用一个短名称来简化用户对远程存储库 URL 的引用。默认的短名称是
origin
。可以分配其他值，然后在整个作业定义中使用这些值来引用远程存储库。
Refspec
refspec
将远程分支映射到本地引用。它定义了将从远程存储库提取到代理工作区的分支和标记。
refspec
定义了将被检索的远程引用以及它们如何映射到本地引用。如果留空，它将默认为正常的
git fetch
行为，并将检索所有分支。在大多数情况下，这种默认行为就足够了。
默认
refspec
是
+refs/heads/*:refs/remotes/REPOSITORYNAME/
其中
REPOSITORYNAME
是您在上述存储库
Name
字段中指定的值。默认
refspec
检索所有分支。如果 checkout 只需要一个分支，那么更严格的
refspec
可以减少从远程存储库到代理工作区的数据传输。例如：
+refs/heads/master:refs/remotes/origin/master
将仅检索 master 分支，而不检索其他分支。
refspec
可以与
advanced clone behaviors
行为中的
Honor refspec on initial clone
选项一起使用，以限制映射到本地引用的远程分支的数量。如果未启用
Honor refspec on initial clone
，则为其初始获取提供默认
refspec
。这保持了与以前行为的兼容性，并允许作业定义决定是否应在初始克隆时遵守
refspec
。
可以通过使用
空格
字符分隔多个参照规范来输入。
refspec
值
+refs/heads/master:refs/remotes/origin/master +refs/heads/develop:refs/remotes/origin/develop
检索主分支和开发分支，而不检索其他分支。
请参阅
git refspec documentation
以了解更多
refspec
详细信息。
Using Credentials
git 插件支持 Jenkins 凭据插件提供的用户名/密码凭据和私钥凭据。它不支持其他凭据类型，例如：密文、机密文件或证书。从作业定义下拉菜单中选择凭据，或在管道作业定义中输入其标识符。
当使用
HTTP
或
HTTPS
协议访问远程存储库时，插件需要
username/password credential
。其他凭据类型不适用于
HTTP
或
HTTPS
协议。
当使用
ssh protocol
访问远程存储库时，插件需要
ssh private key credential
。其他凭据类型不适用于 ssh 协议。
Push Notification From Repository
为了最大限度地减少推送和构建之间的延迟，请将远程存储库配置为使用 Webhook 通知 Jenkins 存储库的更改。请参阅存储库的 webhook 文档：
其他 git 存储库可以使用远程存储库中的
post-receive hook
来通知 Jenkins 更改。在 git 服务器上的
hooks/post-receive
文件中添加以下行 ，将
<URL of the Git repository>
替换为您在克隆存储库时使用的完全限定 URL，并将
<Access token>
替换为 Jenkins 管理员使用 “Configure Global Security” 页面的 “git plugin notifyCommit Access tokens” 部分生成的令牌。
curl http://yourserver/git/notifyCommit?url=<URL of the Git repository>&token=<Access token>
这将扫描以下所有作业：
-
Have Build Triggers > Poll SCM enabled
。不需要轮询时间表。 - 配置为在指定的 URL 上构建存储库
对于满足这些条件的作业，将触发轮询。如果轮询发现更改值得构建，则会触发构建。
这允许
notify script
对所有 Jenkins 作业保持不变。或者，如果在单个存储库主机应用程序（如：Gitosis）下有多个存储库，则可以与所有存储库共享一个
post-receive hook
脚本。
默认情况下，令牌参数是安全措施所必需的，但可以通过以下
system property
禁用：
hudson.plugins.git.GitStatus.NOTIFY_COMMIT_ACCESS_CONTROL
它有两种模式：
-
disabled-for-polling
——允许未经验证的请求，只要它们仅请求对
url
查询参数中提供的存储库进行轮询。禁止试图通过提供
sha1
查询参数立即安排生成的未经验证的请求。 -
disabled
——完全禁用访问令牌机制，并允许所有
notifyCommit
请求未经身份验证。此选项不安全，不建议使用。
当
notifyCommit
成功时，将返回已触发项目的列表。
Enabling JGit
有关
Enabling JGit
的说明，请参阅
git client plugin
文档。一旦启用，JGit 将在整个 Jenkins 可用。
Global Configuration
有关
Global Configuration
的说明，请参阅
Global Configuration
文档
Extensions
扩展为不同的用途添加新的行为或修改现有的插件行为。扩展帮助用户更精确地调整插件以满足他们的需求。
扩展包括：
- 克隆扩展
- 结帐扩展
- 变更日志扩展
- 标记扩展
- 构建启动扩展
- 合并扩展
- 已弃用的扩展
克隆扩展
克隆扩展修改将远程更改检索到代理工作区的 git 操作。扩展可以调整检索历史的数量、允许检索运行多长时间以及其他检索细节。
高级克隆行为
高级克隆行为修改
git clone
和
git fetch
命令。他们控制：
- 历史检索的广度（refspecs）
- 历史检索深度（shallow clone）
- 磁盘空间使用（reference repositories）
- 命令的持续时间（timeout）
- 标签检索
高级克隆行为包括：
Honor refspec on initial clone
使用为存储库定义的 refspec 执行初始克隆。当您只需要访问 refspec 指定的引用时，这可以节省时间、数据传输和磁盘空间。如果未启用，则插件默认 refspec 包括所有远程分支。
Shallow clone
通过从请求的分支的尖端请求有限数量的提交来执行浅克隆。Git 不会下载项目的完整历史记录。当您只想访问最新版本的存储库时，这可以节省时间和磁盘空间。
Shallow clone depth
将浅克隆深度设置为指定的提交次数。Git 只会 depth 从远程存储库下载提交，从而节省时间和磁盘空间。
Path of the reference repo to use during clone
指定一个包含存储库的文件夹，该存储库将在克隆操作期间被 git 用作参考。如果该文件夹在代理上不可用，则此选项将被忽略。
Timeout (in minutes) for clone and fetch operations
指定克隆和提取操作的超时时间（以分钟为单位）。
Fetch tags
取消选择此项以执行不带标签的克隆，当您只想访问 refspec 指定的内容而不考虑任何存储库标签时，可以节省时间和磁盘空间。
Prune stale remote tracking branches
如果远程上不再存在远程跟踪分支，则从本地工作区中删除它们。请参阅
git remote prune
和
git fetch –prune
了解更多详情。
Prune stale tags
如果远程上不再存在标签，则在获取之前从本地工作区中删除标签。如果不修剪过时的标签，删除远程标签不会删除工作区中的本地标签。如果本地标签已经存在于工作空间中，git 会正确地拒绝再次创建标签。修剪过时的标签允许本地工作区创建一个与从远程删除的标签同名的标签。
Checkout Extensions
签出扩展修改 git 操作，这些操作将 git 存储库中的文件放置在代理的工作区中。扩展可以调整签出操作的最长持续时间、git 子模块的使用和行为、工作区在磁盘上的位置等等。
Advanced checkout behaviors
高级签出行为修改
git checkout
命令。高级签出行为包括：
Timeout (in minutes) for checkout operation
指定签出超时（分钟）。如果超过超时，则停止签出。签出超时通常仅适用于速度较慢的文件系统或大型存储库。
Advanced sub-modules behaviours
高级子模块行为修改 git 子模块命令。它们控制：
- 历史检索深度（shallow clone）
- 磁盘空间使用（reference repositories）
- 凭据使用
- 命令的持续时间（timeout）
- 用于获取子模块的并发线程
Custom user name/e-mail address
user.name
定义 git 将分配给工作区中的新提交的用户名值。如果给定，则为构建设置环境变量
GIT_COMMITTER_NAME
和
GIT_AUTHOR_NAME
并覆盖全局设置中的值。
user.email
定义 git 将分配给工作区中的新提交的用户电子邮件值。如果给定，则为构建设置环境变量
GIT_COMMITTER_EMAIL
和
GIT_AUTHOR_EMAIL
并覆盖全局设置中的值。
Deprecated Extensions
Custom SCM name-Deprecated
此 SCM 的唯一名称。在
Multi SCM
插件中使用 Git 时需要。Pipeline 是在单个作业中从多个存储库中签出的强大且功能丰富的方式。
Submodule Combinator-Removed
多年前创建了一个实验，试图在 Jenkins 工作中创建子模块的组合。Freestyle 项目或其他遗留项目（如：多配置项目）永远无法使用该实验。它在 Pipeline、配置即代码和 JobDSL 中可见。
实验的实施已经取消。可靠性测试和其他配置工具更适合评估子模块组合。
子模块组合器没有已知用途，也没有针对子模块组合器报告的未解决的 Jira 问题。那些使用子模块组合器的人应该继续使用 4.6.0 之前的 git 插件版本。
子模块组合器忽略用户为 git 的
checkout scm
提供的以下参数值：
DoGenerateSubmoduleConfiguration（数据生成子模块配置）
现在始终设置为 false 的布尔值。git 插件不再评估子模块配置。
submoduleCfg
现在始终为空的子模块名称和分支的列表。git 插件不再评估子模块配置。
以前的管道语法如下所示：
checkout([$class: 'GitSCM',
branches: [[name: 'master']],
doGenerateSubmoduleConfigurations: false,
extensions: [],
submoduleCfg: [],
userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin']]])
当前管道语法如下所示：
checkout([$class: 'GitSCM',
branches: [[name: 'master']],
extensions: [],
userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin']]])
Environment Variables
git 插件在多个上下文中为环境变量赋值。环境变量在
Freestyle
、
Pipeline
、
Multibranch Pipeline
和
Organization Folder
项目中分配。
Branch Variables
GIT_BRANCH
正在构建的分支的名称，包括远程名称，如在
origin/master
中
GIT_LOCAL_BRANCH
正在构建的没有远程名称的分支名称，如在
master
中
Commit Variables
GIT_COMMIT
此构建中使用的提交的 SHA-1
GIT_PREVIOUS_COMMIT
此项目先前构建中使用的提交的 SHA-1
GIT_PREVIOUS_SUCCESSFUL_COMMIT
该项目最近一次成功构建中使用的提交的 SHA-1
System Configuration Variables
GIT_URL
此工作区中第一个 git 存储库的远程 URL
GIT_URL_n
此工作区中其他 git 存储库的远程 URL（如果有）
GIT_AUTHOR_EMAIL
将用于此工作区中的新提交的作者电子邮件地址
GIT_AUTHOR_NAME
将用于此工作区中的新提交的作者姓名
GIT_COMMITTER_EMAIL
将用于此工作区中的新提交的提交者电子邮件地址
GIT_COMMITTER_NAME
将用于此工作区中的新提交的提交者名称
Token Macro Variables
一些 Jenkins 插件（如：
email extension
、
build name setter
和
description setter
）允许参数化引用重新格式化支持的变量的文本。支持参数化引用以重新格式化其文本的变量称为 “令牌宏”。git 插件为以下内容提供令牌宏：
GIT_REVISION
扩展到 Git SHA1 提交 ID，该 ID 指向构建的提交。
length
应显示的提交 ID 的整数长度。${GIT_REVISION} 可能会扩大到 a806ba7701bcfc9f784ccb7854c26f03e045c1d2，而 ${GIT_REVISION, length=8} 会扩大到 a806ba77。
GIT_BRANCH
扩展为已构建的分支的名称。
all
布尔值，在启用时扩展到指向当前提交的所有分支名称。默认情况下，令牌仅扩展为一个分支名称
fullName
扩展为完整分支名称的布尔值，例如：
remotes/origin/masteror
或
origin/master
。否则，它会扩展为短名称，例如：
master
。
令牌宏最常见的用途是在 Freestyle 项目中。Jenkins Pipeline 支持丰富的字符串操作集，因此在 Pipelines 中通常不使用令牌宏。
当与 Pipeline 一起使用时，令牌宏基值通常由 Pipeline 中执行的第一次检出分配。随后的检出操作不会修改管道中令牌宏的值。
Properties
某些 git 插件设置只能通过 Jenkins 启动时设置的命令行属性进行控制。
Default Timeout
默认的 git 超时值（以分钟为单位）可以被
org.jenkinsci.plugins.gitclient.Git.timeOut
属性覆盖。应该在控制器和所有代理上设置该属性才能生效。
Disable command line git
命令行 git 是 git 插件和 git 客户端插件中的参考 git 实现。命令行 git 提供了最多的功能，也是最稳定的实现。一些安装可能不想安装命令行 git 并且可能想要禁用命令行 git 实现。管理员可以使用属性
org.jenkinsci.plugins.gitclient.Git.useCLI=false
禁用命令行 git 。
Allow local checkout
命令行 git 和 JGit 可以使用本地 URL（如：
file:/my/repo.git
）或路径（如：
/my/repo.git
）获取存储库。从本地 URL 或路径获取会在 Jenkins 控制器上创建安全漏洞。当前版本的 git 插件不允许从本地 URL 和路径获取。如果需要本地 URL 或路径，并且管理员接受禁用此安全保护的风险，则 Java 属性
hudson.plugins.git.GitSCM.ALLOW_LOCAL_CHECKOUT=true
可以从启动 Jenkins 控制器的命令行设置。