commitizen-action - GitLite

KO | EN

gitlite — search

#javascript #react #typescript #llm #android #machine-learning #nodejs #java #awesome #security #pytorch #mcp #openai #open-source

commitizen-action

(★ 103)

Commitizen github action to bump and create changelog

File Explorer

Download Latest Version (.zip)

- - bumpversion.yaml
  - test_action.yml
  - update_semver.yml
.cz.toml
.gitignore
action.yml
CHANGELOG.md
Dockerfile
entrypoint.sh
LICENSE
README.md

# Installation Guide

1. Get the code

git clone https://github.com/commitizen-tools/commitizen-action

Downloads the entire project code from GitHub to your computer.

cd commitizen-action

Moves into the project folder you just downloaded.

2. Docker

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

docker build -t commitizen-action .

Builds a runnable image based on the Dockerfile.

docker run -p 8080:80 commitizen-action

Runs the built image as an actual container.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# commitizen-action

Add [commitizen][cz] incredibly fast into your project!

## Features

- Allow prerelease
- Super easy to setup
- Automatically bump version
- Automatically create changelog
- Update any file in your repo with the new version

Are you using [conventional commits][cc] and [semver][semver]?

Then you are ready to use this github action! The only thing you'll need is the
`.cz.toml` file in your project.

## Usage

1. In your repository create a `.cz.toml` file (you can run `cz init` to create it)
2. Create a `.github/workflows/bumpversion.yaml` with the Sample Workflow

### Minimal configuration

Your `.cz.toml` (or `pyproject.toml` if you are using python) should look like
this.

```toml
[tool.commitizen]
version = "0.1.0"  # This should be your current semver version
```

