Advanced usage¶

Using Changelog Keeper in pre-commit hooks¶

Changelog Keeper integrates with pre-commit tool. Add taminomara/cl-keeper to your .pre-commit-config.yaml:

- repo: https://github.com/taminomara/cl-keeper
  rev: v1
  hooks:
    - id: clk
    - id: clk-tags

Then run pre-commit autoupdate to replace v1 with the exact latest version:

$ pre-commit autoupdate

There are two hooks available:

clk

runs clk fix on your repository.

clk-tags

runs clk check-tag before push to check whether pushed tags conform to the selected version_format.

Note that there is no guarantee that this hook will catch all push attempts; it’s best to run clk check-tag in CI as well.

Using Changelog Keeper in GitHub Actions¶

Changelog Keeper provides a GitHub action to extract release notes for the given tag.

Here’s an example of using taminomara/cl-keeper@v1 in combination with softprops/action-gh-release@v2 to create a GitHub release on tag push:

name: Create a release
  on:
    push:
      tags:
        - 'v*'
jobs:
  release:
    - name: Checkout source
      uses: actions/checkout@v4
    - id: changelog
      name: Parse Changelog
      uses: taminomara/cl-keeper@v1
      with:
        version: ${{ github.ref }}
    - name: Create GitHub release
      uses: softprops/action-gh-release@v2
      with:
        prerelease: ${{ fromJSON(steps.changelog.outputs.is-pre-release) }}
        draft: ${{ fromJSON(steps.changelog.outputs.is-unreleased) }}
        body: |
          ## Changelog

          ${{ steps.changelog.outputs.text }}

Note

If you’re running action in strict mode, you may need to enable full history fetch in order to validate git tags. Use fetch-depth for this:

- name: Checkout source
  uses: actions/checkout@v4
  with:
    fetch-depth: 0

Inputs¶
Parameter	Type	Default	Description
`config`	`string`	`""`	Path to the config file, relative to repository root.
`changelog`	`string`	`""`	Path to the changelog file, relative to repository root.
`version`	`string`	`"latest"`	Version to search for, default is “latest”.
`strict`	`boolean`	`false`	Run changelog keeper in strict mode.
`ignore-errors`	`boolean`	`false`	Ignore issues found in changelog.

Outputs¶
Output	Type	Description
`text`	`string`	Extracted markdown text.
`is-latest`	`boolean`[1]	Indicates that this is the latest release so far.
`is-pre-release`	`boolean`[1]	Indicates that this is a pre-release.
`is-post-release`	`boolean`[1]	Indicates that this is a post-release.
`is-unreleased`	`boolean`[1]	Indicates that action returned an unreleased section of changelog.
`data`	`object`[1]	Full JSON output of the “clk find” command.

Running Changelog Keeper from VSCode¶

You can configure VSCode to run clk fix on the current file:

Open Tasks: Open User Tasks.

Add the following task:

{
  "label": "clk",
  "type": "shell",
  "command": "clk fix -i '${file}' -m",
  "problemMatcher": {
    "fileLocation": "absolute",
    "source": "clk",
    "owner": "changelog-keeper",
    "applyTo": "allDocuments",
    "pattern": {
      "regexp": "^(.*):(\\d*):([a-zA-Z0-9 ]*):([a-zA-Z0-9 ]*):(.*)$",
      "file": 1,
      "line": 2,
      "severity": 3,
      "code": 4,
      "message": 5
    }
  },
  "presentation": {
    "echo": true,
    "reveal": "never",
    "focus": false,
    "panel": "shared",
    "showReuseMessage": true,
    "clear": false
  }
}

Now you can run clk fix using Tasks: Run Task command.