search

cloudfoundry-community / slack-notification-resource

Concourse CI resource for sending notifications to Slack.
MIT License
75 stars 81 forks source link

readme

Docker Stars Docker pulls

dockeri.co

Slack notification sending resource

Sends messages to Slack.

Resource Type Configuration

resource_types:
  - name: slack-notification
    type: docker-image
    source:
      repository: cfcommunity/slack-notification-resource
      tag:        latest

The tag: latest source property is optional, as the value latest in the default.

Source Configuration

To setup an Incoming Webhook, go to https://my.slack.com/services/new/incoming-webhook/.

Example:

resources:
  - name: slack-alert
    type: slack-notification
    source:
      url: https://hooks.slack.com/services/XXXX

Behavior

check Step (check script): No operation

Checking for new version always returns the last timestamp-based dummy version, created when the last put step was executed on this resource.

get Step (in script): No operation

Getting a new version of this resource does nothing else that always returning the last timestamp-based dummy version, created when the last put step was executed on this resource.

put Step (out script): Sends a message to Slack.

Send a message to Slack, with the configured parameters.

Parameters

You must specify one or more of the following:

If you omit the text parameter, the content of the file specified in the text_file parameter will be used verbatim. Alternatively, you can include the environment variable $TEXT_FILE_CONTENT in the text string to include the content of the file with other static text and interpolated variables (see Metadata section below.

If you use text without using the $TEXT_FILE_CONTENT in it, the content will not be added to your message.

The text and text_file content can contain multiple lines, emojis like :simple_smile:, and links in form <http://example.com> or <http://example.com|Click here!>.

To mention a user, you will have to use the <@U123ABC> format, where U123ABC is the user ID. You can get a user's user ID by browsing their profile and using the ⌵ control to display and quickly copy and paste a specific user's ID. You can @mention a group using <!subteam^S0123456789> You can find the user_groups id through the url on the slack website. For more ways, see the Slack documentation on username/user ID mapping. You can read more on how to mention users/channels in the Slack documentation on linking to channels and users.

Note that the old <@username> format will soon no longer be supported by Slack (See changelog).

If you omit the attachments parameter, the contents of the file specified in the attachments_file parameter will be used verbatim. If the attachments parameter is set, then attachments_file will be ignored. There is no way to use both at the same time.

Under the philosophy that its better to write something than fail silently, the following will be sent under these conditions:

Optional:

Explore formatting with Slack's Message Builder.

Metadata

Various metadata is available in the form of environment variables. Any environment variables present in the parameters will be automatically evaluated; this enables dynamic parameter content.

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

---
jobs:
- name: some-job
  plan:
  - put: slack-alert
    params:
      channel: '#my_channel'
      text_file: results/message.txt
      text: |
        The build had a result. Check it out at:
        http://my.concourse.url/teams/$BUILD_TEAM_NAME/pipelines/$BUILD_PIPELINE_NAME/jobs/$BUILD_JOB_NAME/builds/$BUILD_NAME
        or at:
        http://my.concourse.url/builds/$BUILD_ID

        Result: $TEXT_FILE_CONTENT

See the official documentation for a complete list of available metadata.

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 test 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 test/combined_text_template_and_file_empty.out | ./out .
webhook_url: https://some.url
body: {
  "text": ":some_emoji:<https://my-ci.my-org.com//teams//main//pipelines//jobs//builds/|Alert!>\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

> cat test/combined_text_template_and_file_missing.out | ./out .
webhook_url: https://some.url
body: {
  "text": ":some_emoji:<https://my-ci.my-org.com//teams//main//pipelines//jobs//builds/|Alert!>\n_(no notification provided)_\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

> cat test/combined_text_template_and_file.out | ./out .
webhook_url: https://some.url
body: {
  "text": ":some_emoji:<https://my-ci.my-org.com//teams//main//pipelines//jobs//builds/|Alert!>\nThis text came from sample.txt. It could have been generated by a previous Concourse task.\n\nMultiple lines are allowed.\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

> cat test/text_file_empty.out | ./out .
webhook_url: https://some.url
body: {
  "text": "_(missing notification text)_\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

> cat test/text_file.out | ./out .
webhook_url: https://some.url
body: {
  "text": "This text came from sample.txt. It could have been generated by a previous Concourse task.\n\nMultiple lines are allowed.\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

> cat test/text.out | ./out .
webhook_url: https://some.url
body: {
  "text": "Inline static text\n",
  "username": "concourse",
  "icon_url": null,
  "icon_emoji": null,
  "channel": null
}

Release Engineering

To build local versions of this, for testing:

$ docker build -t slack-notification-resources

Tests will run as part of the build, and be left in the image for future testing. This adds about 100k to the image.

To cut a new officialy release of the cfcommunity/slack-notification-resource image on Docker Hub:

$ make VERSION=x.y.z release

Author and license

Copyright © 2017-2020, James Hunt Copyright © 2021-present, Benjamin Gandon, Gstack

The Slack notification resource is released under the terms of the MIT license.