woodpeckerci/plugin-git

Woodpecker CI Git插件镜像

镜像概述

woodpeckerci/plugin-git是Woodpecker CI的官方Git插件镜像，专为在CI/CD工作流中执行标准化Git操作而设计。该镜像封装了完整的Git工具链，提供从代码仓库克隆、分支检出到子模块管理的全流程支持，帮助开发者在自动化管道中高效获取源代码。

核心功能与特性

• 全面的Git操作支持：提供克隆、拉取、检出分支/标签/提交哈希等基础功能
• 子模块管理：支持递归拉取和更新Git子模块，满足复杂项目依赖需求
• 深度控制：可配置克隆深度（shallow clone），减少数据传输量，提升执行效率
• 多协议支持：兼容HTTPS和SSH两种仓库访问协议
• 灵活认证机制：支持用户名密码、SSH密钥等多种认证方式
• 轻量级设计：基于Alpine Linux构建，镜像体积小，启动速度快

使用场景

• CI/CD管道初始化：在构建、测试或部署阶段前获取最新代码
• 多分支工作流：针对feature、release、main等不同分支执行差异化构建
• 版本化部署：基于特定标签或提交版本执行构建，确保部署版本可追溯
• 子模块项目构建：处理包含多个子模块的复杂项目依赖
• 代码同步任务：在多仓库协作场景中同步代码资源

使用方法与配置说明

Woodpecker CI配置示例

在Woodpecker CI配置文件（.woodpecker.yml）中添加以下步骤：

yaml
steps:
  - name: checkout code
    image: woodpeckerci/plugin-git
    settings:
      repo: https://github.com/your-username/your-repo.git
      branch: main
      depth: 1
      submodule_update: true

配置参数详解

高级使用示例

SSH密钥认证配置

yaml
steps:
  - name: clone private repo
    image: woodpeckerci/plugin-git
    settings:
      repo: git@github.com:your-username/private-repo.git
      branch: develop
      ssh_key:
        from_secret: git_ssh_key  # 引用Woodpecker CI密钥管理中的SSH密钥
      submodule_update: true
      submodule_recursive: true

基于标签的版本检出

yaml
steps:
  - name: build release version
    image: woodpeckerci/plugin-git
    settings:
      repo: https://github.com/your-username/your-repo.git
      tag: v1.2.3
      depth: 1  # 浅克隆加速获取

直接Docker运行（调试用）

bash
docker run --rm \
  -e PLUGIN_REPO=https://github.com/woodpecker-ci/plugin-git.git \
  -e PLUGIN_BRANCH=main \
  -e PLUGIN_DEPTH=10 \
  woodpeckerci/plugin-git

注意事项

• 当同时指定多个版本参数时，优先级为：sha > tag > branch
• 使用SSH认证时，确保私钥格式正确且无密码保护
• 浅克隆（depth > 0）可能导致部分Git操作受限（如无法获取完整历史）
• 对于包含大型子模块的项目，建议单独配置子模块的克隆深度

环境变量参考

除上述配置参数外，还可通过以下环境变量进行配置：