Email

Description

This plugin enables you to send data to an email.

Source Code: https://github.com/go-vela/vela-email

Registry: https://hub.docker.com/r/target/vela-email

Usage

NOTE:

Users should refrain from using latest as the tag for the Docker image.

It is recommended to use a semantically versioned tag instead.

Sample for .vela.yml

secrets:
  - name: username
    engine: native
    key: vela/noreply/username
    type: shared

  - name: password
    engine: native
    key: vela/noreply/password
    type: shared

steps:
  - name: email on success
    image: target/vela-email:latest
    pull: not_present
    secrets: [username, password]
    ruleset:
      status: success
    parameters:
      from: vela-noreply@fakemail.com
      to: [one@email.com, two@email.com]
      sendtype: StartTLS
      auth: LoginAuth
      host: smtp.youremailserver.com
      port: 587
      subject: "{{ .VELA_BUILD_COMMIT }}"
      text: "Author: {{ .VELA_BUILD_AUTHOR }} - Branch: {{ .VELA_BUILD_BRANCH }}"

  - name: email on failure
    image: target/vela-email:latest
    pull: not_present
    secrets: [username, password]
    ruleset:
      status: failure
    parameters:
      from: vela-noreply@fakemail.com
      to: [one@email.com, two@email.com]
      sendtype: StartTLS
      auth: LoginAuth
      host: smtp.youremailserver.com
      port: 587
      subject: "{{ .VELA_BUILD_COMMIT }}"
      text: "Author: {{ .VELA_BUILD_AUTHOR }} - Branch: {{ .VELA_BUILD_BRANCH }}"

Sample for .vela.yml with attachment

secrets:
  - name: username
    engine: native
    key: vela/noreply/username
    type: shared

  - name: password
    engine: native
    key: vela/noreply/password
    type: shared

steps:
  - name: email on success
    image: target/vela-email:latest
    pull: not_present
    secrets: [username, password]
    ruleset:
      status: success
    parameters:
      filename: <filename>
      sendtype: StartTLS
      auth: LoginAuth
      host: smtp.youremailserver.com
      port: 587

  - name: email on failure
    image: target/vela-email:latest
    pull: not_present
    secrets: [username, password]
    ruleset:
      status: failure
    parameters:
      filename: <filename>
      sendtype: StartTLS
      auth: LoginAuth
      host: smtp.youremailserver.com
      port: 587

Sample for email attachment

From: vela-noreply@fakemail.com
To: emailone@email.com, emailtwo@email.com
Subject: Vela Pipeline for {{ .VELA_REPO_FULL_NAME }} {{ .VELA_BUILD_BRANCH }}
Content-Type: text/plain

BuildAuthor:        {{ .VELA_BUILD_AUTHOR }}
BuildAuthorEmail:   {{ .VELA_BUILD_AUTHOR_EMAIL }}
BuildBranch:        {{ .VELA_BUILD_BRANCH }}
BuildCommit:        {{ .VELA_BUILD_COMMIT }}
BuildCreated:       {{ .BuildCreated }}
BuildMessage:       {{ .VELA_BUILD_MESSAGE }}
BuildNumber:        {{ .VELA_BUILD_NUMBER }}
RepositoryFullName: {{ .VELA_REPO_FULL_NAME }}
RepositoryLink:     {{ .VELA_REPO_LINK }}

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

The plugin accepts the following parameters for authentication:

Parameter	Environment Variable Configuration
username	PARAMETER_USERNAME, USERNAME
password	PARAMETER_PASSWORD, PASSWORD

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: email
    image: target/vela-email:latest
    pull: always
+   secrets: [ username, password ]
    parameters:
-     username: usernameexample@email.com

This example will add the secret to the email step as environment variables:

• USERNAME=value

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
username	/vela/parameters/email/username, /vela/secrets/email/username
password	/vela/parameters/email/password, /vela/secrets/email/password

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: email
    image: target/vela-email:latest
    pull: always
    parameters:
-     username: usernameexample@email.com

This example will read the secret value in the volume stored at /vela/secrets/

Parameters

NOTE:

Any values set from a file take precedence over values set from the environment.

VELA environments can be found at VELA Environments

All environment variables are wrapped in sprig template. More information on sprig can be found at sprig docs

The following parameters are used to configure the image:

Logging

Parameter	Description	Required	Default	Environment Variables
log_level	set the log level for the plugin (valid options: info, debug, trace)	true	info	PARAMETER_LOG_LEVEL EMAIL_LOG_LEVEL

Email

Parameter	Description	Required	Default	Environment Variables
from	who the email is being sent from	true	N/A	PARAMETER_FROM EMAIL_FROM
to	who the email is being sent to	true	N/A	PARAMETER_TO EMAIL_TO
cc	carbon copy of the email to be sent to	false	N/A	PARAMETER_CC EMAIL_CC
bcc	blind carbon copy of the email to be sent to	false	N/A	PARAMETER_BCC EMAIL_BCC
sender	who the email being sent from (will overwrite from)	false	N/A	PARAMETER_SENDER EMAIL_SENDER
replyto	email address that will be used for replies	false	N/A	PARAMETER_REPLYTO EMAIL_REPLYTO
subject	subject of the email	false	default subject	PARAMETER_SUBJECT EMAIL_SUBJECT
text	body of the email in plain text format (HTML will overwrite TEXT)	false	N/A	PARAMETER_TEXT EMAIL_TEXT
html	body of the email in hmtl format (HTML will overwrite TEXT)	false	default html body	PARAMETER_HTML EMAIL_HTML
readreceipt	delivery confirmation	false	N/A	PARAMETER_READRECEIPT EMAIL_READRECEIPT

