pivotal-cf/email-resource

Name: email-resource

Owner: Pivotal Cloud Foundry

Description: A Concourse resource that sends emails

Created: 2015-08-03 21:40:02.0

Updated: 2018-03-27 18:20:09.0

Pushed: 2018-05-13 17:05:45.0

Homepage:

Size: 408

Language: Go

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Email Resource

A Concourse resource that sends emails.

Getting started

Add the following Resource Type to your Concourse pipeline

urce_types:
name: email
type: docker-image
source:
  repository: pcfseceng/email-resource

Look at the demo pipeline for a complete example.

This resource acts as an SMTP client, using PLAIN auth over TLS. So you need an SMTP server that supports all that.

For development, we've been using Amazon SES with its SMTP support

Source Configuration

source:

Parameters

Within smtp:

• host: Required. SMTP Host name
• port: Required. SMTP Port, must be entered as a string
• anonymous: Optional. Whether or not to require credential. true/false are valid options. If omitted default is false
• username: Required, Conditionally. Username to authenticate with. Ignored if anonymous: true
• password: Required, Conditionally. Password to authenticate with. Ignored if anonymous: true
• skip_ssl_validation: Optional. Whether or not to skip ssl validation. true/false are valid options. If omitted default is false
• ca_cert: Optional. Certificates content to verify servers with custom certificates. Only considered if skip_ssl_validation is false.

Within source:

• from: Required. Email Address to be sent from.
• to: Required.Conditionally. Array of email addresses to send email to. Not required if job params contains a file reference that has to recipients.

An example source configuration is below.

urces:
me: send-an-email
pe: email
urce:
smtp:
  host: smtp.example.com
  port: "587" # this must be a string
  username: a-user
  password: my-password
from: build-system@example.com
to: [ "dev-team@example.com", "product@example.net" ] #optional if `params.additional_recipient` is specified

An example source configuration is below supporting sending email when anonymous is permitted.

urces:
me: send-an-email
pe: email
urce:
smtp:
  host: smtp.example.com
  port: "587" # this must be a string
  anonymous: true
from: build-system@example.com
to: [ "dev-team@example.com", "product@example.net" ]

An exmaple using custom certificates:

urces:
me: send-an-email
pe: email
urce:
smtp:
  host: smtp.example.com
  port: "587" # this must be a string
  anonymous: true
  ca_cert: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
from: build-system@example.com
to: [ "dev-team@example.com", "product@example.net" ] 

Note that to is an array, and that port is a string. If you're using fly configure with the --load-vars-from (-l) substitutions, every {{ variable }} automatically gets converted to a string. But for literals you need to surround it with quotes.

Behavior

This is an output-only resource, so check and in actions are no-ops.

out: Send an email

Parameters

• headers: Optional. Path to plain text file containing additional mail headers
• subject: Optional. Path to plain text file containing the subject. Either subject or subject_text required. subject_text takes precedence.
• subject_text: Optional. The subject as text. Either subject or subject_text required. subject_text takes precedence.
• body: Optional. Path to file containing the email body. Either body or body_text required. body_text takes precedence.
• body_text: Optional. The email body as text. Either body or body_text required. body_text takes precedence.
• send_empty_body: Optional. If true, send the email even if the body is empty (defaults to false).
• to: Optional. Path to plain text file containing recipients which could be determined at build time. You can run a task before, which figures out the email of the person who committed last to a git repository (git -C $source_path --no-pager show $(git -C $source_path rev-parse HEAD) -s --format='%ae' > output/email.txt). This file can contain , delimited list of email address if wanting to send to multiples.

For example, a build plan might contain this:

put: send-an-email
params:
  subject: generated-subject-file
  body: generated-body-file

For example, a build plan might contain this if using generated list of recipient(s):

put: send-an-email
params:
  subject: generated-subject-file
  body: generated-body-file
  to: generated-to-file

You can use the values below in any of the source files or text properties to access the corresponding metadata made available by concourse, as documented here

• ${BUILD_ID}
• ${BUILD_NAME}
• ${BUILD_JOB_NAME}
• ${BUILD_PIPELINE_NAME}
• ${ATC_EXTERNAL_URL}
• ${BUILD_TEAM_NAME}

For example:

put: send-an-email
params:
  subject_text: "Build finished: ${BUILD_PIPELINE_NAME}/${BUILD_JOB_NAME}/${BUILD_NAME}"
  body_text: "Build finished: ${ATC_EXTERNAL_URL}/teams/main/pipelines/${BUILD_PIPELINE_NAME}/jobs/${BUILD_JOB_NAME}/builds/${BUILD_NAME}"

HTML Email

To send HTML email set the headers parameter to a file containing the following:

-version: 1.0
ent-Type: text/html; charset="UTF-8"

Build from the source

email-resource is written in Go. To build the binary yourself, follow these steps:

• Install Go.
• Install Glide, a dependency management tool for Go.
• Clone the repo:
• mkdir -p $(go env GOPATH)/src/github.com/pivotal-cf
• cd $(go env GOPATH)/src/github.com/pivotal-cf
• git clone git@github.com:pivotal-cf/email-resource.git
• Install dependencies:
• cd email-resource
• glide install
• go build -o bin/check check/cmd/*.go
• go build -o bin/in in/cmd/*.go
• go build -o bin/out out/cmd/*.go

To cross compile, set the $GOOS and $GOARCH environment variables. For example: GOOS=linux GOARCH=amd64 go build.

Testing

To run the unit tests, use go test $(glide nv).