Flow documentation

[EvanCarroll]

It's not clear how git cliff flows. For example, the way the git-cliff GitHub action flows.

• User creates tag
• User pushes tag
• git cliff generates change log.

But it's not clear that's what someone wants. What I want is users pushes to branch, changelog and version are generated and updated in a chore commit. It would be good to put a high level overview of how git cliff is supposed to work in CI.

[orhun]

Hello! 👋🏼

Good question! There isn't much documentation surrounding the integration of git-cliff in the CI, and it's mostly up to the user to configure it based on their use case.

For your mentioned use case, you can do this in (e.g. GitHub Actions):

name: Generate Changelog and Version on Push

on:
  push:
    branches:
      - '**'  # Triggers for push to any branch

jobs:
  generate-changelog:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Set up Git for committing
        run: |
          git config user.name "github-actions"
          git config user.email "[email protected]"

      - name: Generate changelog and version
        uses: orhun/git-cliff-action@v3
        with:
          config: cliff.toml
          args: --verbose
        env:
          OUTPUT: CHANGELOG.md
          GITHUB_REPO: ${{ github.repository }}

      - name: Commit and push changelog and version changes
        run: |
          git add CHANGELOG.md
          git commit -m "chore: update changelog and version"
          git push origin ${{ github.ref }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Also, if your project is in Rust, I highly recommend release-plz which does something similar to what you have described.

Additionally, I think adding moving the github-actions and gitlab pages under a more general section where we describe the possible use cases would be a good addition. What do you think?

P.S. Transferring this to git-cliff-action since it's more related.