Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cloudfoundry-community/slack-notification-resource

Concourse CI resource for sending notifications to Slack.
https://github.com/cloudfoundry-community/slack-notification-resource

Last synced: 4 months ago
JSON representation

Concourse CI resource for sending notifications to Slack.

Awesome Lists containing this project

README 

          
[![Docker Stars](https://img.shields.io/docker/stars/cfcommunity/slack-notification-resource.svg?style=plastic)](https://registry.hub.docker.com/v2/repositories/cfcommunity/slack-notification-resource/stars/count/)

[![Docker pulls](https://img.shields.io/docker/pulls/cfcommunity/slack-notification-resource.svg?style=plastic)](https://registry.hub.docker.com/v2/repositories/cfcommunity/slack-notification-resource)



[![dockeri.co](https://dockeri.co/image/cfcommunity/slack-notification-resource)](https://hub.docker.com/r/cfcommunity/slack-notification-resource/)



Slack notification sending resource

===================================



Sends messages to [Slack](https://slack.com).



Resource Type Configuration

---------------------------



```yaml

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

.



- `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 to `false` 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 to `true` to use an HTTP

  proxy as an HTTPS tunnel.



- `disable`: *Optional.* Set to `true` to skip all messaging.

  Convenient for temporarily disabling notifications without editing

  your pipelines.



- `ca_certs`: *Optional.* An array of objects with the following

  format:



  ```yaml

  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:



```yaml

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:



- `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][attach]

  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

`` or ``.



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 ` ` 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][uidmap].

You can read more on how to mention users/channels in the [Slack

documentation on linking to channels and users][chans].



Note that the old `<@username>` format will soon no longer be

supported by Slack (See [changelog][cl2017]).



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 both `attachments` and

  `attachments_file` are omitted, and `text` 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. If `channel` is also specified, the

  two lists will be concatenated.



- `env_file`: *Optional.* File that contains a list of `key=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][build].



[attach]: https://api.slack.com/reference/messaging/attachments

[uidmap]: https://api.slack.com/changelog/2017-09-the-one-about-usernames#mapping

[chans]:  https://api.slack.com/docs/message-formatting#linking_to_channels_and_users

[cl2017]: https://api.slack.com/changelog/2017-09-the-one-about-usernames

[build]:  https://api.slack.com/docs/formatting/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:



```yaml

---

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][meta] for a complete list of

available metadata.



[meta]:   https://concourse-ci.org/implementing-resource-types.html#resource-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:\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:\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:\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][hub]:



    $ make VERSION=x.y.z release



[hub]:    https://hub.docker.com/r/cfcommunity/slack-notification-resource



## Authors 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](./LICENSE).