TriPSs Conventional Changelog Action

The TriPSs Conventional Changelog Action serves as a critical automation bridge within the GitHub Actions ecosystem, specifically designed to bridge the gap between commit history and release documentation. By leveraging the Conventional Commits specification, this action automates the laborious process of determining the next semantic version, generating a human-readable changelog, and tagging the repository. In a modern CI/CD pipeline, the manual curation of release notes is a significant bottleneck and a source of human error; this tool mitigates those risks by transforming standardized commit messages—such as feat:, fix:, and chore:—into structured release data. It does not merely generate a text file; it integrates deeply with the Git lifecycle, managing version files, performing Git commits, and providing the necessary metadata to trigger subsequent deployment workflows or the creation of official GitHub Releases.

Architectural Overview and Core Functionality

The primary objective of the TriPSs Conventional Changelog Action is to automate the versioning process based on the nature of the changes committed to a branch. It parses the commit history since the last tagged version and determines whether a patch, minor, or major version bump is required. For instance, a commit starting with feat: triggers a minor version increase, while a commit containing BREAKING CHANGE: or a ! after the type (e.g., feat!:) necessitates a major version bump to 1.0.0 or higher.

The action operates by analyzing the commit log and then performing a series of operations: updating a version file (such as package.json or a custom YAML file), creating a CHANGELOG.md file, and pushing a new Git tag. This automation ensures that the software version always reflects the actual changes implemented, maintaining a strict adherence to Semantic Versioning (SemVer) principles.

Detailed Version History and Evolutionary Path

The development trajectory of the TriPSs Conventional Changelog Action reveals a consistent focus on expanding file support, improving Git integration, and updating the underlying runtime environments to maintain compatibility with GitHub's hosted runners.

Input Parameters and Configuration Deep Dive

To achieve maximum flexibility, the action provides a wide array of input parameters. These allow users to customize how the version is bumped, where the changelog is stored, and who is credited with the release commit.

The following parameters define the behavior of the action:

• github-token: The GitHub token required for API interactions. This can be the default GITHUB_TOKEN or a custom secret. For specific use cases, such as triggering other actions via a pushed tag, this may be set to an empty string when using a Deploy Key.
• git-message: A custom commit message for the version bump. It supports placeholders, such as chore(release): {version}.
• git-user-name: The name attributed to the commit performing the version bump (e.g., github-actions[bot]).
• git-user-email: The email associated with the release commit (e.g., github-actions[bot]@users.noreply.github.com).
• preset: The conventional commit preset to use, such as angular.
• tag-prefix: The prefix added to the version tag, commonly v.
• output-file: Specifies the path to the changelog file. If set to false, no physical changelog file is created in the repository, which is ideal for users who only want to use the output for a GitHub Release body.
• release-count: Controls the number of releases to include in the generated changelog.
• version-file: The file used to track the current version. Supported formats include .json, .yml, .yaml, .toml, and .properties.
• version-path: The specific path within the version file where the version string is located.
• skip-on-empty: A boolean specifying whether to skip the release process if no relevant commits are found.
• skip-version-file: If set to true, the action will not attempt to update or create a version file (e.g., package.json).
• skip-commit: If set to true, the action will generate the tag and changelog but will not perform a Git commit of the version bump.
• git-branch: The branch upon which the action operates.
• skip-git-pull: When set to true, the action avoids pulling the latest changes. This is critical when a long build process occurs before tagging to prevent the action from tagging a different commit than the one that was actually built.
• pre-commit: A path to a JavaScript file to be executed as a pre-commit hook.

Action Outputs and Pipeline Integration

The action provides several outputs that can be utilized by subsequent steps in a GitHub Workflow. This allows the pipeline to remain dynamic, such as only creating a GitHub Release if a version bump actually occurred.

The available outputs are:

• changelog: The full generated changelog for the new version.
• clean_changelog: The changelog without the version name. This is the preferred output for the body of a GitHub Release to avoid redundant version headers.
• version: The newly calculated version string.
• tag: The full name of the generated tag (e.g., v1.2.3).
• skipped: A boolean (true or false) indicating whether the action skipped the release process due to a lack of qualifying commits.

Implementation Strategies and Example Use-Cases

Depending on the desired outcome—whether it is a simple tag, a full repository update, or a GitHub Release—the configuration differs.

Standard Implementation with File Output

In a basic setup, the action updates the repository's CHANGELOG.md and package.json and pushes the changes back to the branch.

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

