plugins/gh-pages

drone-gh-pages 镜像文档

概述

drone-gh-pages是Drone CI的官方插件镜像，用于将项目构建产物自动部署到GitHub Pages。该镜像由drone-plugins团队维护（https://github.com/drone-plugins/drone-gh-pages），通过Drone CI自动构建和推送，提供可靠的GitHub Pages部署能力，帮助开发者在CI/CD流程中无缝完成静态网站发布。

核心功能和特性

• Drone CI集成：与Drone CI pipeline无缝集成，支持自动触发部署流程
• GitHub Pages部署：专注于将静态文件部署到GitHub Pages服务
• 灵活配置：支持自定义源目录、目标分支、提交信息等部署参数
• 安全认证：通过GitHub Token进行身份验证，确保仓库访问安全
• 自动化流程：减少手动部署步骤，提高静态网站发布效率

使用场景和适用范围

适用于需要通过CI/CD流程自动部署静态内容到GitHub Pages的场景，包括但不限于：

• 开源项目文档站点（如使用 MkDocs、Sphinx 生成的文档）
• 静态博客（如 Jekyll、Hugo、Hexo 等生成的站点）
• 前端应用（如 React、Vue、Angular 构建的单页应用）
• 个人/组织主页

使用方法和配置说明

环境变量配置

以下环境变量用于控制部署行为：

Drone CI Pipeline配置示例

在Drone CI配置文件（.drone.yml）中添加部署步骤：

yaml
steps:
  - name: 构建静态文件
    image: docker.xuanyuan.run/node:18
    commands:
      - npm install
      - npm run build

  - name: 部署到GitHub Pages
    image: docker.xuanyuan.run/plugins/gh-pages
    settings:
      github_token:
        from_secret: github_token  # 从Drone密钥管理中获取
      target_branch: gh-pages      # 目标分支
      publish_dir: ./dist          # 构建产物目录
      commit_message: "Deploy ${DRONE_COMMIT_SHA:0:8}"  # 提交信息，包含短SHA

Docker Run命令示例

直接使用Docker命令运行（需挂载项目目录）：

bash
docker run --rm \
  -e GITHUB_TOKEN=your_github_personal_access_token \
  -e GITHUB_REPO=your-username/your-repo \
  -e TARGET_BRANCH=gh-pages \
  -e PUBLISH_DIR=/app/dist \
  -v $(pwd):/app \
  docker.xuanyuan.run/plugins/gh-pages

注意事项

• GitHub Token权限：需确保GITHUB_TOKEN具有repo权限（至少需要public_repo权限用于公共仓库，repo权限用于私有仓库）
• 目标分支：若TARGET_BRANCH不存在，插件会自动创建该分支
• 构建产物：确保PUBLISH_DIR目录包含完整的静态文件（如HTML、CSS、JS等）
• Drone环境：在Drone CI中使用时，GITHUB_REPO等信息会自动从Drone环境变量获取，无需手动指定