-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Add readme and examples, fix broken input * Add an example with webhooks * Revert input rename for now --------- Co-authored-by: Krisztián Gödrei <[email protected]>
- Loading branch information
Showing
3 changed files
with
174 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,87 +1,163 @@ | ||
| # Slack Message step | ||
| # Send a Slack message | ||
|
|
||
| Send a Slack message from your [bitrise](https://www.bitrise.io/cli) build! | ||
| [](https://github.com/bitrise-io/steps-slack-message/releases) | ||
|
|
||
| Send a [Slack](https://slack.com/) message to a channel or group. | ||
|
|
||
| ## How to use this Step | ||
| <details> | ||
| <summary>Description</summary> | ||
|
|
||
| Can be run directly with the [bitrise CLI](https://github.com/bitrise-io/bitrise), | ||
| just `git clone` this repository, `cd` into it's folder in your Terminal/Command Line | ||
| and call `bitrise run test`. | ||
|
|
||
| *Check the `bitrise.yml` file for required inputs which have to be | ||
| added to your `.bitrise.secrets.yml` file!* | ||
| Send a [Slack](https://slack.com/) message to a Slack user, a group, or a channel. Create and customize the messages however you see fit. Among other things, you can: | ||
|
|
||
| Step by step: | ||
| - Set a different text for failed and successful builds. | ||
| - Add an icon and/or emojis to your messages. | ||
| - Set the bot user's name for the messages. | ||
| - Linkify channel names and usernames. | ||
| - Add and customize attachments. | ||
|
|
||
| 1. Open up your Terminal / Command Line | ||
| 2. `git clone` the repository | ||
| 3. `cd` into the directory of the step (the one you just `git clone`d) | ||
| 5. Create a `.bitrise.secrets.yml` file in the same directory of `bitrise.yml` - the `.bitrise.secrets.yml` is a git ignored file, you can store your secrets in | ||
| 6. Check the `bitrise.yml` file for any secret you should set in `.bitrise.secrets.yml` | ||
| * Best practice is to mark these options with something like `# define these in your .bitrise.secrets.yml`, in the `app:envs` section. | ||
| 7. Once you have all the required secret parameters in your `.bitrise.secrets.yml` you can just run this step with the [bitrise CLI](https://github.com/bitrise-io/bitrise): `bitrise run test` | ||
| ### Configuring the Step | ||
|
|
||
| An example `.bitrise.secrets.yml` file: | ||
| To use this Step, you need either a configured Slack Integration in your workspace, an incoming Slack webhook or a Slack bot user with an API token. For the former see your Workspace settings, for the latter two, you can set them up in Slack: | ||
|
|
||
| ``` | ||
| envs: | ||
| - A_SECRET_PARAM_ONE: the value for secret one | ||
| - A_SECRET_PARAM_TWO: the value for secret two | ||
| ``` | ||
| - [Incoming webhooks](https://api.slack.com/incoming-webhooks). | ||
| - [Bot user with an API token](https://api.slack.com/bot-users). | ||
|
|
||
| ## How to create your own step | ||
| Once you're ready with those, come back to Bitrise and configure the Step itself: | ||
|
|
||
| 1. Create a new git repository for your step (**don't fork** the *step template*, create a *new* repository) | ||
| 2. Copy the [step template](https://github.com/bitrise-steplib/step-template) files into your repository | ||
| 3. Fill the `main.go` with your functionality | ||
| 4. Wire out your inputs to `step.yml` (`inputs` section) | ||
| 5. Fill out the other parts of the `step.yml` too | ||
| 6. Provide test values for the inputs in the `bitrise.yml` | ||
| 7. Run your step with `bitrise run test` - if it works, you're ready | ||
| 1. Create a [Secret Env Var](https://devcenter.bitrise.io/builds/env-vars-secret-env-vars/) for either your Slack webhook URL or your Slack API token. | ||
| 1. Add the Secret to either the **Slack Webhook URL** or the **Slack API token** input. | ||
| 1. Toggle the **Run if previous Step failed** option on - you should see a white checkmark on green background next to it. This allows Slack messages to be sent for failed builds, too. | ||
| 1. In the **Target Slack channel, group or username**, set where the Slack message should be sent. | ||
| 1. Customize your messages as you'd like. For the details, see the respective inputs. | ||
|
|
||
| __For Step development guidelines & best practices__ check this documentation: [https://github.com/bitrise-io/bitrise/blob/master/_docs/step-development-guideline.md](https://github.com/bitrise-io/bitrise/blob/master/_docs/step-development-guideline.md). | ||
|
|
||
| **NOTE:** | ||
| In case of the Slack Integration usecase you can copy the ID in your Workspace settings, on the Integrations page. This ID is not senstive, you can use it as a step input as-is, or put it into a regular environment variable. | ||
|
|
||
| If you want to use your step in your project's `bitrise.yml`: | ||
| Note that this step always sends a message (either to `channel` or `channel_on_error`). If your use case is to send a message only on success or on failure, then you can [run the entire step conditionally](https://devcenter.bitrise.io/en/steps-and-workflows/introduction-to-steps/enabling-or-disabling-a-step-conditionally.html). | ||
|
|
||
| 1. git push the step into it's repository | ||
| 2. reference it in your `bitrise.yml` with the `git::PUBLIC-GIT-CLONE-URL@BRANCH` step reference style: | ||
| ### Troubleshooting | ||
|
|
||
| ``` | ||
| - git::https://github.com/user/my-step.git@branch: | ||
| title: My step | ||
| inputs: | ||
| - my_input_1: "my value 1" | ||
| - my_input_2: "my value 2" | ||
| ``` | ||
| If the Step fails, check your Slack settings, the incoming webhook or the API token, and your Slack channel permissions. | ||
|
|
||
| ### Useful links | ||
|
|
||
| - [Integrating with Slack](https://devcenter.bitrise.io/builds/configuring-notifications/#integrating-with-slack) | ||
| - [Slack attachments](https://api.slack.com/messaging/composing/layouts#attachments) | ||
|
|
||
| ### Related Steps | ||
|
|
||
| You can find more examples of step reference styles | ||
| in the [bitrise CLI repository](https://github.com/bitrise-io/bitrise/blob/master/_examples/tutorials/steps-and-workflows/bitrise.yml#L65). | ||
| - [Send email with Mailgun](https://www.bitrise.io/integrations/steps/email-with-mailgun) | ||
| - [Post Jira Comment](https://www.bitrise.io/integrations/steps/post-jira-comment-with-build-details) | ||
| </details> | ||
|
|
||
| ## How to contribute to this Step | ||
| ## 🧩 Get started | ||
|
|
||
| 1. Fork this repository | ||
| 2. `git clone` it | ||
| 3. Create a branch you'll work on | ||
| 4. To use/test the step just follow the **How to use this Step** section | ||
| 5. Do the changes you want to | ||
| 6. Run/test the step before sending your contribution | ||
| * You can also test the step in your `bitrise` project, either on your Mac or on [bitrise.io](https://www.bitrise.io) | ||
| * You just have to replace the step ID in your project's `bitrise.yml` with either a relative path, or with a git URL format | ||
| * (relative) path format: instead of `- original-step-id:` use `- path::./relative/path/of/script/on/your/Mac:` | ||
| * direct git URL format: instead of `- original-step-id:` use `- git::https://github.com/user/step.git@branch:` | ||
| * You can find more example of alternative step referencing at: https://github.com/bitrise-io/bitrise/blob/master/_examples/tutorials/steps-and-workflows/bitrise.yml | ||
| 7. Once you're done just commit your changes & create a Pull Request | ||
| Add this step directly to your workflow in the [Bitrise Workflow Editor](https://devcenter.bitrise.io/steps-and-workflows/steps-and-workflows-index/). | ||
|
|
||
| You can also run this step directly with [Bitrise CLI](https://github.com/bitrise-io/bitrise). | ||
|
|
||
| ## Share your own Step | ||
| ### Examples | ||
|
|
||
| You can share your Step or step version with the [bitrise CLI](https://github.com/bitrise-io/bitrise). Just run `bitrise share` and follow the guide it prints. | ||
| #### Using OAuth integration (recommended) | ||
|
|
||
| First, set up the integration between your Bitrise Workspace and your Slack instance. Go to Bitrise _Workspace Settings > Integrations_, select _Slack_, then follow the instructions. | ||
|
|
||
| Once the two services are connected, copy the integration ID (under the `...` menu) and pass it as an input to this step. This ID is not senstive, you can use it as a step input as-is, or put it into a regular environment variable. | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - slack: | ||
| title: Notify team | ||
| inputs: | ||
| - workspace_slack_integration_id: example | ||
| - message: This is a test notification, please ignore | ||
| - emoji: ":bitrise:" | ||
| ``` | ||
| #### Using webhooks | ||
| To register an Incoming WebHook integration visit: https://api.slack.com/incoming-webhooks. | ||
| ```yaml | ||
| steps: | ||
| - slack: | ||
| title: Notify team | ||
| inputs: | ||
| - webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX | ||
| - message: This is a test notification, please ignore | ||
| - emoji: ":bitrise:" | ||
| ``` | ||
| ## Trigger a new release | ||
| - __merge every code changes__ to the `master` branch | ||
| - __push the new version tag__ to the `master` branch | ||
| ## ⚙️ Configuration | ||
| <details> | ||
| <summary>Inputs</summary> | ||
| | Key | Description | Flags | Default | | ||
| | --- | --- | --- | --- | | ||
| | `is_debug_mode` | Step prints additional debug information if this option is enabled | | `no` | | ||
| | `webhook_url` | **One of workspace\_integration\_id, webhook\_url or api\_token input is required.** To register an **Incoming WebHook integration** visit: https://api.slack.com/incoming-webhooks | sensitive | | | ||
| | `webhook_url_on_error` | **One of workspace\_integration\_id, webhook\_url or api\_token input is required.** To register an **Incoming WebHook integration** visit: https://api.slack.com/incoming-webhooks | sensitive | | | ||
| | `workspace_slack_integration_id` | **One of workspace\_integration\_id, webhook\_url or api\_token input is required.** To register a **Workspace Slack Integration** see the Integration page in your Workspace settings | | | | ||
| | `workspace_slack__integration_id_on_error` | **One of workspace\_integration\_id, webhook\_url or api\_token input is required.** To register a **Workspace Slack Integration** see the Integration page in your Workspace settings | | | | ||
| | `api_token` | **One of workspace\_integration\_id, webhook\_url or api\_token input is required.** To setup a **bot with an API token** visit: https://api.slack.com/bot-users | sensitive | | | ||
| | `channel` | Can be an encoded ID, or the channel's name. Examples: * channel ID: C024BE91L * channel: #general * username: @username | | | | ||
| | `channel_on_error` | * channel example: #general * username example: @username | | | | ||
| | `text` | Text of the message to send. Required unless you wish to send attachments only. | | | | ||
| | `text_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | | | ||
| | `emoji` | Optionally you can specify a Slack emoji as the sender icon. You can use the Ghost icon for example if you specify `:ghost:` here as an input. **If you specify an Icon URL then this Emoji input will be ignored!** | | | | ||
| | `emoji_on_error` | **This option will be used if the build failed.** If you leave this option empty then the default one will be used. | | | | ||
| | `icon_url` | Optionally, you can specify a custom icon image URL which will be presented as the sender icon. Slack recommends an image a square image, which can't be larger than 128px in either width or height, and it must be smaller than 64K in size. Slack custom emoji guideline: [https://slack.zendesk.com/hc/en-us/articles/202931348-Using-emoji-and-emoticons](https://slack.zendesk.com/hc/en-us/articles/202931348-Using-emoji-and-emoticons) If you specify this input, the **Emoji** input will be ignored! | | `https://github.com/bitrise-io.png` | | ||
| | `icon_url_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | `https://github.com/bitrise-io.png` | | ||
| | `link_names` | Linkify names in the message such as `@slackbot` or `#random` | | `yes` | | ||
| | `from_username` | The username of the bot user which will be presented as the sender of the message | | `Bitrise` | | ||
| | `from_username_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | `Bitrise` | | ||
| | `thread_ts` | Sends the message as a reply to the message with the given ts if set (in a thread). | | | | ||
| | `thread_ts_on_error` | Sends the message as a reply to the message with the given ts if set (in a thread) if the build failed. | | | | ||
| | `ts` | Timestamp of the message to be updated. When **Message Timestamp** is provided an existing Slack message will be updated, identified by the provided timestamp. Example: `"1405894322.002768"`. | | | | ||
| | `ts_on_error` | Timestamp of the message to be updated if the build failed. When **Message Timestamp if the build failed** is provided an existing Slack message will be updated, identified by the provided timestamp. Example: `"1405894322.002768"`. | | | | ||
| | `reply_broadcast` | Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation | | `no` | | ||
| | `reply_broadcast_on_error` | Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation | | `no` | | ||
| | `color` | Color is used to color the border along the left side of the attachment. Can either be one of good, warning, danger, or any hex color code (eg. #439FE0). You can find more info about the color and other text formatting in [Slack's documentation](https://api.slack.com/docs/message-attachments). | required | `#3bc3a3` | | ||
| | `color_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | `#f0741f` | | ||
| | `pretext` | An optional text that appears above the attachment block. | | `*Build Succeeded!*` | | ||
| | `pretext_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | `*Build Failed!*` | | ||
| | `author_name` | A small text used to display the author's name. | | `$GIT_CLONE_COMMIT_AUTHOR_NAME` | | ||
| | `title` | Title is displayed as larger, bold text near the top of a attachment. | | `$GIT_CLONE_COMMIT_MESSAGE_SUBJECT` | | ||
| | `title_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | | | ||
| | `title_link` | A URL that will hyperlink the title. | | | | ||
| | `message` | Text is the main text of the attachment, and can contain standard message markup. The content will automatically collapse if it contains 700+ characters or 5+ linebreaks, and will display a "Show more..." link to expand the content. | | `$GIT_CLONE_COMMIT_MESSAGE_BODY` | | ||
| | `message_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | `$GIT_CLONE_COMMIT_MESSAGE_BODY` | | ||
| | `image_url` | A URL to an image file that will be displayed inside the attachment. Supported formats: GIF, JPEG, PNG, and BMP. Large images will be resized to a maximum width of 400px or a maximum height of 500px. | | | | ||
| | `image_url_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | | | ||
| | `thumb_url` | A URL to an image file that will be displayed as a thumbnail on the right side of a attachment. Supported formats: GIF, JPEG, PNG, and BMP. The thumbnail's longest dimension will be scaled down to 75px. | | | | ||
| | `thumb_url_on_error` | This option will be used if the build failed. If you leave this option empty then the default one will be used. | | | | ||
| | `footer` | The footer adds some brief text to help contextualize and identify an attachment. Limited to 300 characters. | | `Bitrise` | | ||
| | `footer_on_error` | The footer adds some brief text to help contextualize and identify an attachment. Limited to 300 characters. | | `Bitrise` | | ||
| | `footer_icon` | Renders a small icon beside the footer text It will be scaled down to 16px by 16px. | | `https://github.com/bitrise-io.png?size=16` | | ||
| | `footer_icon_on_error` | Renders a small icon beside the footer text It will be scaled down to 16px by 16px. | | `https://github.com/bitrise-io.png?size=16` | | ||
| | `timestamp` | Show the current time as part of the attachment's footer? | | `yes` | | ||
| | `fields` | Fields separated by newlines and each field contains a `title` and a `value`. The `title` and the `value` fields are separated by a pipe `\|` character. The *title* shown as a bold heading above the `value` text. The *value* is the text value of the field. Supports multiline text with escaped newlines. Example: `Release notes\| - Line1 \n -Line2`. Empty lines and lines without a separator are omitted. | | `App\|${BITRISE_APP_TITLE} Branch\|${BITRISE_GIT_BRANCH} Pipeline\|${BITRISEIO_PIPELINE_TITLE} Workflow\|${BITRISE_TRIGGERED_WORKFLOW_ID} ` | | ||
| | `buttons` | Buttons separated by newlines and each field contains a `text` and a `url`. The `text` and the `url` fields are separated by a pipe `\|` character. Empty lines and lines without a separator are omitted. The *text* is the label for the button. The *url* is the fully qualified http or https url to deliver users to. An attachment may contain 1 to 5 buttons. | | `View App\|${BITRISE_APP_URL} View Pipeline Build\|${BITRISEIO_PIPELINE_BUILD_URL} View Workflow Build\|${BITRISE_BUILD_URL} Install Page\|${BITRISE_PUBLIC_INSTALL_PAGE_URL} ` | | ||
| | `pipeline_build_status` | This status will be used to help choosing between _on_error inputs and normal ones when sending the slack message. | | `$BITRISEIO_PIPELINE_BUILD_STATUS` | | ||
| | `build_status` | This status will be used to help choosing between _on_error inputs and normal ones. | | `$BITRISE_BUILD_STATUS` | | ||
| | `output_thread_ts` | Will export the created thread's timestamp to the environment with the supplied name (if not already in thread) | | | | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Outputs</summary> | ||
| There are no outputs defined in this step | ||
| </details> | ||
|
|
||
| ## 🙋 Contributing | ||
|
|
||
| We welcome [pull requests](https://github.com/bitrise-io/steps-slack-message/pulls) and [issues](https://github.com/bitrise-io/steps-slack-message/issues) against this repository. | ||
|
|
||
| For pull requests, work on your changes in a forked repository and use the Bitrise CLI to [run step tests locally](https://devcenter.bitrise.io/bitrise-cli/run-your-first-build/). | ||
|
|
||
| Learn more about developing steps: | ||
|
|
||
| - [Create your own step](https://devcenter.bitrise.io/contributors/create-your-own-step/) | ||
| - [Testing your Step](https://devcenter.bitrise.io/contributors/testing-and-versioning-your-steps/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| ### Examples | ||
|
|
||
| #### Using OAuth integration (recommended) | ||
|
|
||
| First, set up the integration between your Bitrise Workspace and your Slack instance. Go to Bitrise _Workspace Settings > Integrations_, select _Slack_, then follow the instructions. | ||
|
|
||
| Once the two services are connected, copy the integration ID (under the `...` menu) and pass it as an input to this step. This ID is not senstive, you can use it as a step input as-is, or put it into a regular environment variable. | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - slack: | ||
| title: Notify team | ||
| inputs: | ||
| - workspace_slack_integration_id: example | ||
| - message: This is a test notification, please ignore | ||
| - emoji: ":bitrise:" | ||
| ``` | ||
| #### Using webhooks | ||
| To register an Incoming WebHook integration visit: https://api.slack.com/incoming-webhooks. | ||
| ```yaml | ||
| steps: | ||
| - slack: | ||
| title: Notify team | ||
| inputs: | ||
| - webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX | ||
| - message: This is a test notification, please ignore | ||
| - emoji: ":bitrise:" | ||
| ``` |