woodpeckerci/plugin-s3

Woodpecker S3 插件

概述

Woodpecker S3插件是一个专为Woodpecker CI/CD系统设计的插件，用于与Amazon S3或兼容S3的对象存储服务进行交互。该插件允许在CI/CD流程中轻松实现文件的上传、下载等操作，方便管理构建产物、备份数据或部署静态资源。

核心功能和特性

• 支持文件上传到S3存储桶
• 支持从S3存储桶下载文件
• 兼容Amazon S3及S3兼容存储服务
• 支持设置文件访问权限
• 支持路径前缀和通配符匹配
• 支持自定义Content-Type
• 支持设置缓存控制头

使用场景和适用范围

• CI/CD流程中上传构建产物到S3
• 从S3下载依赖文件或配置
• 部署静态网站到S3托管服务
• 备份CI/CD过程中的重要文件
• 与S3兼容的存储服务集成

使用方法和配置说明

基本用法

在Woodpecker Pipeline配置文件中使用：

yaml
steps:
  - name: upload to s3
    image: woodpecker-plugins/plugin-s3
    settings:
      access_key: your-access-key
      secret_key: your-secret-key
      bucket: your-bucket-name
      endpoint: s3.amazonaws.com
      region: us-east-1
      action: upload
      source: dist/*
      target: /path/in/bucket/

配置参数

必选参数

可选参数

Docker Run 示例

bash
docker run --rm \
  -e PLUGIN_ACCESS_KEY=your-access-key \
  -e PLUGIN_SECRET_KEY=your-secret-key \
  -e PLUGIN_BUCKET=your-bucket \
  -e PLUGIN_REGION=us-east-1 \
  -e PLUGIN_ACTION=upload \
  -e PLUGIN_SOURCE=dist/* \
  -e PLUGIN_TARGET=/path/in/bucket/ \
  -v $(pwd):/woodpecker/workspace \
  woodpecker-plugins/plugin-s3

完整配置示例

yaml
steps:
  - name: upload to s3
    image: woodpecker-plugins/plugin-s3
    settings:
      access_key:
        from_secret: s3_access_key
      secret_key:
        from_secret: s3_secret_key
      bucket: my-project-bucket
      region: eu-central-1
      action: upload
      source: ./dist/**/*.{js,css,html}
      target: /website/
      acl: public-read
      cache_control: max-age=31536000
      content_type: auto

环境变量配置

除了在pipeline配置中设置参数外，还可以通过环境变量进行配置：

• PLUGIN_ACCESS_KEY: S3访问密钥
• PLUGIN_SECRET_KEY: S3密钥
• PLUGIN_BUCKET: 存储桶名称
• PLUGIN_REGION: 区域
• PLUGIN_ENDPOINT: S3服务端点
• PLUGIN_ACTION: 操作类型(upload/download)
• PLUGIN_SOURCE: 源文件路径
• PLUGIN_TARGET: 目标路径
• PLUGIN_ACL: 访问控制列表
• PLUGIN_CACHE_CONTROL: 缓存控制头

注意事项

• 确保提供的访问密钥具有足够的权限执行所需操作
• 对于S3兼容服务，需要正确配置endpoint和path_style参数
• 使用通配符时注意路径匹配规则
• 敏感信息如访问密钥应使用Woodpecker的secret功能进行管理，避免明文暴露