github / branch-deploy

Enabling Branch Deployments through IssueOps with GitHub Actions - If you find this project useful, give it a star! ⭐️
https://github.com/marketplace/actions/branch-deploy
MIT License
384 stars 45 forks source link

Update Base Branch Improvements #237

Closed GrantBirki closed 9 months ago

GrantBirki commented 9 months ago

Update Base Branch Improvements


⚠️ breaking change! ⚠️ - This will initiate a new major release of this Action. The target release is v9.0.0

It should be noted that this change is only "breaking" in the sense that unexpected behavior may take place for teams using more unique git flows for development. If you want to maintain the current state of this Action on v9.0.0 and beyond, all you need to do is to simply set outdated_mode: "pr_base" in the Action configuration. This will keep the current logic of this Action where only the pr_base is evaluated for "out-of-date-ness".


This pull request updates the language around updating branches in this Action to make it more clear what is happening to the user.

It also adds a new input option called outdated_mode.

Here is the full (very verbose) documentation to this new input option:

Issue #253 contains a great discussion about the outdated mode and why it was added as a feature to this project.

The outdated_mode input option gives you the ability to determine how the branch-deploy Action should handle outdated branches. This input option is closely related to the update_branch input option as well.

Using the outdated_mode input option

The outdated_mode input option has three possible values:

How the outdated_mode input option works with the update_branch input option

If your branch is determined to be out-of-date, the branch-deploy Action will not deploy your branch. What happens next is determined by the value of the update_branch input option. Here are the three possible values for the update_branch input option and how they will operate:

It should be noted that if you are using the force value for the update_branch input option, the branch-deploy Action will only attempt to update your branch with the target base branch of the pull request. This means that if your target base branch is something other than the default|stable branch, the branch-deploy Action will only attempt to update your branch with the latest commits from the target base branch. You will still be warned about your branch being out-of-date with the default|stable branch but it will not try to update your branch with the latest commits from the default|stable branch due to the complexity and potential risk involved with such a merge. You will need to manually update your branch with the latest commits from the default|stable branch if you want to deploy your branch and that is the case.

The final bit of important information to note is that rollback deployments (i.e .deploy main) will always work even if the default|stable branch is considered out-of-date. This is for safety reasons so that users of this Action can always rollback their changes in the event of an issue.

About the outdated_mode input option

The outdated_mode input option is useful when you want to ensure that the branch-deploy Action only deploys branches that are up-to-date. This is especially useful when you have a large team of developers working on a project and you want to ensure that commits are not rolled back accidentally when you are deploying a branch. For the sake of availability and deployment confidence, this input option is set to strict by default. This will ensure that your branch is up-to-date with the latest commits from both the default|stable branch and the branch that your pull request is merging into.

Example Scenarios

This section will go into a few example scenarios to help you understand how the outdated_mode input option works in practice.

Big thanks to @jessew-albert for providing these examples!

For all scenarios, we assume that we are operating on a pull request that is at branch featureB (commit featB2) in the diagram. The target base branch of the pull request is featureA and the default|stable branch is main.

Scenario 1

This example diagram shows a scenario where a branch is created from the default|stable branch (main in this case). The name of this branch is featureA and a following branch is created from featureA called featureB. A few commits are made to the featureB branch and sometime later, another developer merges two commits into main. The featureB branch is now out-of-date with main even though it is up-to-date with the featureA branch. In this example, the target base branch of featureB is featureA.

gitGraph
   commit id: "A"
   commit id: "B"
   branch featureA
   checkout featureA
   commit id: "featA1"
   commit id: "featA2"
   branch featureB
   checkout featureB
   commit id: "featB1"
   commit id: "featB2"
   checkout main
   commit id: "C"
   commit id: "D"

Let's pretend that we are trying to run the .deploy command on the pull request associated with featureB (which is trying to merge into featureA).

Scenario 2

This scenario shows the "ideal" situation for a successful deployment. In this example, the featureB branch is up-to-date with both the featureA branch and the main branch. When this is the case, it does not matter which value you have set for the outdated_mode input option. Whether you have it set to strict, pr_base, or default_branch, all options in this case are up-to-date and the branch-deploy Action will allow the deployment to happen. Hooray!

This diagram expands upon Scenario 1 and shows the featureB branch being updated by having main merged into it:

gitGraph
   commit id: "A"
   commit id: "B"
   branch featureA
   checkout featureA
   commit id: "featA1"
   commit id: "featA2"
   branch featureB
   checkout featureB
   commit id: "featB1"
   commit id: "featB2"
   checkout main
   commit id: "C"
   commit id: "D"
   checkout featureB
   merge main

Alternatively, you could rebase the stack with featureA and featureB on top of main:

gitGraph
   commit id: "A"
   commit id: "B"
   commit id: "C"
   commit id: "D"
   branch featureA
   checkout featureA
   commit id: "featA1"
   commit id: "featA2"
   branch featureB
   checkout featureB
   commit id: "featB1"
   commit id: "featB2"

Scenario 3

In this scenario, the branch featureB is now out-of-date in all cases. This is because the featureB branch is behind both the featureA branch and the main branch. This is the worst-case scenario and the branch-deploy Action will prevent the deployment from happening in all cases. It does not matter what value you have set for the outdated_mode input option. Whether you have it set to strict, pr_base, or default_branch, all options in this case are out-of-date and the branch-deploy Action will prevent the deployment from happening.

gitGraph
   commit id: "A"
   commit id: "B"
   branch featureA
   checkout featureA
   commit id: "featA1"
   commit id: "featA2"
   branch featureB
   checkout featureB
   commit id: "featB1"
   commit id: "featB2"
   checkout featureA
   commit id: "featA3"
   checkout main
   commit id: "C"
   commit id: "D"

Scenario 4

In this example, the featureB branch is behind featureA but up-to-date with main. In this case, the outdated_mode input option will determine whether the branch-deploy Action will allow the deployment to happen or not.

gitGraph
   commit id: "A"
   commit id: "B"
   branch featureA
   checkout featureA
   commit id: "featA1"
   commit id: "featA2"
   branch featureB
   checkout featureB
   commit id: "featB1"
   commit id: "featB2"
   checkout featureA
   commit id: "featA3"

related: https://github.com/github/branch-deploy/issues/235