Skip to main content
The [remote] section configures integration with Git hosting platforms to enhance changelogs with pull request data, contributor information, and more.

​
Supported Platforms

git-cliff supports integration with:
  • GitHub
  • GitLab
  • Gitea / Forgejo
  • Bitbucket
  • Azure DevOps

​
GitHub Configuration

​
remote.github.owner
string
required
Owner (username or organization) of the GitHub repository.Example:
[remote.github]
owner = "orhun"
​
remote.github.repo
string
required
Name of the GitHub repository.Can be overridden with --github-repo argument or GITHUB_REPO environment variable.Example:
[remote.github]
owner = "orhun"
repo = "git-cliff"
Or via command line:
git cliff --github-repo orhun/git-cliff
​
remote.github.token
string
GitHub personal access token for authentication.Can be overridden with --github-token argument or GITHUB_TOKEN environment variable.Example:
[remote.github]
owner = "orhun"
repo = "git-cliff"
token = "ghp_your_token_here"
Or via environment variable:
export GITHUB_TOKEN="ghp_your_token_here"
git cliff
​
remote.github.api_url
string
Custom GitHub API URL for GitHub Enterprise instances.Example:
[remote.github]
owner = "myorg"
repo = "myrepo"
api_url = "https://github.company.com/api/v3"
token = "ghp_token"
​
remote.github.native_tls
boolean
Use platform’s native certificate store instead of bundled certificates.Useful for corporate environments with custom CA certificates.Example:
[remote.github]
owner = "orhun"
repo = "git-cliff"
native_tls = true

​
GitHub Example

[remote.github]
owner = "orhun"
repo = "git-cliff"
token = "ghp_your_personal_access_token"
See GitHub integration documentation for more details.

​
GitLab Configuration

​
remote.gitlab.owner
string
required
Owner (username or group) of the GitLab repository.
​
remote.gitlab.repo
string
required
Name of the GitLab repository.Can be overridden with --gitlab-repo argument or GITLAB_REPO environment variable.
​
remote.gitlab.token
string
GitLab personal access token.Can be overridden with --gitlab-token argument or GITLAB_TOKEN environment variable.
​
remote.gitlab.api_url
string
Custom GitLab API URL for self-hosted instances.Example:
[remote.gitlab]
owner = "archlinux"
repo = "arch-repro-status"
api_url = "https://gitlab.archlinux.org/api/v4"
token = "glpat-your_token"
​
remote.gitlab.native_tls
boolean
Use platform’s native certificate store.

​
GitLab Example

[remote.gitlab]
owner = "archlinux"
repo = "arch-repro-status"
api_url = "https://gitlab.archlinux.org/api/v4"
token = "glpat_your_personal_access_token"
native_tls = false
See GitLab integration documentation for more details.

​
Gitea / Forgejo Configuration

​
remote.gitea.owner
string
required
Owner of the Gitea/Forgejo repository.
​
remote.gitea.repo
string
required
Name of the Gitea/Forgejo repository.Can be overridden with --gitea-repo argument or GITEA_REPO environment variable.
​
remote.gitea.token
string
Gitea/Forgejo access token.Can be overridden with --gitea-token argument or GITEA_TOKEN environment variable.
​
remote.gitea.api_url
string
Gitea/Forgejo API URL (required for self-hosted instances).Example:
[remote.gitea]
owner = "myorg"
repo = "myproject"
api_url = "https://gitea.company.com/api/v1"
token = "your_gitea_token"
​
remote.gitea.native_tls
boolean
Use platform’s native certificate store.

​
Gitea Example

[remote.gitea]
owner = "gitea"
repo = "tea"
api_url = "https://gitea.com/api/v1"
token = "your_gitea_access_token"
See Gitea integration documentation for more details.

​
Bitbucket Configuration

​
remote.bitbucket.owner
string
required
Owner (username or workspace) of the Bitbucket repository.
​
remote.bitbucket.repo
string
required
Name of the Bitbucket repository.Can be overridden with --bitbucket-repo argument or BITBUCKET_REPO environment variable.
​
remote.bitbucket.token
string
Bitbucket app password or access token.Can be overridden with --bitbucket-token argument or BITBUCKET_TOKEN environment variable.
​
remote.bitbucket.api_url
string
Custom Bitbucket API URL for Bitbucket Server instances.
​
remote.bitbucket.native_tls
boolean
Use platform’s native certificate store.

​
Bitbucket Example

[remote.bitbucket]
owner = "myworkspace"
repo = "myrepo"
token = "your_app_password"
See Bitbucket integration documentation for more details.

​
Azure DevOps Configuration

​
remote.azure_devops.owner
string
required
Organization name in Azure DevOps.
​
remote.azure_devops.repo
string
required
Name of the Azure DevOps repository.Can be overridden with --azure-devops-repo argument or AZURE_DEVOPS_REPO environment variable.
​
remote.azure_devops.token
string
Azure DevOps personal access token.Can be overridden with --azure-devops-token argument or AZURE_DEVOPS_TOKEN environment variable.
​
remote.azure_devops.api_url
string
Custom Azure DevOps API URL.
​
remote.azure_devops.native_tls
boolean
Use platform’s native certificate store.

​
Azure DevOps Example

[remote.azure_devops]
owner = "myorganization"
repo = "myproject"
token = "your_personal_access_token"

​
Offline Mode

​
offline
boolean
default:"false"
Disable all external API calls even when a remote is configured.Useful when running --bumped-version or in restricted network environments.Example:
[remote]
offline = true

[remote.github]
owner = "orhun"
repo = "git-cliff"
Or via command line:
git cliff --offline

​
Authentication

​
Creating Access Tokens

GitHub:
  1. Go to Settings → Developer settings → Personal access tokens
  2. Generate new token with repo scope
  3. Use the token in your configuration or as GITHUB_TOKEN
GitLab:
  1. Go to User Settings → Access Tokens
  2. Create token with api scope
  3. Use the token in your configuration or as GITLAB_TOKEN
Gitea:
  1. Go to Settings → Applications → Generate New Token
  2. Create token with appropriate permissions
  3. Use the token in your configuration or as GITEA_TOKEN
Bitbucket:
  1. Go to Personal settings → App passwords
  2. Create app password with repository permissions
  3. Use the password in your configuration or as BITBUCKET_TOKEN
Azure DevOps:
  1. Go to User settings → Personal access tokens
  2. Create new token with Code (Read) permission
  3. Use the token in your configuration or as AZURE_DEVOPS_TOKEN

​
Security Best Practices

Never commit tokens to version control. Use environment variables or secure secret management.
Recommended approach: 
# cliff.toml
[remote.github]
owner = "orhun"
repo = "git-cliff"
# token is read from GITHUB_TOKEN environment variable

# Set environment variable
export GITHUB_TOKEN="ghp_your_token"
git cliff

​
Template Integration

When remote integration is enabled, additional data is available in changelog templates: 
[remote.github]
owner = "orhun"
repo = "git-cliff"

[changelog]
body = """
{% for commit in commits %}
  * {{ commit.message }}
    {%- if commit.remote.pr_number %} ([#{{ commit.remote.pr_number }}](https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}/pull/{{ commit.remote.pr_number }})){%- endif %}
    {%- if commit.remote.username %} by @{{ commit.remote.username }}{%- endif %}
{% endfor %}

{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
  ## New Contributors
  {% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
    * @{{ contributor.username }} made their first contribution
  {% endfor %}
{% endif %}
"""
Available remote data:
  • commit.remote.pr_number - Pull request number
  • commit.remote.pr_title - Pull request title
  • commit.remote.username - Commit author username
  • github.contributors - List of contributors with metadata

​
Complete Example

[remote]
offline = false

[remote.github]
owner = "orhun"
repo = "git-cliff"
# Token read from GITHUB_TOKEN environment variable
api_url = "https://api.github.com"  # optional
native_tls = false  # optional

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us