如何在Jenkins Pipeline中用GitSCM插件拉取/检出单个文件？

核心结论 #

GitSCM插件本身不支持直接拉取单个文件，它的设计以完整克隆或目录级稀疏检出为主，针对单个文件的场景，更推荐直接用Shell执行Git命令，配置简单且高效。

为什么不推荐用GitSCM插件？ #

• GitSCM插件的稀疏检出配置仅支持目录级过滤，没有提供直接指定单个文件的参数。
• 若强行通过插件实现，需要手动修改.git/info/sparse-checkout文件，但插件的封装逻辑没有暴露这类底层操作的入口，配置繁琐且容易出现同步问题。

推荐的Shell命令实现方案 #

方案1：基于稀疏检出拉取单个文件 #

适合需要保留仓库结构的场景，步骤如下：

pipeline {
    agent any
    stages {
        stage('拉取单个文件') {
            steps {
                sh '''
                    git init
                    git remote add origin https://github.com/你的用户名/你的仓库.git
                    git config core.sparseCheckout true
                    # 替换为目标文件的完整路径
                    echo "docs/config.yaml" >> .git/info/sparse-checkout
                    git pull origin main
                '''
            }
        }
    }
}

方案2：用git archive直接提取单个文件（更高效） #

无需初始化本地仓库，直接从远程提取文件，适合仅需要单个文件的场景：

pipeline {
    agent any
    stages {
        stage('提取单个文件') {
            steps {
                sh '''
                    # 替换为远程仓库地址、分支和文件路径，保存到本地指定文件名
                    git archive --remote=https://github.com/你的用户名/你的仓库.git main:docs/config.yaml > local-config.yaml
                '''
            }
        }
    }
}

私有仓库的认证处理 #

如果是私有GitHub仓库，需要在命令中加入认证信息：

• HTTPS方式：使用Jenkins凭据绑定用户名和密码，替换仓库URL为：

  https://${GIT_USER}:${GIT_PASS}@github.com/你的用户名/你的仓库.git
  

  可以通过credentials步骤注入凭据：

  pipeline {
      agent any
      environment {
          GIT_CREDS = credentials('github-credentials-id')
      }
      stages {
          stage('提取私有文件') {
              steps {
                  sh '''
                      git archive --remote=https://${GIT_CREDS_USR}:${GIT_CREDS_PSW}@github.com/你的用户名/你的仓库.git main:docs/config.yaml > local-config.yaml
                  '''
              }
          }
      }
  }
  

• SSH方式：确保Jenkins代理节点配置了对应GitHub的SSH密钥，或者使用Jenkins的SSH凭据管理密钥。

内容的提问来源于stack exchange，提问作者akshay_yelp