Woodpecker Mail Plugin

Email notification plugin for Woodpecker CI written in Go.

Features

• ✅ Lightweight - Minimal Docker image size (~8 MB)
• ✅ HTML Templates - Support for Go templates with all CI variables
• ✅ Attachments - Send build artifacts and reports
• ✅ Multiple Recipients - Support for To, CC, BCC
• ✅ TLS/STARTTLS - Secure email delivery
• ✅ Template Files - Load templates from workspace files

Quick Start

steps:
  - name: send-email
    image: git.ymnuktech.ru/ymnuk/woodpecker-mail:latest
    settings:
      smtp_host: smtp.example.com
      smtp_port: 587
      smtp_user:
        from_secret: smtp_user
      smtp_pass:
        from_secret: smtp_password
      from: "CI Bot <bot@example.com>"
      recipients:
        - developer@example.com
      subject: "[${CI_REPO_NAME}] Pipeline #${CI_PIPELINE_NUMBER}"
      body: |
        <h1>CI Notification</h1>
        <p>Status: ${CI_PIPELINE_STATUS}</p>

Documentation

See docs.md for full documentation including:

• All available settings
• Template variables
• Examples with attachments
• Template file usage

Environment Variables

SMTP Settings

Variable	Description	Default
PLUGIN_SMTP_HOST	SMTP server hostname	-
PLUGIN_SMTP_PORT	SMTP server port	587
PLUGIN_SMTP_USER	SMTP username	-
PLUGIN_SMTP_PASS	SMTP password	-
PLUGIN_SMTP_VERIFY	Verify TLS certificate	true

Email Settings

Variable	Description	Default
PLUGIN_FROM	Sender email	-
PLUGIN_RECIPIENTS	JSON array of recipients	-
PLUGIN_CC	JSON array of CC recipients	[]
PLUGIN_BCC	JSON array of BCC recipients	[]
PLUGIN_REPLY_TO	Reply-To address	-
PLUGIN_SUBJECT	Email subject	Auto-generated
PLUGIN_BODY	Email body HTML	Default template
PLUGIN_TEMPLATE_FILE	Path to template file	-
PLUGIN_ATTACHMENTS	JSON array of file paths	[]

CI Variables Available in Templates

All Woodpecker CI variables are available:

In YAML settings (subject, body as string)

Woodpecker substitutes ${VAR} before passing to plugin:

subject: "[${CI_REPO_NAME}] Pipeline #${CI_PIPELINE_NUMBER}"
body: "Status: ${CI_PIPELINE_STATUS}"

In template files or multi-line body

Use Go template syntax:

{{index .CI "CI_REPO_NAME"}}
{{index .CI "CI_PIPELINE_NUMBER"}}
{{index .CI "CI_PIPELINE_STATUS"}}

Full list at Woodpecker CI Environment Variables.

Example with Attachments

steps:
  - name: build
    image: golang
    commands:
      - go build
      - go test -v ./... > test-report.txt

  - name: send-email
    image: git.ymnuktech.ru/ymnuk/woodpecker-mail:latest
    settings:
      smtp_host: smtp.example.com
      smtp_user:
        from_secret: smtp_user
      smtp_pass:
        from_secret: smtp_password
      from: "CI Bot <bot@example.com>"
      recipients:
        - team@example.com
      subject: "Build Report #${CI_PIPELINE_NUMBER}"
      body: |
        <h1>Build Complete</h1>
        <p>Repository: ${CI_REPO_NAME}</p>
        <p>Status: ${CI_PIPELINE_STATUS}</p>
      attachments:
        - ./test-report.txt

Building

Local Build

go build -ldflags="-s -w" -o woodpecker-mail .

Docker Build

docker build -t woodpecker-mail:latest .

CI/CD Build (Woodpecker)

For multi-arch builds in Woodpecker CI, use plugin-docker-buildx:

- name: docker_release
  image: woodpeckerci/plugin-docker-buildx
  settings:
    repo: ${DOCKER_REGISTRY}/${CI_REPO_OWNER}/${CI_REPO_NAME}
    username:
      from_secret: docker_user
    password:
      from_secret: docker_pass
    tags:
      - latest
      - ${CI_COMMIT_TAG}
    platforms:
      - linux/amd64
      - linux/arm64
    dockerfile: Dockerfile
    registry: ${DOCKER_REGISTRY}

Image Size

• ~8 MB (scratch-based with ca-certificates)
• Supports: linux/amd64, linux/arm64

Testing Locally

docker run --rm \
  -e PLUGIN_SMTP_HOST=smtp.example.com \
  -e PLUGIN_SMTP_PORT=587 \
  -e PLUGIN_SMTP_USER=user \
  -e PLUGIN_SMTP_PASS=pass \
  -e PLUGIN_FROM="Test <test@example.com>" \
  -e PLUGIN_RECIPIENTS='["recipient@example.com"]' \
  -e PLUGIN_SUBJECT="Test Email" \
  -e PLUGIN_BODY="<h1>Test</h1>" \
  git.ymnuktech.ru/ymnuk/woodpecker-mail:latest

CI/CD

The build and release pipeline is configured in .woodpecker.yml:

Trigger: Tag creation (when: tag)

• docker_release — multi-arch image build (amd64 + arm64) with tag
• notify_email — send success notification email

Configure Secrets

Configure the following secrets in Woodpecker CI:

docker_user       # Registry username
docker_pass       # Registry password/token
smtp_host         # SMTP server (e.g., smtp.gmail.com)
smtp_user         # SMTP username (full email)
smtp_pass         # SMTP password (app password)
email_recipients  # Recipients (comma-separated): user1@example.com,user2@example.com

Usage

# Create a tag and push to CI
git tag v1.0.0
git push origin v1.0.0

# Woodpecker CI will automatically:
# 1. Build the image with tag v1.0.0
# 2. Publish to registry
# 3. Send email notification

Links

• Creating Woodpecker Plugins
• Woodpecker Environment Variables
• Go Plugin Library

License

MIT