semantic-release-slack-with-files

A custom semantic-release plugin for sending Slack notifications about new releases, with support for:

• Attaching release assets (e.g., binaries, archives).
• Handling glob patterns and placeholders like ${nextRelease.version}.
• Detailed release messages, including descriptions, changelogs, and download links.
• Prerelease-specific configurations.
• Robust error handling to notify users if something goes wrong.

Installation

Install the plugin as a dependency in your project:

npm install siredmar/semantic-release-slack-with-files -D

Configuration

Add the plugin to your .releaserc.json or .releaserc.js file. Below is an example configuration:

{
  "branches": [
    { "name": "master" },
    { "name": "beta", "prerelease": true }
  ],
  "plugins": [
    [
      "siredmar/semantic-release-slack-with-files",
      {
        "assets": {
          "dist/myfancytool_${nextRelease.version}_*.tar.gz": "Linux Distributions",
          "dist/myfancytool_${nextRelease.version}_Windows_*.zip": "Windows Distributions"
        },
        "changelog": true,
        "lastCommitText": true,
        "message": "We are excited about our new release of `myfancytool` ${nextRelease.version} 🎉🎉🎉\n\n",
        "lastLine": "_Thank you for your continued support!_ 🙌",
        "prerelease": {
          "enabled": true,
          "changelog": false,
          "lastCommitText": true,
          "message": "🚀 Prerelease: `myfancytool` ${nextRelease.version} 🚧\n\n",
          "lastLine": "_This is an experimental build._ 🔬"
        }
      }
    ]
  ]
}

Plugin Options

• assets (required):

  • A mapping of file paths or glob patterns to labels (e.g., "dist/file.tar.gz": "Linux Build").
  • Supports placeholders like ${nextRelease.version}.

• changelog (boolean):

  • If true, includes the changelog generated by @semantic-release/release-notes-generator in the Slack message.

• lastCommitText (boolean):

  • If true, includes the body of the last commit (excluding the title and any Signed-off-by/Co-authored-by lines) as a description.

• message (string):

  • The main release message. Placeholders like ${nextRelease.version} and ${nextRelease.notes} are supported.

• lastLine (string):

  • A custom string appended to the end of the Slack message.

• prerelease (object):

  • Contains overrides for prerelease branches:
    • enabled (boolean): Enable/disable the notification for prerelease branches.
    • changelog (boolean): Include changelog in prerelease messages.
    • lastCommitText (boolean): Include the last commit text in prerelease messages.
    • message (string): Custom prerelease message.
    • lastLine (string): Custom last line for prerelease messages.

Environment Variables

The following environment variables must be set:

• SLACK_TOKEN: Your Slack bot token.
• SLACK_CHANNEL: The Slack channel ID or name where the message will be sent.

Features

Asset Uploads with Glob Patterns

The assets field supports glob patterns, allowing you to upload multiple files easily:

{
  "assets": {
    "dist/myfancytool_${nextRelease.version}_*.tar.gz": "Linux Distributions"
  }
}

If any required assets are not found, the plugin will:

• Post an error message in the Slack thread.
• Edit the original announcement to indicate the release should not be used.
• Fail the semantic-release pipeline.

Prerelease Handling

Prerelease branches (e.g., beta) can have their own configuration:

{
  "prerelease": {
    "enabled": true,
    "changelog": false,
    "lastCommitText": true,
    "message": "🚀 Prerelease: `myfancytool` ${nextRelease.version} 🚧\n\n",
    "lastLine": "_This is an experimental build._ 🔬"
  }
}

This ensures prerelease builds are clearly marked and handled differently.

Error Handling

If an error occurs during execution:

• A message is posted in the Slack thread with details of the error.
• The original announcement message is updated with a prominent note, advising users not to use the release.

Example of an updated message:

🚀 New release: 0.43.0 🎉🎉🎉

📖 Description:
This release is all about bringing it to live.
We took care of preparing everything well and good tested.
Let's hope for the best!

📝 Changelog:
- Another cool feature

📥 Download Links:
• Linux AMD64: [Download](#)
• macOS ARM64: [Download](#)

:x: *An issue occurred with this release. Users are advised NOT to use this version.*

Example Workflow

1. Install the plugin:

   npm install siredmar/semantic-release-slack-with-files -D

2. Configure your .releaserc.json:

   {
     "branches": ["master", "beta"],
     "plugins": [
       ["siredmar/semantic-release-slack-with-files", { ... }]
     ]
   }

3. Run semantic-release:

   npx semantic-release

4. Slack Notifications:

   • Successful release: Sends a message with release details and download links.
   • Error handling: Posts errors in a thread and updates the original message.

License

MIT