Skip to content

Latest commit

 

History

History
376 lines (308 loc) · 13.9 KB

DOCS.md

File metadata and controls

376 lines (308 loc) · 13.9 KB
Raw

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:

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: