Add positive and negative head branch filters

For some workflows, it can be useful to treat pull requests differently
depending on the name of the head branch for the pull request.

For example, a team following scaled trunk-based development might use
the `release/*` naming convention for release branches, and may have
different build/deploy processes for those release branches.

This adds `head_branches` and `ignore_head_branches` settings to this
resource, specified as a glob pattern to align with similar filters on
the Concourse git resource, so that teams can run different jobs based
on the head branch of a PR.

See: https://trunkbaseddevelopment.com/#scaled-trunk-based-development

README.md

@@ -34,6 +34,8 @@ Make sure to check out [#migrating](#migrating) to learn more.
 | `required_review_approvals` | No       | `2`                              | Disable triggering of the resource if the pull request does not have at least `X` approved review(s).                                                                                                                                                                                      |
 | `git_crypt_key`             | No       | `AEdJVENSWVBUS0VZAAAAA...`       | Base64 encoded git-crypt key. Setting this will unlock / decrypt the repository with git-crypt. To get the key simply execute `git-crypt export-key -- - | base64` in an encrypted repository.                                                                                             |
 | `base_branch`               | No       | `master`                         | Name of a branch. The pipeline will only trigger on pull requests against the specified branch.                                                                                                                                                                                            |
+| `head_branches`        | No       | `release/*`                      | If specified, the pipeline will only trigger on pull requests for which the head branch name matches the specified glob pattern.                                                                                                                                                            |
+| `ignore_head_branches`        | No       | `feature/*`                      | Inverse of the above                                                                                                                                                            |
 | `labels`                    | No       | `["bug", "enhancement"]`         | The labels on the PR. The pipeline will only trigger on pull requests having at least one of the specified labels.                                                                                                                                                                         |
 | `disable_git_lfs`           | No       | `true`                           | Disable Git LFS, skipping an attempt to convert pointers of files tracked into their corresponding objects when checked out into a working copy.                                                                                                                                           |
 | `states`                    | No       | `["OPEN", "MERGED"]`             | The PR states to select (`OPEN`, `MERGED` or `CLOSED`). The pipeline will only trigger on pull requests matching one of the specified states. Default is ["OPEN"].                                                                                                                         |

check.go

@@ -60,6 +60,28 @@ Loop:
 			continue
 		}
 
+		// Skip pull request if the HeadRefName does not match the head_branches glob specified in source
+		if request.Source.HeadBranches != "" {
+			matched, err := filepath.Match(request.Source.HeadBranches, p.PullRequestObject.HeadRefName)
+			if err != nil {
+				return nil, fmt.Errorf("failed to apply head branch filter: %s", err)
+			}
+			if !matched {
+				continue
+			}
+		}
+
+		// Skip pull request if the HeadRefName matches the ignore_head_branches glob specified in source
+		if request.Source.IgnoreHeadBranches != "" {
+			matched, err := filepath.Match(request.Source.IgnoreHeadBranches, p.PullRequestObject.HeadRefName)
+			if err != nil {
+				return nil, fmt.Errorf("failed to apply ignore head branch filter: %s", err)
+			}
+			if matched {
+				continue
+			}
+		}
+
 		// Filter out pull request if it does not contain at least one of the desired labels
 		if len(request.Source.Labels) > 0 {
 			labelFound := false

check_test.go

@@ -262,6 +262,36 @@ func TestCheck(t *testing.T) {
 				resource.NewVersion(testPullRequests[10]),
 			},
 		},
+
+		{
+			description: "check correctly ignores PRs that do not match the head branch filter",
+			source: resource.Source{
+				Repository:   "itsdalmo/test-repository",
+				AccessToken:  "oauthtoken",
+				HeadBranches: "pr8*",
+			},
+			version:      resource.Version{},
+			pullRequests: testPullRequests,
+			files:        [][]string{},
+			expected: resource.CheckResponse{
+				resource.NewVersion(testPullRequests[7]),
+			},
+		},
+
+		{
+			description: "check correctly ignores PRs that do match the ignore head branch filter",
+			source: resource.Source{
+				Repository:         "itsdalmo/test-repository",
+				AccessToken:        "oauthtoken",
+				IgnoreHeadBranches: "pr2*",
+			},
+			version:      resource.Version{},
+			pullRequests: testPullRequests,
+			files:        [][]string{},
+			expected: resource.CheckResponse{
+				resource.NewVersion(testPullRequests[2]),
+			},
+		},
 	}
 
 	for _, tc := range tests {

e2e/e2e_test.go

@@ -173,6 +173,68 @@ func TestCheckE2E(t *testing.T) {
 				resource.Version{PR: targetPullRequestID, Commit: targetCommitID, CommittedDate: targetDateTime},
 			},
 		},
+
+		{
+			description: "check returns latest PR that matches the head branch filter",
+			source: resource.Source{
+				Repository:    "itsdalmo/test-repository",
+				AccessToken:   os.Getenv("GITHUB_ACCESS_TOKEN"),
+				V3Endpoint:    "https://api.github.com/",
+				V4Endpoint:    "https://api.github.com/graphql",
+				HeadBranches:  "my*",
+				DisableCISkip: true,
+			},
+			version: resource.Version{},
+			expected: resource.CheckResponse{
+				resource.Version{PR: targetPullRequestID, Commit: targetCommitID, CommittedDate: targetDateTime},
+			},
+		},
+
+		{
+			description: "check works when head branch filter doesn't match any PRs",
+			source: resource.Source{
+				Repository:    "itsdalmo/test-repository",
+				AccessToken:   os.Getenv("GITHUB_ACCESS_TOKEN"),
+				V3Endpoint:    "https://api.github.com/",
+				V4Endpoint:    "https://api.github.com/graphql",
+				HeadBranches:  "feature/*",
+				DisableCISkip: true,
+			},
+			version:  resource.Version{},
+			expected: resource.CheckResponse(nil),
+		},
+
+		{
+			description: "check returns latest PR that matches the ignore head branch filter",
+			source: resource.Source{
+				Repository:         "itsdalmo/test-repository",
+				AccessToken:        os.Getenv("GITHUB_ACCESS_TOKEN"),
+				V3Endpoint:         "https://api.github.com/",
+				V4Endpoint:         "https://api.github.com/graphql",
+				IgnoreHeadBranches: "test*",
+				DisableCISkip:      true,
+			},
+			version: resource.Version{},
+			expected: resource.CheckResponse{
+				resource.Version{PR: targetPullRequestID, Commit: targetCommitID, CommittedDate: targetDateTime},
+			},
+		},
+
+		{
+			description: "check works when ignore head branch filter doesn't match any PRs",
+			source: resource.Source{
+				Repository:         "itsdalmo/test-repository",
+				AccessToken:        os.Getenv("GITHUB_ACCESS_TOKEN"),
+				V3Endpoint:         "https://api.github.com/",
+				V4Endpoint:         "https://api.github.com/graphql",
+				IgnoreHeadBranches: "feature/*",
+				DisableCISkip:      true,
+			},
+			version: resource.Version{},
+			expected: resource.CheckResponse{
+				resource.Version{PR: developPullRequestID, Commit: developCommitID, CommittedDate: developDateTime},
+			},
+		},
 	}
 
 	for _, tc := range tests {

models.go

@@ -24,6 +24,8 @@ type Source struct {
 	IgnoreDrafts            bool                        `json:"ignore_drafts"`
 	GitCryptKey             string                      `json:"git_crypt_key"`
 	BaseBranch              string                      `json:"base_branch"`
+	HeadBranches            string                      `json:"head_branches"`
+	IgnoreHeadBranches      string                      `json:"ignore_head_branches"`
 	RequiredReviewApprovals int                         `json:"required_review_approvals"`
 	Labels                  []string                    `json:"labels"`
 	States                  []githubv4.PullRequestState `json:"states"`