thecodedrift/[email protected]

Because sometimes, you just want a mutliline markdown friendly message sent to slack. With variables.

Usage

steps:
  - name: Checkout
    uses: actions/checkout@v2
  - name: Notifying via Slack
    uses: thecodedrift/[email protected]
    with:
      token: ${{secrets.SLACK_BOT_KEY}} # your slack bot key
      secret: ${{secrets.SLACK_SIGNING_SECRET}} # your slack signing secret
      channel: ${{secrets.SLACK_CHANNEL}} # your slack channel
      # evals - a string of statements (1 per line), assigning the results of a
      # shell command to the left-hand side of the equal (=). In this example,
      # we are running a `git log` command with specific formatting, and then
      # saving the result to a variable called "changelog"
      #
      # Supports Handlebars templating. Don't forget to escape backticks and
      # quotes as needed
      evals: |
        changelog = git log --reverse --color=never --pretty='tformat:%xe2%x80%xa2 `%h` %s (%ae)' {{context.payload.push.before}}...{{context.payload.push.head}}
      # message - a string to send to Slack
      # Supports Markdown and Handlebars
      message: |
        *Something Got Pushed!*
        `{{context.payload.push.before}}...{{context.payload.push.head}}`
        {{evals.changelog}}

Table of Contents

• thecodedrift/[email protected]
• Usage
• Table of Contents
• Action Parameters
  • Finding Your Slack Settings
• Using the evals Parameter
  • If running git operations
• Handlebars Usage
  • What's in that context object?
  • Formatting with Handlebars
    • cut (Handlebars Helper)
    • Accepting PRs for Handlebars Helpers
• Developing (from original readme)
  • Package for distribution
  • Create a release branch

Action Parameters

name	description
channel	⚠️ Should be loaded as a Github Secret Your Slack channel ID you wish to post to.
dry-run	Do not perform a slack notification, instead dumping the message to your Github Action output
dump	Dump the contents of your payload used to format Handlebars messages. channel, secret, and token are masked
evals	A list of newline-delimited commands to run in order to create variables for your slack message. See the section on evals for details
message	The slack message to send
secret	⚠️ Should be loaded as a Github Secret Your Slack Bot's Signing Secret. We use @slack/bolt for composing messages to avoid maintaining as much code as possible. Bolt requires a signing secret on initialization, even if we're not planning to listen for inbound requests.
token	⚠️ Should be loaded as a Github Secret Your Slack Bot token, beginning with xoxb-. Bot tokens are more resilient than webhook tokens. You'll need the chat:write, chat:write.customize, and chat:write.public permissions at a minimum to be able to send messages to any channel in your Slack workspace.

Finding Your Slack Settings

• token: https://api.slack.com/apps > <your app> > OAuth & Permissions > field named: "Bot User OAuth Access Token"
• secret: https://api.slack.com/apps > <your app> > section named: "App Credentials" > field named: "Client Secret"
• channel:
  • On Desktop right click channel and select "Copy Link" > https://your-workspace.slack.com/archives/[this-is-your-channel-id] (it should begin with C)
  • On Web select your channel from the sidebar > https://app.slack.com/client/[this-is-your-team]/[this-is-your-channel-id] (it should begin with C)

Using the evals Parameter

Many times, slack notifications need additional information such as git commit subjects or the output of running a shell command. The evals block enables you to run any command available via shell code and capture it for usage in your slack message. Each line in evals is a command.

saveAs = command --to --run remeber_to_escape

Commands are spawned using @actions/exec with stdout and stderr captured for cross platform compatibility.

Each evaluated line is saved to the lefthand side of the assignment and available in all future commands and slack messages as {{evals.__your_saved_name__}}.

If running git operations

If you're planning on calling git operations, remember to update your checkout to fetch all history. By default, Github Actions only check out the most recent commit for the purpose of tests. Setting a fetch-depth of 0 will enable you to call git commands that span your repo's history.

steps:
  - name: Checkout
    uses: actions/checkout@v2
    with:
      fetch-depth: 0 # all history required

Handlebars Usage

What's in that context object?

View A Sample Dumped Context

The context object available to your handlebars template is the same context object used by Octokit. It contains a payload object which is your webhook payload, along with a variety of other items connected to your Job, including sha, ref, and workflow.

{
  //...
  "context": {
    "payload": {
      /* Specific based on type of event, sample below */
      "pull_request": {}
    },
    "eventName": "pull_request",
    "sha": "94933e1fe203d34a3ed73033c6fb04eb07715de4",
    "ref": "refs/heads/thecodedrift/docker_smash_2",
    "workflow": "Pilot",
    "action": "1",
    "actor": "nektos/act"
  }
}

Formatting with Handlebars

Shell commands and the Slack message both support formatting with the Handlebars template engine. You'll receive the following variables inside of the Handlebars template:

name	type	description
context.payload	object	Contains the webhook payload
context.eventName	string	One of the triggering Github Action events
env.*	object	Contains the current process.env as of script execution
evals.*	object	Contains the assigned output from the evals parameter in this action
inputs.*	object	Contains the inputs message, raw, and channel as provided to this action

cut (Handlebars Helper)

# reduce a string to its first N characters
# useful for constructing things such as short hashes
# cut [string]                    [N]
{{cut context.payload.before  8  }}

Accepting PRs for Handlebars Helpers

At creation, it made sense to only include the absolute minimum helpers that would make writing scripts and Slack messages easier. For example, cut offers a convenient way to shorten sha1 hashes. If you have ideas, open an issue or PR. We just ask that you include an example of how this helps compared to regular 'ole bash scripting. (And yes, "the bashism to do X is absurd" is valid)

Developing (from original readme)

This is based on the javascript-action template.

Package for distribution

GitHub Actions will run the entry point from the action.yml. Packaging assembles the code into one file that can be checked in to Git, enabling fast and reliable execution and preventing the need to check in node_modules.

Actions are run from GitHub repos. Packaging the action will create a packaged action in the dist folder.

Run package

npm run package

Since the packaged index.js is run from the dist folder.

git add dist

Create a release branch

Users shouldn't consume the action from master since that would be latest code and actions can break compatibility between major versions.

Checkin to the v(x) release branch

$ git checkout -b v(x)
$ git commit -a -m "v(x) release"

$ git push origin v(x)

Your action is now published! 🚀

See the versioning documentation