search

TriPSs / conventional-changelog-action

Github Action that generates a changelog with the Conventional Changelog CLI
MIT License
285 stars 102 forks source link
conventional-changelog conventional-commits git github-actions

readme

Conventional Changelog action

This action will bump version, tag commit and generate a changelog with conventional commits.

Inputs

Presets

This action comes pre-compiled with the angular (default) and conventionalcommits, if you wish to use an other preset you need to make sure it's installed with npm install conventional-changelog-<preset name>

Pre-Commit hook

Function in a specified file will be run right before the git-add-git-commit phase, when the next version is already known and a new changelog has been generated. You can run any chores across your repository that should be added and committed with the release commit.

Specified path could be relative or absolute. If it is relative, then it will be based on the GITHUB_WORKSPACE path.

Script should:

preCommit function can be async.

Following props will be passed to the function as a single parameter:

interface Props {
  tag: string; // Next tag e.g. v1.12.3
  version: string; // Next version e.g. 1.12.3
}

export function preCommit(props: Props): void {}

A bunch of useful environment variables are available to the script with process.env. See docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables to learn more.

Pre-Changelog-Generation hook

Function in a specified file will be run right before the changelog generation phase, when the next version is already known, but it was not used anywhere yet. It can be useful if you want to manually update version or tag.

Same restrictions as for the pre-commit hook, but exported functions names should be preVersionGeneration for modifications to the version and preTagGeneration for modifications to the git tag.

Following props will be passed to the function as a single parameter and same output is expected:

// Next version e.g. 1.12.3
export function preVersionGeneration(version: string): string {}

// Next tag e.g. v1.12.3
export function preTagGeneration(tag: string): string {}

Config-File-Path

A config file to define the conventional commit settings. Use it if you need to override values like issuePrefix or issueUrlFormat. If you set a config-file-path, the preset setting will be ignored. Therefore use an existing config and override the values you want to adjust.

example:

'use strict'
const config = require('conventional-changelog-conventionalcommits');

module.exports = config({
    "issuePrefixes": ["TN-"],
    "issueUrlFormat": "https://jira.example.com/browse/{{prefix}}{{id}}"
})

The specified path can be relative or absolute. If it is relative, then it will be based on the GITHUB_WORKSPACE path.

Make sure to install all required packages in the workflow before executing this action.

Outputs

Example usages

Uses all the defaults

permissions:
  contents: write

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}

Write permissions are required in order to enable git push when a new version is generated. In some configurations, the default secrets.github_token may not have the correct permissions. You can check your default permissions by looking at "Set up job" section of your GitHub action run log.

Overwrite everything

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    git-message: 'chore(release): {version}'
    git-user-name: 'Awesome Changelog Action'
    git-user-email: 'awesome_changelog@github.actions.com'
    preset: 'angular'
    tag-prefix: 'v'
    output-file: 'MY_CUSTOM_CHANGELOG.md'
    release-count: '10'
    version-file: './my_custom_version_file.json' // or .yml, .yaml, .toml, mix.exs
    version-path: 'path.to.version'
    skip-on-empty: 'false'
    skip-version-file: 'false'
    skip-commit: 'false'
    git-branch: 'my-maintenance-branch'

No file changelog

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    output-file: "false"

Tag only

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    skip-commit: "true"

Skip Git Pull In CI you might not want to pull extra changes before tagging e.g. if running a long build before tagging, another commit may have come into the branch which would get pulled leading to tagging a different commit to the one which was built.

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

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    skip-git-pull: "true"

Use a custom file for versioning

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    version-file: "my-custom-file.yaml"

Use a pre-commit hook

- name: Conventional Changelog Action
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    pre-commit: some/path/pre-commit.js

Github releases

- name: Conventional Changelog Action
  id: changelog
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ${{ secrets.github_token }}
    output-file: "false"

- name: Create Release
  uses: actions/create-release@v1
  if: ${{ steps.changelog.outputs.skipped == 'false' }}
  env:
    GITHUB_TOKEN: ${{ secrets.github_token }}
  with:
    tag_name: ${{ steps.changelog.outputs.tag }}
    release_name: ${{ steps.changelog.outputs.tag }}
    body: ${{ steps.changelog.outputs.clean_changelog }}

Use a deploy key

If you want to trigger another GitHub action based on pushed tag, you can use Deploy Key, To make full use of the Deploy Key, you must set the value of github-token input to empty string.

- name: Checkout GitHub Action
  uses: actions/checkout@v4
  with:
    ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
- name: Conventional Changelog Action
  id: changelog
  uses: TriPSs/conventional-changelog-action@v5
  with:
    github-token: ""

Development

If you'd like to contribute to this project, all you need to do is clone and install act this project and run:

Note: The image used is 18 gb!

$ npm install

# To run / test one specific job
$ act -j <workflow job name> -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --quiet
# Example
$ act -j test-json -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --quiet

# To run all tests
$ act pull_request -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --quiet

License

Conventional Changelog Action is MIT licensed.

Collaboration

If you have questions or issues, please open an issue!