NOTE:

The parameters To, CC, BCC and ReplyTo accepts an array of emails in the format of:

• [ one@email.com, two@email.com ] or

• [ firstname lastname one@email.com, firstname lastname two@email.com ]

Subject, Text body, and HTML body will accept VELA environments with the use of {{ }} such as:

• {{ .VELA_REPO_FULL_NAME }}

Attachment

Parameter	Description	Required	Default	Environment Variables
attachment	file will be attached to email	false	N/A	PARAMETER_ATTACHMENT EMAIL_ATTACHMENT

Email Filename

Parameter	Description	Required	Default	Environment Variables
filename	data in attached file will be used to populate the email.	false	N/A	PARAMETER_FILENAME EMAIL_FILENAME

SMTP

Parameter	Description	Required	Default	Environment Variables
host	SMTP host	true	N/A	PARAMETER_HOST EMAIL_HOST
port	SMTP port	true	N/A	PARAMETER_PORT EMAIL_PORT
username	SMTP username	true	N/A	PARAMETER_USERNAME EMAIL_USERNAME
password	SMTP password	true	N/A	PARAMETER_PASSWORD EMAIL_PASSWORD

TLS

Parameter	Description	Required	Default	Environment Variables
servername	default is set to host address of SMTP server	false	SMTP host	PARAMETER_SERVERNAME EMAIL_SERVERNAME
insecureskipverify	verification of the server's certificate chain and host name. Only use true for testing purposes as this makes TLS susceptible to man-in-middle attacks.	false	false	PARAMETER_SKIPVERIFY EMAIL_SKIPVERIFY

Encryption

Parameter	Description	Required	Default	Environment Variables
sendtype	security to send email (valid option: Plain, StartTLS, TLS)	true	StartTLS	PARAMETER_SENDTYPE EMAIL_SENDTYPE

Authentication

Parameter	Description	Required	Default	Environment Variables
auth	login authentication (valid option: PlainAuth, LoginAuth)	true	LoginAuth	PARAMETER_AUTH EMAIL_AUTH

NOTE:

PlainAuth using smtp/auth login for SMTP server.

LoginAuth using a custom login for Office 365/Exchange SMTP server.

Variables

The Plugin provides the following User friendly timestamp variables that can be used in a subject, text, HTML template. These timestamps are converted to Unix timestamps in UTC.

• BuildCreated
• BuildEnqueued
• BuildFinished
• BuildStarted

Defaults

NOTE: Context-Type options are as follow:

• text/html for HTML based body of message.
• text/plain for TEXT based body of message.

Default subject

{{ .VELA_REPO_FULL_NAME }} {{ .VELA_BUILD_BRANCH }} - {{ .VELA_BUILD_COMMIT }}

Default body in HTML

<table>
  <tbody>
    <tr>
      <td width="600">
        <div>
          <table width="100%" cellspacing="0" cellpadding="0">
            <tbody>
              <tr>
                <td>
                  <table width="100%" cellspacing="0" cellpadding="0">
                    <tbody>
                      <tr>
                        <td>Build Number:</td>
                        <td>
                          <a href="{{ .VELA_BUILD_LINK }}">
                            {{ .VELA_BUILD_NUMBER }}
                          </a>
                        </td>
                      </tr>
                      <tr>
                        <td>Repo:</td>
                        <td>{{ .VELA_REPO_FULL_NAME }}</td>
                      </tr>
                      <tr>
                        <td>Author:</td>
                        <td>
                          {{ .VELA_BUILD_AUTHOR }} ({{ .VELA_BUILD_AUTHOR_EMAIL
                          }})
                        </td>
                      </tr>
                      <tr>
                        <td>Branch:</td>
                        <td>{{ .VELA_BUILD_BRANCH }}</td>
                      </tr>
                      <tr>
                        <td>Commit:</td>
                        <td>{{ .VELA_BUILD_COMMIT }}</td>
                      </tr>
                      <tr>
                        <td>Started at:</td>
                        <td>{{ .BuildCreated }}</td>
                      </tr>
                    </tbody>
                  </table>
                  <hr />
                  <table width="100%" cellspacing="0" cellpadding="0">
                    <tbody>
                      <tr>
                        <td>{{ .VELA_BUILD_MESSAGE }}</td>
                      </tr>
                    </tbody>
                  </table>
                </td>
              </tr>
            </tbody>
          </table>
        </div>
      </td>
    </tr>
  </tbody>
</table>

Template

COMING SOON!

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: send email
    image: target/vela-email:latest
    pull: always
    parameters:
+     log_level: trace
      ...

Below are a list of common problems and how to solve them: