Sends messages to Slack.
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.
To setup an Incoming Webhook, go to https://my.slack.com/services/new/incoming-webhook/.
-
url
: Required. The webhook URL as provided by Slack. Usually in the form:https://hooks.slack.com/services/XXXX
. -
insecure
: Optional. Connect to Slack insecurely - i.e. skip SSL validation. Defaults tofalse
if not provided. -
proxy
: Optional. Connect to Slack using an HTTP(S) proxy. In the form:http://my.proxy:3128
. -
proxy_https_tunnel
: Optional. Set totrue
to use an HTTP proxy as an HTTPS tunnel. -
disable
: Optional. Set totrue
to skip all messaging. Convenient for temporarily disabling notifications without editing your pipelines. -
ca_certs
: Optional. An array of objects with the following format:ca_certs: - domain: example.com cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- - domain: 10.244.6.2 cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
Each entry specifies the x509 CA certificate for the trusted domain.
Example:
resources:
- name: slack-alert
type: slack-notification
source:
url: https://hooks.slack.com/services/XXXX
Checking for new version always returns the last timestamp-based dummy
version, created when the last put
step was executed on this resource.
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.
Send a message to Slack, with the configured parameters.
You must specify one or more of the following:
-
text
: Static text of the message to send. -
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. -
attachments
: An array of one or more message attachments. See the Slack documentation on message attachments for the message structure. -
attachments_file
: File that contains the json attachments array to send. This parameter allows the attachments to be generated by a previous task step in the Concourse job.
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:
-
when
text
,attachments
,attachments_file
are 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 and bothattachments
andattachments_file
are omitted, andtext
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:- no notification is sent
Optional:
-
channel
: Optional. Override channel to send message to.#channel
and@user
forms are allowed. You can notify multiple channels separated by whitespace, like#channel @user
. -
channel_file
: Optional. File that contains a list of channels to send message to. Ifchannel
is also specified, the two lists will be concatenated. -
env_file
: Optional. File that contains a list ofkey=value
environment variables that will be available in your slack messages template. -
username
: Optional. Override name of the sender of the message. -
icon_url
: Optional. Override icon by providing URL to the image. -
icon_emoji
: Optional. Override icon by providing emoji code (e.g.:ghost:
). -
silent
: Optional. Do not print curl output (avoids leaking slack webhook URL). -
always_notify
: Optional. Attempt to notify even if there are errors or missing text. (Expects true or false, defaults to false).
Explore formatting with Slack's Message Builder.
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.
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
}
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
Copyright © 2017-2020, James Hunt Copyright © 2021-present, Benjamin Gandon, Gstack
The Slack notification resource is released under the terms of the MIT license.