You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



A changelog formatter for Changesets that adds commit, PR, and issue links

Version published




Breaking Changes

  • Rename package to changesets-format-with-issue-links for accuracy (#8) (7f068e3)

Patch Changes

  • Associate each changeset with the commit when it was added, even if it was reformatted later (#9) (46a5734)
  • Update dev environment and code coverage (#7) (b78aedb)



npm version build status test coverage dependencies status

What is this?

Atlassian Changesets is a changelog management tool. Its default formatter generates a plain list of changes, without issue links.

This package adds links to the git commits, issues, and pull requests where your changesets were added.

The result is similar to the output of other common changelog standards, such as standard-version and Release Please.


If you have already set up Changesets, you only need to install the package and add it to your .changeset/config.json.

You do not need to enable the commit option in your config.

npm install --D changesets-format-with-issue-links
// .changeset/config.json
  "changelog": [
      "repoBaseUrl": "",
      // additional options here

Bitbucket setup

You can change the commit and issue link templates for Bitbucket or any other service:

// .changeset/config.json
  "changelog": [
      "repoBaseUrl": "",
      // This will generate a Markdown link like `[#123](`,
      // wrapped in parentheses.
      "issueTemplate": " ([#$issue]($repoBaseUrl/pull-requests/$issue))"
      "commitTemplate": " [$abbrevHash]($repoBaseUrl/commits/$hash)"


repoBaseUrl (required)

A base url -- including https -- which can be used to build links in commitTemplate and issueTemplate. Example: ""

changesetTemplate (default: "- ${changesetTitle}${issue}${commit}${changesetBody}")

Content that will be added to your changelog.

With the default value, issue and commit links will be inserted at the end of the first line of your changeset message.

See commitTemplate for the $commit variable, issueTemplate for the $issue variable, and Template Variables for other available values.

commitTemplate (default: " ([$abbrevHash]($repoBaseUrl/commit/$hash))")

Content for the $commit variable, based on the commit when the changeset was created. See gitlogOptions below for information on the available fields from the commit.

commitMissingTemplate (default: "")

Content for the $commit variable when no commit could be found. This should generally be left blank.

issuePattern (default: "#(\\d+)\\)")

Regular expression (without the leading and trailing /) used to identify issues and pull requests in the subject line of a commit message. The default will match a number immediately followed by a closing parentheses, like #4).

If the commit message matches this pattern, the Regex result will be available as $issueMatch and the text inside the capturing group ((\d+) in the default) will be available as $issue in the issueTemplate, below.

issueTemplate (default: " ([#$issue]($repoBaseUrl/issues/$issue))")

Content for the $issue variable, based on the value matched by issuePattern.

issueMissingTemplate (default: "")

Content for the $issue variable when no issue or pull request could be found. This should generally be left blank.



  "repo": ".",
  "fields": ["hash", "abbrevHash", "authorName", "authorEmail", "authorDate", "subject"],
  "includeMergeCommitFiles": true

Options passed to gitlog (see docs here).

This can be used to add additional fields to the template, or to change the behavior of the git log search.

How it works

This works by identifying the git commit when a changeset entry was added, looking for an issue number in its commit message, and then using templates to append any relevant links or info to the changelog entry.

Template variables

Inside any of the templates (changesetTemplate, commitTemplate, commitMissingTemplate, issueTemplate, or issueMissingTemplate), any token that starts with $ or which is wrapped within ${...} will be treated as a variable.

Use \\$ to escape the dollar sign character if you do not want it to be treated as a variable.

Available variables

Information from the changeset entry:

Variable nameNotes
$changesetTitleThe summary (first line) of your Changesets entry
$changesetBodyAll text after the first line of your Changesets entry, trimmed
$changesetRawBodyThe entire text of your Changesets entry
$versionTypeThe semver bump type: "major", "minor", "patch", or "none"
$changesetInfoObject containing all of the above, plus any other information from Changesets (e.g.,${changesetInfo.changesetTitle}, ${changesetInfo.versionType})

Information from the git commit when the changeset was added:

Variable nameNotes
$commitText generated from commitTemplate (or commitMissingTemplate if the commit was not found)
$hashThe full 40-character git hash
$abbrevHashThe short git hash
$subjectFirst line of the commit message
...Anything you requested via gitlogOptions.fields
$commitInfoObject containing all of the above (e.g., ${commitInfo.abbrevHash}, ${commitInfo.hash})

Information from the matched issue pattern, if any:

Variable nameNotes
$issueText generated from issueTemplate (or issueMissingTemplate if no issue was found)
$issueMatchObject containing all of the results from the match against issuePattern (e.g., ${issueMatch[1]})

And also any additional values you included in the config options:

Variable nameNotes
$repoBaseUrlGenerally used by commitTemplate and issueTemplate
...Anything that wasn't recognized
$optionsObject containing all of the options from .changeset/config.json, merged with the defaults



Package last updated on 27 Aug 2022

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc