Skip to content

Commit 24840e6

Browse files
bearomorphismbearomorphism
committed
docs(github_actions): improve github action tutorial page
1 parent b7cc220 commit 24840e6

File tree

1 file changed

+100
-72
lines changed

1 file changed

+100
-72
lines changed

‎docs/tutorials/github_actions.md‎

Lines changed: 100 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,49 @@
11
## Create a new release with GitHub Actions
22

3-
### Automatic bumping of version
3+
This guide shows you how to automatically bump versions, create changelogs, and publish releases using Commitizen in GitHub Actions.
44

5-
To execute `cz bump` in your CI, and push the new commit and
6-
the new tag, back to your master branch, we have to:
5+
### Prerequisites
76

8-
1. Create a personal access token. [Follow the instructions here](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token). And copy the generated key
9-
2. Create a secret called `PERSONAL_ACCESS_TOKEN`, with the copied key, by going to your
10-
project repository and then `Settings > Secrets > Add new secret`.
11-
3. In your repository create a new file `.github/workflows/bumpversion.yml`
12-
with the following content.
7+
Before setting up the workflow, you'll need:
138

14-
!!! warning
15-
If you use `GITHUB_TOKEN` instead of `PERSONAL_ACCESS_TOKEN`, the job won't trigger another workflow. It's like using `[skip ci]` in other CI's.
9+
1. A personal access token with repository write permissions
10+
2. Commitizen configured in your project (see [configuration documentation](../config/configuration_file.md))
1611

17-
```yaml
12+
### Automatic version bumping
13+
14+
To automatically execute `cz bump` in your CI and push the new commit and tag back to your repository, follow these steps:
15+
16+
#### Step 1: Create a personal access token
17+
18+
1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
19+
2. Click "Generate new token (classic)"
20+
3. Give it a descriptive name (e.g., "Commitizen CI")
21+
4. Select the `repo` scope to grant full repository access
22+
5. Click "Generate token" and **copy the token immediately** (you won't be able to see it again)
23+
24+
!!! warning "Important: Use Personal Access Token, not GITHUB_TOKEN"
25+
If you use `GITHUB_TOKEN` instead of `PERSONAL_ACCESS_TOKEN`, the workflow won't trigger another workflow run. This is a GitHub security feature to prevent infinite loops. The `GITHUB_TOKEN` is treated like using `[skip ci]` in other CI systems.
26+
27+
#### Step 2: Add the token as a repository secret
28+
29+
1. Go to your repository on GitHub
30+
2. Navigate to `Settings > Secrets and variables > Actions`
31+
3. Click "New repository secret"
32+
4. Name it `PERSONAL_ACCESS_TOKEN`
33+
5. Paste the token you copied in Step 1
34+
6. Click "Add secret"
35+
36+
#### Step 3: Create the workflow file
37+
38+
Create a new file `.github/workflows/bumpversion.yml` in your repository with the following content:
39+
40+
```yaml title=".github/workflows/bumpversion.yml"
1841
name: Bump version
1942

2043
on:
2144
push:
2245
branches:
23-
- master
46+
- master # or 'main' if that's your default branch
2447

2548
jobs:
2649
bump-version:
@@ -29,7 +52,7 @@ jobs:
2952
name: "Bump version and create changelog with commitizen"
3053
steps:
3154
- name: Check out
32-
uses: actions/checkout@v3
55+
uses: actions/checkout@v6
3356
with:
3457
token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
3558
fetch-depth: 0
@@ -39,88 +62,93 @@ jobs:
3962
github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
4063
```
4164
42-
Push to master and that's it.
65+
#### How it works
66+
67+
- **Trigger**: The workflow runs on every push to the `master` branch (or `main` if you change it)
68+
- **Conditional check**: The `if` condition prevents infinite loops by skipping the job if the commit message starts with `bump:`
69+
- **Checkout**: Uses your personal access token to check out the repository with full history (`fetch-depth: 0`)
70+
- **Bump**: The `commitizen-action` automatically:
71+
- Determines the version increment based on your commit messages
72+
- Updates version files (as configured in your `pyproject.toml` or other config)
73+
- Creates a new git tag
74+
- Generates/updates the changelog
75+
- Pushes the commit and tag back to the repository
76+
77+
Once you push this workflow file to your repository, it will automatically run on the next push to your default branch.
78+
79+
Check out [commitizen-action](https://github.com/commitizen-tools/commitizen-action) for more details.
4380

4481
### Creating a GitHub release
4582

46-
You can modify the previous action.
47-
48-
Add the variable `changelog_increment_filename` in the `commitizen-action`, specifying
49-
where to output the content of the changelog for the newly created version.
50-
51-
And then add a step using a GitHub action to create the release: `softprops/action-gh-release`
52-
53-
Commitizen action creates an env variable called `REVISION`, containing the
54-
newly created version.
55-
56-
```yaml
57-
- name: Create bump and changelog
58-
uses: commitizen-tools/commitizen-action@master
59-
with:
60-
github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
61-
changelog_increment_filename: body.md
62-
- name: Release
63-
uses: softprops/action-gh-release@v1
64-
with:
65-
body_path: "body.md"
66-
tag_name: ${{ env.REVISION }}
67-
env:
68-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69-
```
83+
To automatically create a GitHub release when a new version is bumped, you can extend the workflow above.
7084

71-
### Publishing a python package
85+
The `commitizen-action` creates an environment variable called `REVISION` containing the newly created version. You can use this to create a release with the changelog content.
7286

73-
Once the new tag is created, triggering an automatic publish command would be desired.
87+
```yaml title=".github/workflows/bumpversion.yml"
88+
name: Bump version
7489
75-
In order to do so, the credential needs to be added with the information of our PyPI account.
90+
on:
91+
push:
92+
branches:
93+
- master # or 'main' if that's your default branch
7694
77-
Instead of using username and password, we suggest using [api token](https://pypi.org/help/#apitoken) generated from PyPI.
95+
jobs:
96+
bump-version:
97+
if: "!startsWith(github.event.head_commit.message, 'bump:')"
98+
runs-on: ubuntu-latest
99+
name: "Bump version and create changelog with commitizen"
100+
steps:
101+
- name: Check out
102+
uses: actions/checkout@v6
103+
with:
104+
token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
105+
fetch-depth: 0
106+
- name: Create bump and changelog
107+
uses: commitizen-tools/commitizen-action@master
108+
with:
109+
github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
110+
changelog_increment_filename: body.md
111+
- name: Release
112+
uses: ncipollo/release-action@v1
113+
with:
114+
tag: v${{ env.REVISION }}
115+
bodyFile: "body.md"
116+
skipIfReleaseExists: true
117+
env:
118+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
119+
```
78120

79-
After generate api token, use the token as the PyPI password and `__token__` as the username.
121+
You can find the complete workflow in our repository at [bumpversion.yml](https://github.com/commitizen-tools/commitizen/blob/master/.github/workflows/bumpversion.yml).
80122

81-
Go to `Settings > Secrets > Add new secret` and add the secret: `PYPI_PASSWORD`.
123+
### Publishing a Python package
82124

83-
Create a file in `.github/workflows/pythonpublish.yaml` with the following content:
125+
After a new version tag is created, you can automatically publish your package to PyPI (or other package registries).
84126

85-
```yaml
127+
```yaml title=".github/workflows/pythonpublish.yml"
86128
name: Upload Python Package
87129
88130
on:
89131
push:
90132
tags:
91-
- "*" # Will trigger for every tag, alternative: 'v*'
133+
- "v*"
92134
93135
jobs:
94136
deploy:
95137
runs-on: ubuntu-latest
138+
permissions:
139+
id-token: write
140+
contents: read
96141
steps:
97-
- uses: actions/checkout@v3
142+
- uses: actions/checkout@v6
98143
with:
144+
token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
99145
fetch-depth: 0
100146
- name: Set up Python
101-
uses: actions/setup-python@v4
102-
with:
103-
python-version: "3.x"
104-
- name: Install Poetry
105-
uses: snok/install-poetry@v1
106-
with:
107-
version: latest
108-
virtualenvs-in-project: true
109-
virtualenvs-create: true
110-
- name: Install dependencies
111-
run: |
112-
poetry --version
113-
poetry install
114-
- name: Build and publish
115-
env:
116-
POETRY_HTTP_BASIC_PYPI_USERNAME: __token__
117-
POETRY_HTTP_BASIC_PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
118-
run: poetry publish --build
147+
uses: astral-sh/setup-uv@v7
148+
- name: Build
149+
run: uv build
150+
- name: Publish package to PyPI
151+
uses: pypa/gh-action-pypi-publish@release/v1
119152
```
120153

121-
Notice that we are using poetry to publish the package.
122-
123-
124-
You can also use [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) to publish your package.
125-
126-
Push the changes and that's it.
154+
You can find the complete workflow in our repository at [pythonpublish.yml](https://github.com/commitizen-tools/commitizen/blob/master/.github/workflows/pythonpublish.yml).

0 commit comments

Comments
 (0)