Skip to main content

​
Template Context

The template context contains all the data available to your templates. This page documents the structure of the context and all available variables.

​
Release Context

Each time the body template is rendered, it receives a release context:
​
version
string
The release version (e.g., v1.0.0). null for unreleased changes.
​
message
string
The annotated tag message for the release.
​
commit_id
string
The commit ID of the release commit (e.g., a440c6eb26404be4877b7e3ad592bfaa5d4eb210).
​
timestamp
integer
Unix timestamp of the release (e.g., 1625169301).Usage:
{{ timestamp | date(format="%Y-%m-%d") }}
​
repository
string
Path to the Git repository (e.g., /path/to/repository).
​
commits
array
Array of commit objects in this release. See Commit Object below.
​
commit_range
object
Range of commits in this release.
{
  "from": "(id of the first commit)",
  "to": "(id of the last commit)"
}
​
previous
object
Information about the previous release.
{
  "version": "v0.9.0"
}
​
statistics
object
Release statistics. See Statistics Object below.

​
Commit Object

The structure of a commit depends on whether conventional_commits is enabled.

​
With Conventional Commits

When conventional_commits = true:
​
id
string
Full commit SHA (e.g., e795460c9bb7275294d1fa53a9d73258fb51eb10).
​
group
string
Commit group assigned by commit_parsers (e.g., Features, Bug Fixes).
​
scope
string
Commit scope from conventional commit format (e.g., api, auth).Example: For feat(api): add endpoint, scope is api.
​
message
string
Commit description (the text after the type and scope).Example: For feat(api): add endpoint, message is add endpoint.
​
body
string
Commit body (text between description and footers).
​
footers
array
Array of footer objects. See Footers below.
​
breaking
boolean
true if commit is a breaking change.Set by:
  • Exclamation mark: feat!: breaking change
  • Footer: BREAKING CHANGE: description
​
breaking_description
string
Description of the breaking change from BREAKING CHANGE footer or commit message.
​
conventional
boolean
true if commit follows conventional commits format.
​
merge_commit
boolean
true if commit is a merge commit.
​
links
array
Array of link objects extracted by link_parsers.
[
  {
    "text": "#123",
    "href": "https://github.com/owner/repo/issues/123"
  }
]
​
author
object
Commit author information.
{
  "name": "User Name",
  "email": "[email protected]",
  "timestamp": 1660330071
}
​
committer
object
Commit committer information (same structure as author).
The author is who originally wrote the code. The committer is who applied the commit. These differ when applying patches or merging pull requests.
​
raw_message
string
Full, unprocessed commit message.

​
Without Conventional Commits

When conventional_commits = false:
​
id
string
Full commit SHA.
​
group
string
Commit group (assigned by commit_parsers).
​
scope
string
Commit scope (can be set by commit_parsers).
​
message
string
Full commit message (not parsed into parts).
​
conventional
boolean
Always false.
​
merge_commit
boolean
true if commit is a merge commit.
​
links
array
Array of link objects (same as conventional mode).
​
author
object
Commit author information.
​
committer
object
Commit committer information.
​
raw_message
string
Full commit message (same as message in this mode).

​
Footers

Conventional commits can contain structured footers: 
feat: add new feature