GitHub Release Integration

To create an official GitHub Release, the action should be configured to skip the physical output file, and its outputs should be passed to a release creation action.

```yaml
- 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:
  GITHUBTOKEN: ${{ secrets.githubtoken }}
  with:
  tagname: ${{ steps.changelog.outputs.tag }}
  releasename: ${{ steps.changelog.outputs.tag }}
  body: ${{ steps.changelog.outputs.clean_changelog }}
  ```

Advanced Workflow: PR-based Releases

In some enterprise environments, releases are not pushed directly to main but are instead proposed via a Pull Request. This involves creating a temporary release branch.

```yaml
- name: Create Branch
run: |
git checkout -b ${{ env.PR_BRANCH }}

• name: Create Changelog
  uses: TriPSs/conventional-changelog-action@v5
  id: changelog
  with:
  github-token: ${{ github.token }}
  git-user-name: "github-actions[bot]"
  git-user-email: "github-actions[bot]@users.noreply.github.com"
  git-branch: ${{ env.PR_BRANCH }}
  skip-git-pull: true
  output-file: false
  version-file: .github/package.yaml
  create-summary: true

• name: Create Changelog PR
  if: steps.changelog.outputs.skipped == 'false'
  run: |
  gh pr create --base main --head ${{ env.PR_BRANCH }} --title "Release ${{ steps.changelog.outputs.version }}"
  ```

Specialized Deployment and Security Configurations

Deploy Key Integration

For scenarios where a pushed tag must trigger another GitHub Action, using the default GITHUB_TOKEN may be insufficient due to security restrictions on triggering further workflows. In such cases, a Deploy Key is required. To implement this:

1. Use the actions/checkout action with an ssh-key provided by secrets.
2. Set the github-token input of the Conventional Changelog Action to an empty string ("").

```yaml
- name: Checkout GitHub Action
uses: actions/checkout@v4
with:
ssh-key: ${{ secrets.SSHDEPLOYKEY }}

• name: Conventional Changelog Action
  id: changelog
  uses: TriPSs/conventional-changelog-action@v5
  with:
  github-token: ""
  ```

Versioning File Formats and Paths

The action supports a diverse range of versioning files. If a relative path is provided for the version-file, it is resolved based on the GITHUB_WORKSPACE path. This allows for flexible project structures where the version might be stored in a subdirectory.

• JSON/YAML/TOML: Standard formats for web and cloud-native projects.
• Java Properties: Added in v6.1.0, enabling support for .properties files.
• Custom Paths: The version-path input allows the action to target a specific key within a nested file structure.

Development and Contribution Framework

For developers wishing to contribute to the project, the action provides a local testing environment using act, which allows GitHub Actions to be run locally.

The contribution process involves:

1. Cloning the repository and running npm install or yarn install.
2. Ensuring the action.yml file has the main entry point updated from src/index.js to ../src/index.js.
3. Running specific jobs using the following command:

bash act -j <workflow job name> -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --quiet

For full test suite execution, the command is:

bash act pull_request -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --quiet

It is noted that the Docker image used for these tests is substantial, approximately 18 GB in size. The project is distributed under the MIT license.

Conclusion: Analysis of Automation Impact

The TriPSs Conventional Changelog Action represents a significant shift from manual release management to a "Commit-Driven Release" philosophy. By enforcing the Conventional Commits standard, it removes the ambiguity of versioning. The impact on the development lifecycle is twofold: first, it creates a high-fidelity audit trail where the CHANGELOG.md is a direct reflection of the code changes, and second, it enables a seamless transition from a merge to a production release without manual intervention.

The evolution of the tool, particularly the addition of .properties support and the no-verify git option, indicates a move toward broader language ecosystem support beyond the Node.js community. Furthermore, the ability to integrate with Deploy Keys ensures that it can function within complex, multi-repo architectures where security and trigger-chains are paramount. The transition to Node 24 in recent versions ensures that the action remains performant and compatible with the latest GitHub runner environments. Ultimately, this action transforms the "release" from a discrete, manual event into a continuous, automated byproduct of the development process.

Sources

1. TriPSs/conventional-changelog-action Releases
2. Conventional Changelog Action Source/Commit
3. TriPSs/conventional-changelog-action GitHub
4. Automated GitHub Releases with GitHub Actions and Conventional Commits
5. Changelog Automation with GitHub Actions