Skip to content

Commit bc30e65

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

File tree

1 file changed

+117
-52
lines changed

1 file changed

+117
-52
lines changed

‎docs/tutorials/github_actions.md‎

Lines changed: 117 additions & 52 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,62 +62,106 @@ 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 }}
83+
To automatically create a GitHub release when a new version is bumped, you can extend the workflow above.
84+
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.
86+
87+
```yaml title=".github/workflows/bumpversion.yml"
88+
name: Bump version
89+
90+
on:
91+
push:
92+
branches:
93+
- master # or 'main' if that's your default branch
94+
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 }}
69119
```
70120

71-
### Publishing a python package
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).
72122

73-
Once the new tag is created, triggering an automatic publish command would be desired.
123+
### Publishing a Python package
74124

75-
In order to do so, the credential needs to be added with the information of our PyPI account.
125+
After a new version tag is created by the bump workflow, you can automatically publish your package to PyPI.
76126

77-
Instead of using username and password, we suggest using [api token](https://pypi.org/help/#apitoken) generated from PyPI.
127+
#### Step 1: Create a PyPI API token
78128

79-
After generate api token, use the token as the PyPI password and `__token__` as the username.
129+
1. Go to [PyPI Account Settings](https://pypi.org/manage/account/)
130+
2. Scroll to the "API tokens" section
131+
3. Click "Add API token"
132+
4. Give it a name (e.g., "GitHub Actions")
133+
5. Set the scope (project-specific or account-wide)
134+
6. Click "Add token" and **copy the token immediately**
80135

81-
Go to `Settings > Secrets > Add new secret` and add the secret: `PYPI_PASSWORD`.
136+
!!! tip "Using API tokens"
137+
PyPI API tokens are more secure than passwords. Use `__token__` as the username and the token as the password.
82138

83-
Create a file in `.github/workflows/pythonpublish.yaml` with the following content:
139+
#### Step 2: Add the token as a repository secret
84140

85-
```yaml
141+
1. Go to your repository on GitHub
142+
2. Navigate to `Settings > Secrets and variables > Actions`
143+
3. Click "New repository secret"
144+
4. Name it `PYPI_PASSWORD`
145+
5. Paste the PyPI token
146+
6. Click "Add secret"
147+
148+
#### Step 3: Create the publish workflow
149+
150+
Create a new file `.github/workflows/pythonpublish.yml` that triggers on tag pushes:
151+
152+
```yaml title=".github/workflows/pythonpublish.yml"
86153
name: Upload Python Package
87154
88155
on:
89156
push:
90157
tags:
91-
- "*" # Will trigger for every tag, alternative: 'v*'
158+
- "*" # Will trigger for every tag, alternative: 'v*'
92159
93160
jobs:
94161
deploy:
95162
runs-on: ubuntu-latest
96163
steps:
97-
- uses: actions/checkout@v3
164+
- uses: actions/checkout@v6
98165
with:
99166
fetch-depth: 0
100167
- name: Set up Python
@@ -118,9 +185,7 @@ jobs:
118185
run: poetry publish --build
119186
```
120187

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.
188+
This workflow uses Poetry to build and publish the package. You can find the complete workflow in our repository at [pythonpublish.yml](https://github.com/commitizen-tools/commitizen/blob/master/.github/workflows/pythonpublish.yml).
125189

126-
Push the changes and that's it.
190+
!!! note "Alternative publishing methods"
191+
You can also use [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) or other build tools like `setuptools`, `flit`, or `hatchling` to publish your package.

0 commit comments

Comments
 (0)