Gitea Integration 🍵
This is still an experimental feature, please report bugs.
If you have built from source, enable the gitea
feature flag for the integration to work.
For projects hosted on Gitea/Forgejo, you can use git-cliff to add the following to your changelog:
- Gitea usernames
- Contributors list (all contributors / first time)
- Pull request links (associated with the commits)
Setting up the remote
As default, remote upstream URL is automatically retrieved from the Git repository.
If that doesn't work or if you want to set a custom remote, there are a couple of ways of doing it:
- Use the remote option in the configuration file:
[remote.gitea]
owner = "orhun"
repo = "git-cliff"
token = "***"
-
Use the
--gitea-repo
argument (takes values inOWNER/REPO
format, e.g. "orhun/git-cliff") -
Use the
GITEA_REPO
environment variable (same format as--gitea-repo
)
Authentication
Gitea REST API is being used to retrieve data from Gitea. It does not require authentication for public repositories. If your project uses a private repository, you need to create an access token under Settings > Applications > Access tokens.
To set an access token, you can use the configuration file (not recommended), --gitea-token
argument or GITEA_TOKEN
environment variable.
For example:
GITEA_TOKEN="***" git cliff --gitea-repo "orhun/git-cliff"
You can use the GITEA_API_URL
environment variable want to override the API URL. This is useful if you are using your own Gitea instance.
Templating
See the templating documentation for general information about how the template engine works.
Remote
You can use the following context for adding the remote to the changelog:
{
"gitea": {
"owner": "orhun",
"repo": "git-cliff"
}
}
For example:
https://codeberg.org/{{ remote.gitea.owner }}/{{ remote.gitea.repo }}/commits/tag/{{ version }}
Commit authors
For each commit, Gitea related values are added as a nested object (named gitea
) to the template context:
{
"id": "8edec7fd50f703811d55f14a3c5f0fd02b43d9e7",
"message": "refactor(config): remove unnecessary newline from configs\n",
"group": "🚜 Refactor",
"...": "<strip>",
"gitea": {
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["rust"],
"is_first_time": false
}
}
This can be used in the template as follows:
{% for commit in commits %}
* {{ commit.message | split(pat="\n") | first | trim }}\
{% if commit.gitea.username %} by @{{ commit.gitea.username }}{%- endif %}\
{% if commit.gitea.pr_number %} in #{{ commit.gitea.pr_number }}{%- endif %}
{%- endfor -%}
The will result in:
- feat(commit): add merge_commit flag to the context by @orhun in #389
- feat(args): set `CHANGELOG.md` as default missing value for output option by @sh-cho in #354
Contributors
For each release, following contributors data is added to the template context as a nested object:
{
"version": "v1.4.0",
"commits": [],
"commit_id": "0af9eb24888d1a8c9b2887fbe5427985582a0f26",
"timestamp": 0,
"previous": null,
"gitea": {
"contributors": [
{
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["rust"],
"is_first_time": true
},
{
"username": "cliffjumper",
"pr_title": "I love jumping",
"pr_number": 999,
"pr_labels": ["rust"],
"is_first_time": true
}
]
}
}
This can be used in the template as follows:
{% for contributor in gitea.contributors | filter(attribute="is_first_time", value=true) %}
* @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}
The will result in:
- @orhun made their first contribution in #420
- @cliffjumper made their first contribution in #999