The new Merge Rules system
Now, you can restrict merges to happen only if certain rules are met. We call this new feature "Merge Rules" and it is available both for on-premises (Team and Enterprise) and Cloud Edition.
It is very easy to set rules like "don't allow to merge branches if they are not reviewed" and "only allow merges from child branches" among others.
Previously, you'd have to write a trigger to enforce this behavior, but now it is just a matter of setting a few merge rules.
Types of merge rules
With the Merge Rules system, you can restrict merges to certain branches, so that:
- They only allow to merge some branches if they are reviewed.
- They only allow merges from certain branches.
- They only allow to merge from parent or child branches.
Let's see below in detail these merge rules.
How the Merge Rules system works
- You must first specify one or more merge rules.
A merge rule defines:
- If the merge rule is enabled or not
- The affected repositories
- A restriction:
- The restriction includes the source and destination branches involved in the merge.
- These branches must match a pattern.
- The branch matching works by specifying one or more of the following filters:
- branch name patterns (with '*' to represent any substring)
- branch attribute names and, optionally, attribute values
You can see is this section how filtering works.
Let's see a merge rule example to clarify these concepts:
- Then, when you're about to merge a branch, the server will check whether there are any rules that apply to the involved source/destination branches pair.
'only_allow_merges_if_reviewed' rule
Definition
Only allows to merge branches if they have an approved code review. It is an equivalent to the popular "pull request restrictions" that force to review branches before merge.
Example
[{
"enabled": true,
"repositories": "*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchNames": ["main"]
},
"from":
{
"branchNames": ["QUAK-*"],
}
}]
This (enabled) rule applies to all repositories and forces all branches named QUAK-* to be reviewed prior to be merged to main.
In the diagram below, only branch QUAK-001 will merge to main:
If a merge can't happen, you'll receive an error like this:
Cannot perform the merge. Review the branch '/main/QUAK-002' to merge it to '/main'.
'restrict_merges_to_branch' rule
Definition
Restricts merges to a given branch. This way, the merges to that branch can only come from a given set of branches.
It is possible to specify rules that apply to groups of branches too.
Example
[{
"enabled": true,
"repositories": "codice",
"rule": "restrict_merges_to_branch",
"to":
{
"branchNames": ["/fix3.0"],
},
"from":
{
"branchNames": ["fixes-*"],
}
}]
In repository codice, merges to branch /fix3.0 are only allowed from branches named fixes-*. (Remember that you can use wildcards.)
In the diagram below, branches /fix-3.0/fixes-089 and /fix-3.0/fixes-090 will merge to fix-3.0:
'only_allow_merges_from_parent' rule
Definition
Only allows merges to a given branch that come from its parent.
This is very useful to enforce that certain branches only allow to be rebased from the parent, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.
Example
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_parent",
"to":
{
"branchNames": ["task*"],
}
}]
In repositories named like game*, branches with name task* can only receive merges from their parent branch. This way you can prevent merges across different task branches.
In the diagram below, branch task001 will receive merges from main, and branch task003 will receive merges from dev-002:
'only_allow_merges_from_children' rule
Definition
Only allows merges to a given branch that come from its child branches.
This is very useful to enforce that certain branches only allow merges from the children, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.
Example
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_children",
"to":
{
"branchNames": ["iteration*"],
}
}]
In the repositories with name game*, branches with name iteration* can only receive merges from their child branches.
In the diagram below, /main/iteration-32/task23 can be merged into /main/iteration-32, but it cannot be merged into /main/iteration-15, as it is not a child of that branch:
Filtering
To filter the branches involved in a rule, you can use the branches name, the branches attribute or both:
- Filtering by name: Use the
branchNameskey to specify the branch names. For example:[{ "enabled": true, "repositories": "game*", "rule": "only_allow_merges_if_reviewed", "to": { "branchNames": ["main"] }, "from": { "branchNames": ["scm*"], } }] - Filtering by attribute: Use the
branchesWithAttributekey to filter by attribute by specifying the attribute name and, optionally, a value. For example:[{ "enabled": true, "repositories": "*", "rule": "only_allow_merges_if_reviewed", "to": { "branchesWithAttribute": [ { "attribute": "merge_only_reviewed", "value": "enabled" } ] }, "from": { "branchesWithAttribute": [ { "attribute": "task", } ] } }] - Filtering by name and attribute: Combine the above filters to filter by branch name and attribute. For example:
[{ "enabled": true, "repositories": "game*", "rule": "only_allow_merges_from_parent", "to": { "branchNames": ["scm*"], "branchesWithAttribute": [ { "attribute": "restricted_rebases", "value": "yes" } ] } }]or:
[{ "enabled": true, "repositories": "game*", "rule": "only_allow_merges_if_reviewed", "to": { "branchesWithAttribute": [ { "attribute": "merge_only_reviewed" } ] }, "from": { "branchNames": ["scm*"], } }]
Managing the Merge Rules
The merge rules are stored in the mergerules.conf file in the server directory (where plasticd.exe is located). This is a JSON file that contains your configured merge rules.
The merge rules in this file must to be placed inside an array [].
The following is an example of a mergerules.conf file with two merge rules:
[{
"enabled": true,
"repositories": "code*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchNames": ["main"],
"branchesWithAttribute": [
{
"attribute": "merge_only_reviewed",
"value": "enabled"
}
]
},
"from":
{
"branchNames": ["scm*"],
"branchesWithAttribute": [
{
"attribute": "task",
}
]
}
},
{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_parent",
"to":
{
"branchNames": ["scm*"],
"branchesWithAttribute": [
{
"attribute": "restricted_rebases",
"value": "yes"
}
]
}
}]
You will find a mergerules.conf file with some examples in your server directory, inside config_samples, and alongside the binaries for clean setups (on Windows using the installer, and GNU/Linux using the official packages) so you can directly modify it.
How can you configure your merge rules?
mergerules.conf:To configure your merge rules, you can directly edit the
mergerules.conffile in yourserverdirectory.You don't need to restart the server for changes to take effect!- Merge Rules section in the WebAdmin:
You can manage your Merge Rules from the WebAdmin. You can select and configure the ones that fit your needs best.
You don't need to restart the server for changes to take effect! - Merge Rules for your cloud organization repositories:
To configure the Merge Rules for your cloud organization repositories, go to your cloud dashboard and click the Edit Merge Rules button:
A new dialog appears where you can manage your Merge Rules for your selected cloud repository:
Availability
We first launched the Merge Rules system in release BL3442. This first system only supported the only_allow_merges_if_reviewed rule.
But since release release BL3515, the Merge Rules system supports the four merge rules described above:
only_allow_merges_if_reviewedrestrict_merges_to_branchonly_allow_merges_from_parentonly_allow_merges_from_children
Wrapping up
The Merge Rules system lets you define what branches can be merged by following matching rules related to the affected repositories, and source and destination branches.
These rules are stored in the mergerules.conf file in the server directory (where plasticd.exe is located).
You can manage your merge rules by directly editing the mergerules.conf file or by using the Merge rules section in the WebAdmin. Remember that you can also configure merge rules for your cloud repositories.
0 comentarios: