Configure your commit messages

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Astro

Bridgetown

Docusaurus

Eleventy

Gatsby

Hugo

Jekyll

Lume

MkDocs

Next.js

Nuxt

Static

SvelteKit

Custom

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

A commit message is a short piece of text used to describe changes you make to you website. Commit messages provide a record of your changes for you and your team members. If you have commit messages configured, the Review changes modal will prompt you to add a commit message every time you save your changes.

Commit messages in CloudCannon use predefined templates to maintain a consistent format. These templates use template strings to populate the commit message with a mix of text and data. For more information, please read our documentation on template strings.

You can configure a commit message by adding the array key commit_templates to your global configuration file.

Commit messages and external integrations#

Depending on your Git provider, some external programs can integrate with your repository and read your commit messages. For example, the Jira and GitHub integration enables commits to your repository that use a specific commit message format to close Jira tickets.

It is important to configure your template string correctly if you need your commit message to match a particular format for an integration.

Configure a commit template#

To configure a basic commit message:

1. Navigate to your global configuration file and open it in the Source Editor.
2. Identify the commit_templates key, or create one at the top level of your configuration file.
3. Add a template_string item within the commit_templates array.
4. Save your changes to the global configuration file.

Here is an example of a simple commit message using a text string.

commit_templates:
  - template_string: '{message}'

{
  "commit_templates": [
    {
      "template_string": "{message}"
    }
  ]
}

module.exports = {
  commit_templates: [
    {
      template_string: "{message}"
    }
  ]
};

Once you have saved the changes to your global configuration file, the Review changes modal in CloudCannon will update to include a commit message.

Placeholders in commit templates#

Commit templates can use placeholders. When CloudCannon reads a placeholder in a commit message, it will replace it with the data it references before sending the commit message to your Git repository.

There are two types of placeholders:

• Data placeholders — Replaced with data you have defined. These placeholders use { } brackets.
• Fixed placeholders — Replaced with data defined by CloudCannon. These placeholders use [ ] brackets.

For commit message templates, data placeholders reference inputs you have defined in your global configuration file under commit_templates._inputs. If you do not define a data placeholder used by your commit template, CloudCannon will use the default input type based on the placeholder name (e.g., a date picker for {date}, or a text input for {message}).

CloudCannon recognizes the following fixed placeholders in commit templates:

• [changes] creates a bulleted list of all changes in the commit (edits, additions, and deletions).
• [date] reads as the current date.
• [author] reads as the email address of the person making the commit.
• [default_commit_message] creates the default commit message that CloudCannon would generate. This will resolve to a sentence like "Added/Updated X file(s)".

You can use a mix of data and fixed placeholders in your commit templates.

commit_templates:
  - template_string: |
      {ticket_number}: {subject}
      Committed by [author] at [date]
    _inputs:
      ticket_number:
        type: number

{
  "commit_templates": [
    {
      "template_string": "{ticket_number}: {subject}\nCommitted by [author] at [date]\n",
      "_inputs": {
        "ticket_number": {
          "type": "number"
        }
      }
    }
  ]
}

module.exports = {
  commit_templates: [
    {
      template_string: "{ticket_number}: {subject}\nCommitted by [author] at [date]\n",
      _inputs: {
        ticket_number: {
          type: "number"
        }
      }
    }
  ]
};

For more information on placeholders in general, please read our documentation on configuring your template strings.

Filters in commit templates#

Commit templates can use filters to modify placeholders. Filters should occur after the placeholder name, separated by a | character. You can apply multiple filters to a single placeholder. For example, {title|trim|uppercase} will remove leading and trailing whitespace, then uppercase, a data placeholder called "title".

For more information, including a full list of filters, please read our documentation on configuring your template strings.

Multiple commit templates#

You can configure multiple commit message template strings in your global configuration file. When you or a team member save changes to your website, the Review changes modal will prompt you to select which template to use. In this case, adding a label to each template string is important.

Here is an example of multiple commit message templates.

commit_templates:
  - label: Custom message
    template_string: '{message}'
  - label: Structured message
    template_string: '{commit_type}: {message|trim}'
    _inputs:
      commit_type:
        type: select
        options:
          values:
            - feature
            - fix
            - refactor

{
  "commit_templates": [
    {
      "label": "Custom message",
      "template_string": "{message}"
    },
    {
      "label": "Structured message",
      "template_string": "{commit_type}: {message|trim}",
      "_inputs": {
        "commit_type": {
          "type": "select",
          "options": {
            "values": [
              "feature",
              "fix",
              "refactor"
            ]
          }
        }
      }
    }
  ]
}

module.exports = {
  commit_templates: [
    {
      label: "Custom message",
      template_string: "{message}"
    },
    {
      label: "Structured message",
      template_string: "{commit_type}: {message|trim}",
      _inputs: {
        commit_type: {
          type: "select",
          options: {
            values: [
              "feature",
              "fix",
              "refactor"
            ]
          }
        }
      }
    }
  ]
};

Commit templates from a file#

Rather than configure a template string in your global configuration file, you can configure a template_path to point at a file containing your commit template. CloudCannon will use the content of this file as your template string.

This could be a better option if you already have a file containing your commit message template or want to prevent a long commit template from taking up space in your global configuration file.

commit_templates:
  - label: Commit message from file
    template_path: /.git/commit-message.txt

{
  "commit_templates": [
    {
      "label": "Commit message from file",
      "template_path": "/.git/commit-message.txt"
    }
  ]
}

module.exports = {
  commit_templates: [
    {
      label: "Commit message from file",
      template_path: "/.git/commit-message.txt"
    }
  ]
};

Extra data#

In some cases, you may need to create nested template strings. You can define another template string using the extra_data key. Anything defined under extra_data is processed sequentially and before template_path or template_string.

Let’s walk through an example.

We want to create an optional text field called “Breaking Change Message” for our team members to fill out when they commit a breaking change to our repository. To draw attention to the breaking change message, want the message to appear after a blank line and a ⚠️ warning emoji. When the breaking change input contains no text, we do not want any formatting associated with this message to appear in the commit.

commit_templates:
  - template_string: '{message}{breaking_change|if=breaking_change_message}'
    _inputs:
      breaking_change_message:
        type: text
    extra_data:
      breaking_change: |-

        ⚠️ {breaking_change_message}

{
  "commit_templates": [
    {
      "template_string": "{message}{breaking_change|if=breaking_change_message}",
      "_inputs": {
        "breaking_change_message": {
          "type": "text"
        }
      },
      "extra_data": {
        "breaking_change": "\n⚠️ {breaking_change_message}"
      }
    }
  ]
}

module.exports = {
  commit_templates: [
    {
      template_string: "{message}{breaking_change|if=breaking_change_message}",
      _inputs: {
        breaking_change_message: {
          type: "text"
        }
      },
      extra_data: {
        breaking_change: "\n⚠️ {breaking_change_message}"
      }
    }
  ]
};

In the Review changes modal, this will appear as two text fields. If no text is entered into the field for Breaking Change Message, then the extra formatting does not appear in the commit message.

Options#

Commit templates have the following configuration options available: