Simplifing WIP pacts

[bethesque]

Background

The purpose of the WIP ("work in progress") pacts feature is allow pacts from the feature branches of the consumer to be verified automatically during a provider CI build without the provider having to change its configuration.

At the moment, this is achieved using some very complex logic to try and identify which pacts are currently being worked on by the consumer team. This complex logic is needed because the Pact Broker did not when a git branch was merged/deleted. Because pacts are not currently automatically removed from the Pact Broker when the git branch is merged or deleted, it is hard to tell which branches should be included for WIP pacts, and a date must be provided in the configuration to indicate how far back in the history the WIP pacts should start being detected.

Since the WIP pacts feature was implemented, we now have support for git branches (the original logic used tags).

Proposed change

• Add an "active" flag to the Pact Broker branch resource.
• Provide mechanisms for this active flag to be toggled when a git branch is merged or deleted in SCM (eg. github actions, SCM webhook). Discontinue use of the WipPactsSince date.
• Add support for a new consumer version selector { branch: true, active: true} which will return the pacts for all active branches. The "pending" feature will continue to ensure that the newly changed pacts to not cause the provider build to fail.

The reason for using a flag on the branch rather than just deleting the branch and associated pacts is that some teams will merge, but leave the branch there, and some will delete the branch. Using the phrase "you should verify the pacts from all active branches" makes sense when describing the real world, and then would translate directly into the Pact Broker domain model. The branches can then be cleared up using the clean function, or using a SCM hook, as a separate concern from determining which pacts to verify.

The reason I think using a flag called "active" is better than "merged" is because some branches may be merged into other branches that are not main, and may still be considered active. The customer would be able to choose at what point a branch is no longer considered active (eg. when it's deleted, when it's merged, when it's too old etc).

I would expect the lifecycle of the active flag to go:

• pact published with branch (branch created and marked active)
• PR merged (SCM hook marks branch as inactive)

If a pact was for some reason re-published from a branch with the same name as a branch previously marked as inactive, it would set it to active again.

Required work

• add active flag to branch resource
• add support for marking as inactive via API, CLI, GithubAction (Gitlab if possible?)
• add support for new consumer version selector
• provide mechanism for bulk marking historical branches as inactive via CLI
• update docs

[bethesque]

cc: @mefellows @uglyog

[mefellows]

add support for marking as inactive via API, CLI, GithubAction (Gitlab if possible?)

A webhook endpoint that is aware of the various CI providers for this would be an excellent addition.

[bethesque]

Wip pacts doesn't work for trunk based dev. Unless they're somehow manually using tags.

[mefellows]

Yeah, I was thinking this advice: https://docs.pact.io/pact_broker/tags#using-tags-with-feature-toggles-instead-of-feature-branches

[bethesque]

We really need to work out how to support feature toggles properly. Is it on our "roadmap" somewhere?

[mefellows]

It's currently here 👉 https://pact.canny.io/feature-requests/p/add-better-support-for-workflows-that-are-managed-by-feature-toggles-rather-than

(we have a PF tracking item also)

[rholshausen]

Sounds all ok to me

[ulises]

I have a potentially unrelated question: the phrase

Using the phrase "you should verify the pacts from all active branches" makes sense when describing the real world

sounds strange to me. Perhaps I got it all wrong, but a flow like: verify all contracts + check only relevant(*) verification results in can-i-deploy makes sense to me. So I'd like to ask: is the notion of verifying a subset of all published contracts ever an optimisation on the above flow?

(*) relevant to the environment you're trying to deploy to

[mefellows]

check only relevant(*) verification results in can-i-deploy makes sense to me

In what way does it not work like that now?

[bethesque]

Updated plan for killing WIP pacts.

The "Active" flag on the branch resource has not been implemented. What has been implemented is the consumer version selector { branch: true, latest: true} which will return the pacts for the latest version of every branch.

For this selector to be useful, the customer must only have the provider branches in the Pact Broker that correspond to active branches in their SCM. For this to be achieved, the user must set up a post branch delete hook in their SCM that removes the corresponding branch resource from the Pact Broker as described in Yousaf's blog post here. It's actually probable that this should be done on branch merge, rather than on branch delete. Often the two are tied together, but not always.

For existing Pact Broker users who want to bulk delete all their old branches, there is a new endpoint that does bulk delete, however, it is not yet documented. The endpoint is designed to be called by the Pact Broker CLI, but I haven't done the CLI for it yet. Here is an example of how to delete all the branches for some-api except for branch-to-keep-1 and branch-to-keep-2.

curl -v -X DELETE https://pact-broker:9292/pacticipants/some-api/branches -G  --data-urlencode "exclude[]=branch-to-keep-1"   --data-urlencode "exclude[]=branch-to-keep-2"

There is a CLI command in the Github API which allows you to list active branches, and I was working on a script to plug the output of that into the bulk delete command, but I didn't get time to finish it before I went on leave.

The API deletes the branches asynchronously, and doesn't actually delete the application versions or pacts - it just deletes the branches. This means that even though the pacts still exist, they won't show up in the "latest pact for each branch" verification response.

I had thought of making the single and bulk delete endpoints also delete the versions and pacts (perhaps by supporting a query param that explicitly specifies to delete the associated data), but I haven't got that far.

So, in summary, we should have everything we need now to kill WIP pacts - it's just documentation that needs to be updated. I was going update all the pactflow code to use this new approach to validate the approach before we documented it for the public, but I didn't get time. It would be great if someone from the Pactflow team could make this happen.

TODO

• Choose one Pactflow internal integration that uses pact as a test bed for the new approach
• Add the "post branch delete" hook to the provider side in Github if it isn't there already (I've added at least one)
• Clean up all the old provider branches using the bulk delete endpoint
• Update consumer to use the new { branch: true, latest: true} selector in the consumer version selectors. Hopefully this is supported out of the box in the dynamically typed language libraries that we use.
• Make some changes to the integration, add and delete some branches, and make sure the expected workflow is happening.
• Check that the new selector works in all the languages. Previously, the branch key only supported a string name. Now it supports either a string name or the boolean true. This may be uncomfortable in some languages, and Pact JVM will definitely need code changes to support this selector, because Java.
• Update the docs and example codebases, making sure to include docs for the bulk delete endpoint. Don't forget this page https://docs.pact.io/provider/recommended_configuration
• Profit
• Never speak about WIP pacts again

[mefellows]

Thanks Beth! IIUC this issue has an endpoint that also deletes the related pacts for a branch.

Presumably if that bug was fixed, a user could call that endpoint to remove old pacts and then delete the branch (both in an SCM hook or something)? Does that API leave behind any versions associated with other branches too or other relationships?

[Ilia]

cc @pahnin

[bethesque]

I would just leave the old versions and pacts for the clean up job to get rid of.

[bethesque]

I did do the code to delete the associated versions and pacts (if they were not associated with any other branches) #711 It's not finished however, as the code needs to updated to also not delete a version if it is deployed/released.

[mefellows]

For this selector to be useful, the customer must only have the provider branches in the Pact Broker that correspond to active branches in their SCM.

Did you mean consumer branch?