Signed-off-by: User Name <[email protected]>
Reviewed-by: Reviewer <[email protected]>
Fixes #1234
BREAKING CHANGE: API endpoint changed
Each footer is represented as:
​
token
string
Footer name (e.g., Signed-off-by, BREAKING CHANGE).
​
separator
string
Separator between token and value (: or #).
​
value
string
Footer value (text after the separator).
​
breaking
boolean
true if this is a BREAKING CHANGE footer.
Template example: 
{% if commit.footers %}
  {% for footer in commit.footers %}
    {{ footer.token }}{{ footer.separator }}{{ footer.value }}
  {% endfor %}
{% endif %}

​
Statistics Object

The statistics object provides release metrics:
​
commit_count
integer
Total number of commits in the release.
​
commits_timespan
integer
Number of days between the first and last commit.
​
conventional_commit_count
integer
Number of commits following conventional commits format.
​
links
array
Aggregated links from all commits with occurrence counts.
[
  {
    "text": "#452",
    "href": "https://github.com/owner/repo/issues/452",
    "count": 3
  }
]
​
days_passed_since_last_release
integer
Days between this release and the previous release.
Template example: 
### Commit Statistics

- {{ statistics.commit_count }} commit(s) contributed to the release.
- {{ statistics.commits_timespan | default(value=0) }} day(s) passed between the first and last commit.
- {{ statistics.conventional_commit_count }} commit(s) parsed as conventional.
- {{ statistics.links | length }} linked issue(s) detected in commits.
{%- if statistics.links | length > 0 %}
  {%- for link in statistics.links %}
    - [{{ link.text }}]({{ link.href }}) (referenced {{ link.count }} time(s))
  {%- endfor %}
{%- endif %}
{%- if statistics.days_passed_since_last_release %}
  - {{ statistics.days_passed_since_last_release }} day(s) passed between releases.
{%- endif %}

​
Remote Context

When using remote integrations (GitHub, GitLab, etc.), additional context is available:
​
remote.github
object
GitHub integration context.
{
  "owner": "orhun",
  "repo": "git-cliff"
}
Usage:
https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
​
github.contributors
array
GitHub contributor information (when GitHub integration is enabled).
[
  {
    "username": "octocat",
    "pr_number": 123,
    "is_first_time": true
  }
]
Template example:
{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
  ## New Contributors ❤️
{% endif %}
{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution
    {%- if contributor.pr_number %} in \
      [#{{ contributor.pr_number }}](https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}/pull/{{ contributor.pr_number }}) \
    {%- endif %}
{%- endfor %}
See the GitHub integration documentation for more details. The footer template has access to the releases array containing all releases: 
{% for release in releases %}
  {% if release.version %}
    {% if release.previous.version %}
      [{{ release.version | trim_start_matches(pat="v") }}]: \
        https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
          /compare/{{ release.previous.version }}..{{ release.version }}
    {% endif %}
  {% else %}
    [unreleased]: https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
      /compare/{{ release.previous.version }}..HEAD
  {% endif %}
{% endfor %}

​
Example: Complete Context

Here’s what a complete release context looks like: 
{
  "version": "v1.0.0",
  "message": "Release version 1.0.0",
  "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210",
  "timestamp": 1625169301,
  "repository": "/path/to/repository",
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "Features",
      "scope": "api",
      "message": "add user authentication",
      "body": "Implemented JWT-based authentication for API endpoints.",
      "footers": [
        {
          "token": "Reviewed-by",
          "separator": ": ",
          "value": "Jane Doe <[email protected]>",
          "breaking": false
        }
      ],
      "breaking": false,
      "breaking_description": null,
      "conventional": true,
      "merge_commit": false,
      "links": [
        {
          "text": "#123",
          "href": "https://github.com/owner/repo/issues/123"
        }
      ],
      "author": {
        "name": "John Doe",
        "email": "[email protected]",
        "timestamp": 1660330071
      },
      "committer": {
        "name": "John Doe",
        "email": "[email protected]",
        "timestamp": 1660330071
      },
      "raw_message": "feat(api): add user authentication\n\nImplemented JWT-based authentication for API endpoints.\n\nReviewed-by: Jane Doe <[email protected]>"
    }
  ],
  "commit_range": {
    "from": "81fbc6365484abf0b4f4b05d384175763ad8db44",
    "to": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210"
  },
  "statistics": {
    "commit_count": 15,
    "commits_timespan": 7,
    "conventional_commit_count": 14,
    "links": [
      {
        "text": "#123",
        "href": "https://github.com/owner/repo/issues/123",
        "count": 2
      }
    ],
    "days_passed_since_last_release": 30
  },
  "previous": {
    "version": "v0.9.0"
  }
}

​
Next Steps

  • Examples - See complete template configurations
  • Syntax - Learn Tera syntax and filters

Build docs developers (and LLMs) love

Get started for freeTalk to us