Slack notification sending resource

Sends messages to Slack.

Source Configuration

url: (Required) The webhook URL as provided by Slack. Usually in the form: https://hooks.slack.com/services/XXXX

Behavior

`out`: Sends message to Slack.

Send message to Slack, with the configured parameters.

Parameters

The resource will accept all configuration described by the Slack Incoming Webhooks documentation including Message Attachments. The contents of the message can be formatted using the Slack Formatting system including multiple lines, emojis and links. At the time of publication, the following fields are available:

Name	Description
`attachments.author_icon`	The author icon for the message attachment
`attachments.author_link`	The author link for the message attachment
`attachments.author_name`	The author name for the message attachment
`attachments.color`	The accent color for the message attachment
`attachments.fallback`	The plain-text fallback for the message attachment
`attachments.fields.short`	Whether the message attachment field is short
`attachments.fields.title`	The title for the message attachment field
`attachments.fields.value`	The value for the message attachment field
`attachments.image_url`	The image url for the message attachment
`attachments.pretext`	The pretext for the message attachment
`attachments.text`	The text for the message attachment
`attachments.thumb_url`	The thumbnail url for the message attachment
`attachments.title_link`	The title link for the message attachment
`attachments.title`	The title for the message attachment
`channel`	The channel for of the message
`icon_emoji`	The emoji icon of the message
`icon_url`	The user icon of the message
`text`	The text of the message
`username`	The username of the message

In addition to the Slack configuration, there is some resource-specific configuration:

Name	Description
`always_notify`	Whether a notification should be sent, even if there is no configured message
`debug`	Print out the Webhook URL and body instead of invoking the Slack webhook
`text_file`	File that contains the message to send. This allows the message to be generated by a previous task step in the Concourse job.

One or more of always_notify, attachments, text, or text_file must be specified. If you omit the attachments and text parameters, the content of the file specified in text_file will be used verbatim. Alternatively, you can include a reference to the environment variable TEXT_FILE_CONTENT in any string to include the content of the file with other static text. See the Metadata section below for more details.

Under the philosophy that it's better to write something than fail silently, the following fallback values are used:

when text is omitted and
- text_file omitted, or present but file missing:
  - (no notification given)
- text_file specified and present but file empty:
  - (missing notification text)
when text is present, but evaluates to empty string after variable interpolation:
- (missing notification text)
when text specified with $TEXT_FILE_CONTENT and more content and
- text_file omitted, or present but file missing
  - $TEXT_FILE_CONTENT is replaced with (no notification given)
- text_file specified and present but file empty:
  - $TEXT_FILE_CONTENT is replaced with (missing notification text)

Metadata

The resource runs with all of the environment variables described by the Concourse metadata. At the time of publication, the following metadata is available:

Name	Description
`$ATC_EXTERNAL_URL`	The public URL for your ATC; useful for debugging
`$BUILD_ID`	The internal identifier for the build. Right now this is numeric but it may become a guid in the future. Treat it as an absolute reference to the build.
`$BUILD_JOB_NAME`	The name of the build's job
`$BUILD_NAME`	The build number within the build's job
`$BUILD_PIPELINE_NAME`	The pipeline that the build's job lives in

In addition to the Concourse metadata, there is some resource-specific metadata:

Name	Description
`$TEXT_FILE_CONTENT`	The contents of the file specified by the `text_file` parameter

The following pipeline config snippet demonstrates how to incorporate the metadata:

---
jobs:
- name: some-job
  plan:
  - put: slack-alert
    params:
      attachments:
      - color: good
        fallback: $BUILD_PIPELINE_NAME #$BUILD_NAME has been deployed: $ATC_EXTERNAL_URL/pipelines/$BUILD_PIPELINE_NAME/jobs/$BUILD_JOB_NAME/builds/$BUILD_NAME
        text: $BUILD_PIPELINE_NAME <$ATC_EXTERNAL_URL/pipelines/$BUILD_PIPELINE_NAME/jobs/$BUILD_JOB_NAME/builds/$BUILD_NAME|#$BUILD_NAME> has been deployed

Examples

If you're interested in the API of Concourse resources and/or contributing to this resource, you can play with the out script using examples. There are some available in the examples folder.

Note: they have a params.debug set so that it only prints out the data structures rather than attempting to invoke the Slack API. Remove it and set a real Slack API to test the script against Slack.

$: cat examples/combined_text_template_and_file_empty.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "text": ":some_emoji:<https://my-ci.my-org.com//pipelines/cf-java-client/jobs/deploy/builds/305|Alert!>
_(no notification provided)_
",
  "username": "concourse"
}

$: cat examples/combined_text_template_and_file_missing.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "text": ":some_emoji:<https://my-ci.my-org.com//pipelines/cf-java-client/jobs/deploy/builds/305|Alert!>
_(no notification provided)_
",
  "username": "concourse"
}

$: cat examples/combined_text_template_and_file.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "text": ":some_emoji:<https://my-ci.my-org.com//pipelines/cf-java-client/jobs/deploy/builds/305|Alert!>
This text came from sample.txt. It could have been generated by a previous Concourse task.

Multiple lines are allowed.

",
  "username": "concourse"
}

$: cat examples/text_file_empty.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "username": "concourse",
  "text": "_(no notification provided)_"
}

$: cat examples/text_file.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "username": "concourse",
  "text": "This text came from sample.txt. It could have been generated by a previous Concourse task.

Multiple lines are allowed.
"
}

$: cat examples/text.out | ./out .
Webhook URL:  https://some.url
Webhook Body:
{
  "text": "Inline static text",
  "username": "concourse"
}

nebhale/slack-notification-resource