Jenkins Git 插件

  • Post author:
  • Post category:其他




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

  1. 单击管道语法片段生成器并选择

    withCredentials

    步骤,添加 Git 用户名和密码绑定。
  2. 选择所需的凭据和 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 控制器的命令行设置。



版权声明:本文为qq_46373211原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。