semantic-release-clickup

semantic-release plugin to announce releases to a ClickUp chat channel.

Install

pnpm add -D @kozyops/semantic-release-clickup

Usage

Add the plugin to your semantic-release configuration:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@kozyops/semantic-release-clickup", {
      "workspaceId": "12345678",
      "channelId": "abc-def-123"
    }]
  ]
}

Set the CLICKUP_TOKEN environment variable to your ClickUp personal API token (starts with pk_). You can create one at Settings > Apps in ClickUp.

Configuration

Environment Variables

| Variable | Required | Description | |---|---|---| | CLICKUP_TOKEN | Yes | ClickUp personal API token (pk_...) | | CLICKUP_WORKSPACE_ID | Fallback | Workspace ID (if not set in plugin config) | | CLICKUP_CHANNEL_ID | Fallback | Channel ID (if not set in plugin config) |

Plugin Options

| Option | Type | Default | Description | |---|---|---|---| | workspaceId | string | $CLICKUP_WORKSPACE_ID | ClickUp workspace ID | | channelId | string | $CLICKUP_CHANNEL_ID | Chat channel ID to post to | | messageType | "post" \| "message" | "message" | Message type. "post" includes a title, but ClickUp may reject post payloads without workspace-specific post metadata. | | notifyOnSuccess | boolean | true | Send a message on successful release | | notifyOnFail | boolean | false | Send a message on release failure | | packageName | string | npm_package_name | Package name used in messages | | successTitle | string \| function | "Released ${packageName} v${version}" | Title for success post | | successMessage | string \| function | See below | Body template for success | | failTitle | string \| function | "Release failed: ${packageName}" | Title for failure post | | failMessage | string \| function | See below | Body template for failure |

Template Variables

String templates support ${variable} interpolation:

Success templates: ${version}, ${gitTag}, ${channel}, ${notes}, ${packageName}, ${repositoryUrl}

Fail templates: ${packageName}, ${repositoryUrl}, ${errors}

Function Templates

For full control, pass a function instead of a string:

["@kozyops/semantic-release-clickup", {
  workspaceId: "12345678",
  channelId: "abc-def-123",
  successMessage: ({ version, commits, packageName }) =>
    `**${packageName}** v${version} shipped with ${commits.length} commits!`,
}]

Finding Your Workspace & Channel IDs

Workspace ID: Look at your ClickUp URL — https://app.clickup.com/{workspace_id}/home

Channel ID: Use the ClickUp API to list channels:

curl -H "Authorization: $CLICKUP_TICKET_SKILL_TOKEN" \
  "https://api.clickup.com/api/v3/workspaces/YOUR_WORKSPACE_ID/chat/channels"

Examples

Minimal (env vars only)

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@kozyops/semantic-release-clickup", {}]
  ]
}

CLICKUP_TOKEN=pk_... CLICKUP_WORKSPACE_ID=123 CLICKUP_CHANNEL_ID=abc pnpm exec semantic-release

With failure notifications

["@kozyops/semantic-release-clickup", {
  "workspaceId": "12345678",
  "channelId": "abc-def-123",
  "notifyOnFail": true
}]

Plain message (no title)

["@kozyops/semantic-release-clickup", {
  "workspaceId": "12345678",
  "channelId": "abc-def-123",
  "messageType": "message"
}]

Post messages

ClickUp post payloads can require workspace-specific post metadata. If a post payload is rejected by ClickUp, this plugin automatically retries it as a plain message so releases do not fail on chat formatting alone.

Lifecycle Hooks

| Hook | Description | |---|---| | verifyConditions | Validates token, workspace ID, and channel ID are set | | success | Sends release announcement to the configured channel | | fail | Sends failure notification (if notifyOnFail is enabled) |

Notes

• Messages are formatted as Markdown (text/md)
• ClickUp has a 980-character limit on message content; release notes are automatically truncated
• The fail hook swallows notification errors to avoid masking the original release failure
• The ClickUp Chat API is experimental and subject to change

Releases

This repo is configured to run semantic-release from GitHub Actions on pushes to master.

Required GitHub Actions secrets:

• NPM_TOKEN for publishing to npm

The release workflow:

• runs tests and a production build on Node 22
• creates a GitHub release and generates the npm tarball
• pushes that tarball to npm in a dedicated pnpm-based CI job only when semantic-release publishes a new release
• uploads the generated npm tarball as a GitHub release asset

License

MIT