From 8280c175871a46ec415302d11db9ae3720156f26 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Sat, 4 Jul 2026 15:37:42 -0400
Subject: [PATCH] docs: document configurable templates
---
docs/v2/configuration/overview.mdx | 28 ++++++++++++
.../user/environments/merge-proposals.mdx | 43 +++++++++++++++++++
2 files changed, 71 insertions(+)
diff --git a/docs/v2/configuration/overview.mdx b/docs/v2/configuration/overview.mdx
index 34e4016..138dc05 100644
--- a/docs/v2/configuration/overview.mdx
+++ b/docs/v2/configuration/overview.mdx
@@ -626,6 +626,34 @@ Analytics configuration enables collection and export of feature flag evaluation
## Additional Settings
+### Templates
+
+Templates configuration customizes the generated commit messages and merge proposal content that Flipt creates for Git-backed workflows. Template values use Go [`text/template`](https://pkg.go.dev/text/template) syntax.
+
+| Property | Description | Default | Since |
+| ------------------------ | ---------------------------------------------- | ------- | ------ |
+| templates.commit_message | Commit message template for UI-created changes | | v2.5.0 |
+| templates.proposal_title | Merge proposal title template | | v2.5.0 |
+| templates.proposal_body | Merge proposal body template | | v2.5.0 |
+
+```yaml config.yaml
+templates:
+ commit_message: "{{ (index .Changes 0) }} [skip ci]"
+ proposal_title: "Flipt: Update {{.Base.Ref}} from {{.Branch.Ref}}"
+ proposal_body: |
+ This proposal updates Flipt resources.
+
+ Source branch: {{.Branch.Ref}}
+ Target branch: {{.Base.Ref}}
+```
+
+Server-wide templates override Flipt's built-in defaults. Repository-level templates in `flipt.yaml` or `flipt.yml` override server-wide templates for that repository.
+
+
+ Flipt validates configured templates when it loads the configuration. Invalid
+ server-wide templates prevent the configuration from loading.
+
+
### License
License configuration enables Pro features by providing a valid license key.
diff --git a/docs/v2/guides/user/environments/merge-proposals.mdx b/docs/v2/guides/user/environments/merge-proposals.mdx
index 3b86d1f..87beee8 100644
--- a/docs/v2/guides/user/environments/merge-proposals.mdx
+++ b/docs/v2/guides/user/environments/merge-proposals.mdx
@@ -56,6 +56,49 @@ Refresh the page and click the branch info label again to see the merge proposal
Click the `View open merge proposal` button to view the merge proposal in the SCM provider.
+### Customizing Generated Titles and Descriptions
+
+Flipt generates merge proposal titles and descriptions from Go [`text/template`](https://pkg.go.dev/text/template) templates. You can configure server-wide defaults in your Flipt configuration:
+
+```yaml config.yaml
+templates:
+ proposal_title: "Flipt: Update {{.Base.Ref}} from {{.Branch.Ref}}"
+ proposal_body: |
+ This proposal updates Flipt resources.
+
+ Source branch: {{.Branch.Ref}}
+ Target branch: {{.Base.Ref}}
+```
+
+The template context includes:
+
+| Field | Description |
+| ------------------- | -------------------------------------------- |
+| `.Base` | The target environment configuration |
+| `.Branch` | The source branch environment configuration |
+| `.Base.Ref` | The target Git reference, such as `main` |
+| `.Branch.Ref` | The source Git reference for the branch |
+| `.Base.Directory` | The target directory, when one is configured |
+| `.Branch.Directory` | The branch directory, when one is configured |
+
+Repository-level templates in `flipt.yaml` or `flipt.yml` override the server-wide templates for that repository:
+
+```yaml flipt.yaml
+version: "2.0"
+templates:
+ proposal_title: "Flags: {{.Branch.Ref}} into {{.Base.Ref}}"
+ proposal_body: |
+ Review changes from {{.Branch.Ref}} before merging into {{.Base.Ref}}.
+```
+
+
+ These templates configure the generated defaults. If a merge proposal request
+ provides a title or description, Flipt uses the provided value instead of the
+ template. The Flipt UI can provide a one-off description, but it does not yet
+ let you edit the configured template text or override the generated title
+ directly.
+
+
### Review and Merge a Merge Proposal
Reviewing and merging a merge proposal is the same as reviewing and merging a code pull request in your SCM provider.