Add branch (headRefName) source filter

[chrisfarms]

What

Allows setting a "branch" in the source configuration, that filters the PR versions down to only those with a matching headRefName.

Why

When using instanced pipelines (one-pipeline-per-pr) it is desirable to monitor changes only for an individual PR and not all PRs. Pinning the resource version is not suitable for this use-case as the version contains the "commit" (we still want the resource to trigger on commit changes, we just only want to track those for a single PR).

Ideally we could filter by PR-number or some other unique ID, however the GraphQL API does not expose this, and we want to avoid filtering client-side.

Note

There should be a one-to-one mapping of headRefName to PR in most real-world usage, and so for this "one-pipeline-per-pr" use case, it is probably "good enough". However there is nothing stopping branch names getting reused over time, so you should not consider setting "branch" the same as "pinning" a resource version, it is merely a filter like state.

[vixus0]

@chrisfarms Does Concourse's partial version pinning help in this case (concourse/concourse#4380)? I think that would allow you to pin version.pr. I may be misunderstanding how the partial version pinning works though.

[chrisfarms]

Does Concourse's partial version pinning help in this case

Interesting @vixus0 .... I think could ... but the pr-resource does not seem to emit ALL versions during check, and so you get a state where the only version in the list returned from check would be for some other random PR won't match the version at all, and it becomes a game of probability wether it works or not.

By explicitly scoping the resource to a single PR (well branch) you get to treat the PR-resource more like you treat the git-resource, following commits on a single branch and not caring about other unrelated PRs as they change state.

[vixus0]

Yeah also I realise now the partial pinning results in weirdness with get steps passed param. In any case I'd like to see this PR merged 💯

[Mike-Dax]

We tried the partial pinning approach and found new commits on the PRs don't trigger new builds, so I'd be interested in having this merged and released.