2023-01-15 12:12:00 +01:00
---
name: Woodpecker Email
icon: https://gitnet.fr/deblan/woodpecker-email/raw/branch/develop/logo.svg
description: plugin to send build status notifications via Email.
2023-01-15 12:24:42 +01:00
tags: [notifications, email]
2023-01-15 12:12:00 +01:00
containerImage: deblan/woodpecker-email
containerImageUrl: https://hub.docker.com/r/deblan/woodpecker-email
url: https://gitnet.fr/deblan/woodpecker-email
---
2017-01-16 13:20:59 +01:00
Use the Email plugin for sending build status notifications via email.
2015-11-11 02:44:23 +01:00
2017-01-16 13:20:59 +01:00
## Config
You can configure the plugin using the following parameters:
2021-10-13 08:52:55 +02:00
* **from.address** - Send notifications from this address
* **from.name** - Notifications sender name
2017-01-16 13:20:59 +01:00
* **host** - SMTP server host
* **port** - SMTP server port, defaults to `587`
* **username** - SMTP username
* **password** - SMTP password
* **skip_verify** - Skip verification of SSL certificates, defaults to `false`
2021-11-01 18:56:45 +01:00
* **no_starttls** - Enable/Disable STARTTLS
2017-01-16 13:20:59 +01:00
* **recipients** - List of recipients to send this mail to (besides the commit author)
2020-12-01 13:51:43 +01:00
* **recipients_file** - Filename to load additional recipients from (textfile with one email per line) (besides the commit author)
2017-01-16 13:20:59 +01:00
* **recipients_only** - Do not send mails to the commit author, but only to **recipients** , defaults to `false`
* **subject** - The subject line template
* **body** - The email body template
2017-08-31 11:14:08 +02:00
* **attachment** - An optional file to attach to the sent mail(s), can be an absolute path or relative to the working directory.
2023-01-04 22:42:48 +01:00
* **evaluate** - An optional expression to evaluate (on the fly) whether the mail should be sent or not ([https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#evaluate](https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#evaluate)).
2015-11-11 02:44:23 +01:00
2015-12-11 09:44:27 +01:00
## Example
2023-01-04 13:26:25 +01:00
The following is a sample configuration in your .woodpecker.yml file:
2015-11-11 02:44:23 +01:00
2019-10-07 11:47:52 +02:00
```yaml
2023-01-04 13:26:25 +01:00
pipeline:
mail:
image: deblan/woodpecker-email
2021-02-08 10:45:02 +01:00
settings:
2021-10-13 08:52:55 +02:00
from.address: noreply@github.com
from.name: John Smith
2021-02-08 10:45:02 +01:00
host: smtp.mailgun.org
username: octocat
password: 12345
recipients:
- octocat@github.com
2019-10-07 11:47:52 +02:00
```
2017-01-16 13:20:59 +01:00
### Secrets
2023-01-04 13:26:25 +01:00
2017-01-16 13:20:59 +01:00
The Email plugin supports reading credentials and other parameters from the Drone secret store. This is strongly recommended instead of storing credentials in the pipeline configuration in plain text.
```diff
2023-01-04 13:26:25 +01:00
pipeline:
mail:
image: deblan/woodpecker-email
2021-02-08 12:34:16 +01:00
settings:
2021-10-13 08:52:55 +02:00
from.address: noreply@github.com
2021-02-08 12:34:16 +01:00
host: smtp.mailgun.org
+ username:
+ from_secret: email_username
+ password: 12345
+ from_secret: email_password
recipients:
- octocat@github.com
2017-01-16 13:20:59 +01:00
```
2023-01-15 12:12:00 +01:00
### Evaluation
This plugin introduces an optional expression to evaluate (on the fly) whether the mail should be sent or not.
```diff
pipeline:
mail:
image: deblan/woodpecker-email
settings:
...
when:
- evaluate: 'CI_STEP_STATUS == "failure" || CI_PREV_PIPELINE_STATUS == "failure"'
```
The problem is that the expression is evaluated before the pipeline is generated. In this case, `CI_STEP_STATUS` does not exist yet and the mail step is ignored unless the previous pipeline failed.
```diff
pipeline:
mail:
image: deblan/woodpecker-email
settings:
...
+ evaluate: 'CI_STEP_STATUS == "failure" || CI_PREV_PIPELINE_STATUS == "failure"'
when:
- - evaluate: 'CI_STEP_STATUS == "failure" || CI_PREV_PIPELINE_STATUS == "failure"'
```
More information about the syntaxe on ([https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#evaluate](https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#evaluate)).
2015-12-16 11:41:30 +01:00
### Custom Templates
In some cases you may want to customize the look and feel of the email message
so you can use custom templates. For the use case we expose the following
additional parameters, all of the accept a custom handlebars template, directly
provided as a string or as a remote URL which gets fetched and parsed:
2017-01-16 13:20:59 +01:00
* **subject** - A handlebars template to create a custom subject. For more
2015-12-16 11:41:30 +01:00
details take a look at the [docs ](http://handlebarsjs.com/ ). You can see the
2017-01-16 15:06:10 +01:00
default template [here ](https://github.com/Drillster/drone-email/blob/master/defaults.go#L14 )
2017-01-16 13:20:59 +01:00
* **body** - A handlebars template to create a custom template. For more
2015-12-16 11:41:30 +01:00
details take a look at the [docs ](http://handlebarsjs.com/ ). You can see the
2017-01-16 15:06:10 +01:00
default template [here ](https://github.com/Drillster/drone-email/blob/master/defaults.go#L19-L267 )
2015-12-16 11:41:30 +01:00
Example configuration that generate a custom email:
```yaml
2023-01-04 13:26:25 +01:00
pipeline:
mail:
image: deblan/woodpecker-email
2021-02-08 12:34:16 +01:00
settings:
2021-10-13 08:52:55 +02:00
from.address: noreply@github.com
2021-02-08 12:34:16 +01:00
host: smtp.mailgun.org
username: octocat
password: 12345
subject: >
[{{ build.status }}]
{{ repo.owner }}/{{ repo.name }}
({{ build.branch }} - {{ truncate build.commit 8 }})
body:
https://git.io/vgvPz
2015-12-16 11:41:30 +01:00
```
### Skip SSL verify
In some cases you may want to skip SSL verification, even if we discourage that
as it leads to an unsecure environment. Please use this option only within your
intranet and/or with truested resources. For this use case we expose the
following additional parameter:
2017-01-16 13:20:59 +01:00
* **skip_verify** - Skip verification of SSL certificates
2015-12-16 11:41:30 +01:00
Example configuration that skips SSL verification:
2021-02-08 10:45:02 +01:00
```diff
2023-01-04 13:26:25 +01:00
pipeline:
mail:
image: deblan/woodpecker-email
2021-02-08 12:34:16 +01:00
settings:
from: noreply@github.com
host: smtp.mailgun.org
username: octocat
password: 12345
+ skip_verify: true
2015-12-16 11:41:30 +01:00
```
2021-10-29 22:27:55 +02:00
### STARTTLS
By default, STARTTLS is being used opportunistically meaning, if advertised
by the server, traffic is going to be encrypted.
You may want to disable STARTTLS, e.g., with faulty and/or internal servers:
```diff
2023-01-04 13:26:25 +01:00
pipeline:
mail:
image: deblan/woodpecker-email
2021-10-29 22:27:55 +02:00
settings:
from: noreply@github.com
host: smtp.mailgun.org
username: octocat
password: 12345
2021-11-01 18:56:45 +01:00
+ no_starttls: true
2021-10-29 22:27:55 +02:00
```