For more information visit [commitizen's configuration page][cz-conf]

## Sample Workflow

```yaml
name: Bump version

on:
  push:
    branches:
      - master

jobs:
  bump_version:
    if: "!startsWith(github.event.head_commit.message, 'bump:')"
    runs-on: ubuntu-latest
    name: "Bump version and create changelog with commitizen"
    steps:
      - name: Check out
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          token: "${{ secrets.GITHUB_TOKEN }}"
      - id: cz
        name: Create bump and changelog
        uses: commitizen-tools/commitizen-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Print Version
        run: echo "Bumped to version ${{ steps.cz.outputs.version }}"
```

## Variables

| Name                           | Description                                                                                                                                                                                                                       | Default                                                         |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `github_token`                 | Token for the repo. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`. Required if `push: true`                                                                                                                                | -                                                               |
| `working_directory`            | Change to this directory before running                                                                                                                                                                                           | repo root directory                                             |
| `dry_run`                      | Run without creating commit, output to stdout                                                                                                                                                                                     | false                                                           |
| `repository`                   | Repository name to push. Default or empty value represents current github repository                                                                                                                                              | current one                                                     |
| `branch`                       | Destination branch to push changes                                                                                                                                                                                                | Same as the one executing the action by default                 |
| `prerelease`                   | Set as prerelease {alpha,beta,rc} choose type of prerelease                                                                                                                                                                       | -                                                               |
| `devrelease`                   | Non-negative integer for dev. release                                                                                                                                                                          | -                                                               |
| `local_version`                | Bump only the local version portion                                                                                                                                                                          | -                                                               |
| `build_metadata`               | Specifies additional metadata in the version string, creates a version like `1.1.2+yourmetadata`                                                                                                                                                                   | -                                                               |
| `extra_requirements`           | Custom requirements, if your project uses a custom rule or plugins, you can specify them separated by a space. E.g: `'commitizen-emoji conventional-JIRA'`                                                                        | -                                                               |
| `changelog_increment_filename` | Filename to store the incremented generated changelog. This is different to changelog as it only contains the changes for the just generated version. Example: `body.md`                                                          | -                                                               |
| `git_redirect_stderr`          | Redirect git output to stderr. Useful if you do not want git output in your changelog                                                                                                                                             | `false`                                                         |
| `git_name`                     | Name used to configure git (for git operations)                                                                                                                                                                                   | `github-actions[bot]`                                           |
| `git_email`                    | Email address used to configure git (for git operations)                                                                                                                                                                          | `github-actions[bot]@users.noreply.github.com`                  |
| `push`                         | Define if the changes should be pushed to the branch.                                                                                                                                                                             | true                                                            |
| `merge`                        | Define if the changes should be pushed even on the pull_request event, immediately merging the pull request.                                                                                                                      | false                                                           |
| `commit`                       | Define if the changes should be committed to the branch.                                                                                                                                                                          | true                                                            |
| `commitizen_version`           | Specify the version to be used by commitizen. Eg: `4.10.0`                                                                                                                                                                        | latest                                                          |
| `changelog`                    | Create changelog when bumping the version                                                                                                                                                                                         | true                                                            |
| `no_raise`                     | Don't raise the given comma-delimited exit codes (e.g., no_raise: '20,21'). Use with caution! Open an issue in [commitizen](https://github.com/commitizen-tools/commitizen/issues) if you need help thinking about your workflow. | [21](https://commitizen-tools.github.io/commitizen/exit_codes/) |
| `increment`                    | Manually specify the desired increment {MAJOR,MINOR, PATCH}                                                                                                                                                                       | -                                                               |
| `check_consistency`            | Check consistency among versions defined in commitizen configuration and version_files                                                                                                                                            | `false`                                                         |
| `gpg_sign`                     | If true, use GPG to sign commits and tags (for git operations). Requires separate setup of GPG key and passphrase in GitHub Actions (e.g. with the action `crazy-max/ghaction-import-gpg`)                                        | `false`                                                         |
| `debug`                        | Prints debug output to GitHub Actions stdout                                                                                                                                                                                      | `false`                                                         |

## Outputs

| Name                     | Description                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| `version`                | The next version (same as `next_version`, kept for historical purposes) |
| `next_version`           | Next version                                                            |
| `next_version_major`     | Only the major version of the next version                              |
| `next_version_minor`     | Only the minor version of the next version                              |
| `previous_version`       | Version before the bump                                                 |
| `previous_version_major` | Only the major version of the previous version                          |
| `previous_version_minor` | Only the minor version of the previous version                          |

The new version is also available as an environment variable under `REVISION` or you can access using `${{ steps.cz.outputs.version }}`

## Using SSH with deploy keys

1. Create a [deploy key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys) (which is the SSH **public key**)
2. Add the **private key** as a [Secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) in your repository, e.g: `COMMIT_KEY`
3. Set up your action

```yaml
name: Bump version

on:
  push:
    branches:
      - main

jobs:
  bump-version:
    if: "!startsWith(github.event.head_commit.message, 'bump:')"
    runs-on: ubuntu-latest
    name: "Bump version and create changelog with commitizen"
    steps:
      - name: Check out
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          ssh-key: "${{ secrets.COMMIT_KEY }}"
      - name: Create bump and changelog
        uses: commitizen-tools/commitizen-action@master
        with:
          push: false
      - name: Push using ssh
        run: |
          git push origin main --tags
```

## Creating a Github release

```yaml
name: Bump version

on:
  push:
    branches:
      - main

jobs:
  bump-version:
    if: "!startsWith(github.event.head_commit.message, 'bump:')"
    runs-on: ubuntu-latest
    name: "Bump version and create changelog with commitizen"
    steps:
      - name: Check out
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
      - name: Create bump and changelog
        uses: commitizen-tools/commitizen-action@master
        with:
          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          changelog_increment_filename: body.md
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: "body.md"
          tag_name: ${{ env.REVISION }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Troubleshooting

### Other actions are not triggered when the tag is pushed

This problem occurs because `secrets.GITHUB_TOKEN` do not trigger other
actions [by design][by_design].

To solve it, you must use a personal access token in the checkout and the commitizen steps.

Follow the instructions in [commitizen's documentation][cz-docs-ga].

Alternatively, you can try using the `gh` cli in your github action:

```sh
gh workflow run <workflow.yaml> ...
```

## I'm not using conventional commits, I'm using my own set of rules on commits

If your rules can be parsed, then you can build your own commitizen rules,
create a new commitizen python package, or you can describe it on the `toml` config itself.

[Read more about customization][cz-custom]

[by_design]: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#example-using-multiple-events-with-activity-types-or-configuration
[cz-docs-ga]: https://commitizen-tools.github.io/commitizen/tutorials/github_actions/
[cz]: https://commitizen-tools.github.io/commitizen/
[cc]: https://www.conventionalcommits.org/
[semver]: https://semver.org/
[cz-conf]: https://commitizen-tools.github.io/commitizen/config/
[cz-custom]: https://commitizen-tools.github.io/commitizen/customization/