Merge cascade plugin

This plugin replicates the support for the original Cascading Merge feature of Bitbucket Server and Data Center, with additional configurations and better tracking using Flowie unique features.

It creates a pull request based on the cascade policies, with an associated label which can be used to apply different workflows to the cascade pull request. You can merge using whatever strategy you define, and also use Flowie’s smart auto merge feature.

Flowie also links the cascade pull request to the original pull requests that are being cascaded.

And in the original pull request, you can see which branches have been targeted already.

In the example above, it is cascading 1.x -> 2.x -> 3.x -> main and we can see that cascade to main is still pending.

A typical configuration for the cascade plugin:

ts
import {configure} from "flowie.app"
import {source, labels, otherwise} from "flowie.app/conditions"
import {merge, mergeCascade} from "flowie.app/plugins"
 
configure({
  plugins: [
    mergeCascade(),
    merge(
      [
        labels.has("Cascade"),
        {
          strategies: "merge",
          autoMerge: true,
          closeBranch: source(/^cascade-fail\/.*/),
          select: false,
        },
      ],
      [
        otherwise,
        {
          closeBranch: true,
          select: ["strategy"],
        },
      ]
    ),
  ],
})

Options:

policies - Cascade policies that for triggering the cascade. Default replicates the Bitbucket server cascade merge order and conditions.

pullRequest - Specify the details for the newly created pull request.

pullRequest.label - Default: Cascade

pullRequest.otherLabels - Default: None

Auto merge

You can use the merge plugin and conditions to specify the pull request to be merged automatically. You can also set the merge strategy and other aspects of how Flowie should merge this pull request.

In the example above, we use the default label added to the pull request to specify a workflow for it that:

• Automatically merges the cascade using smart auto merge
• Always use the merge strategy
• Only closes the branch if it is from a failure cascade

Failed cascade

If a conflict is detected in the cascade, Flowie will rename the source branch to use a cascade-fail prefix, which allows the pull request’s conflict to be manually resolved.

Usually, the pull request’s conflict should be resolved by checking out the destination branch, merging the source branch into it, while resolving the conflicts and pushing it back into the source branch.

Skipping checks

You can have different checks applied to the cascade. For instance, cascaded changes come from stable branches, so you might want to skip the review in this case using conditions.

ts
minimumApprovals([source(/^release\/.*/), 0], [otherwise, 2])

Cascade policies

By default, the cascade policies replicate Bitbucket Server’s cascading merge functionality. However, you have full control on how you want the cascade to behave.

A cascade policy has a from property that defines which branches should trigger a cascade. The to defines the branches that will receive the cascade and also the sequence in which it should occur. Both properties accept a glob or a RegExp.

They can be defined to cascade up or down, using the order property, depending on your workflow. All matched policies are applied.

ts
import {configure} from "flowie.app"
import {mergeCascade} from "flowie.app/plugins"
 
configure({
  plugins: [
    mergeCascade({
      policies: [{from: "hotfix/*", to: ["main"]}],
    }),
  ],
})

Default policy

When no policies are specified, Flowie will infer them from the branching model configured for the repository. The inferred policies replicate the rules of Bitbucket Server’s cascading merge. The policies for a repository with release branches configured to ‘release/’, development as ‘develop’ and production branch as ‘main’ would be equivalent to:

ts
import {configure} from "flowie.app"
import {mergeCascade} from "flowie.app/plugins"
 
const releaseRegExp = /^release\/(?<prefix>[A-Za-z-]*)\d+(\.\d+)*$/
 
configure({
  plugins: [
    mergeCascade({
      policies: [
        // production -> development
        {from: "main", to: ["develop"]}, // Using globs
        // release/1.x -> release/2.x -> development
        // OR
        // release/xyz-1.0 > release/xyz-2.x -> devevelopment
        {from: releaseRegExp, to: [releaseRegExp, "develop"]},
      ],
    }),
  ],
})

The example above uses a RegExp to match release and specifies a named capturing group. When a named capturing group is present in the to and from properties, Flowie will ensure they are the same when selecting the next branch. In this case, it ensures release/xyz-1.0 does not cascade to release/2.0.

Labels

By default, the 'Cascade' label is added to the newly created pull requests. However, you can use a custom label that you’ve defined in the labels’ schema.

You can also have additional labels associated with the pull request at creation.

ts
import {configure} from "flowie.app"
import {mergeCascade} from "flowie.app/plugins"
 
configure({
  labels: {
    schema: [
      //  The used labels here ...
    ],
  },
  plugins: [
    mergeCascade({
      pullRequest: {
        label: {name: "Type", value: "Cascade"},
        otherLabels: [{name: "Priority", value: "High"}],
      },
    }),
  ],
})

Further reference: