feat: filter action runs by Git reference (#11013)

Make it possible to filter action runs returned by `/api/v1/repos/andreas/test/actions/runs` by Git reference.

Resolves https://codeberg.org/forgejo/forgejo/issues/10874.

## Checklist

The [contributor guide](https://forgejo.org/docs/next/contributor/) contains information that will be helpful to first time contributors. There also are a few [conditions for merging Pull Requests in Forgejo repositories](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md). You are also welcome to join the [Forgejo development chatroom](https://matrix.to/#/#forgejo-development:matrix.org).

### Tests

- I added test coverage for Go changes...
  - [ ] in their respective `*_test.go` for unit tests.
  - [x] in the `tests/integration` directory if it involves interactions with a live Forgejo server.
- I added test coverage for JavaScript changes...
  - [ ] in `web_src/js/*.test.js` if it can be unit tested.
  - [ ] in `tests/e2e/*.test.e2e.js` if it requires interactions with a live Forgejo server (see also the [developer guide for JavaScript testing](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/tests/e2e/README.md#end-to-end-tests)).

### Documentation

- [ ] I created a pull request [to the documentation](https://codeberg.org/forgejo/docs) to explain to Forgejo users how to use this change.
- [x] I did not document these changes and I do not expect someone else to do it.

### Release notes

- [x] This change will be noticed by a Forgejo user or admin (feature, bug fix, performance, etc.). I suggest to include a release note for this change.
- [ ] This change is not visible to a Forgejo user or admin (refactor, dependency upgrade, etc.). I think there is no need to add a release note for this change.

*The decision if the pull request will be shown in the release notes is up to the mergers / release team.*

The content of the `release-notes/<pull request number>.md` file will serve as the basis for the release notes. If the file does not exist, the title of the pull request will be used instead.

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/11013
Reviewed-by: Mathieu Fenniak <mfenniak@noreply.codeberg.org>
Co-authored-by: Andreas Ahlenstorf <andreas@ahlenstorf.ch>
Co-committed-by: Andreas Ahlenstorf <andreas@ahlenstorf.ch>

models/actions/run_job_list.go

@@ -54,8 +54,6 @@ type FindRunJobOptions struct {
 	CommitSHA     string
 	Statuses      []Status
 	UpdatedBefore timeutil.TimeStamp
-	Events        []string // []webhook_module.HookEventType
-	RunNumber     int64
 }
 
 func (opts FindRunJobOptions) ToConds() builder.Cond {
@@ -78,11 +76,5 @@ func (opts FindRunJobOptions) ToConds() builder.Cond {
 	if opts.UpdatedBefore > 0 {
 		cond = cond.And(builder.Lt{"updated": opts.UpdatedBefore})
 	}
-	if len(opts.Events) > 0 {
-		cond = cond.And(builder.In("event", opts.Events))
-	}
-	if opts.RunNumber > 0 {
-		cond = cond.And(builder.Eq{"`index`": opts.RunNumber})
-	}
 	return cond
 }

models/actions/run_list.go

@@ -72,6 +72,9 @@ type FindRunOptions struct {
 	TriggerEvent  webhook_module.HookEventType
 	Approved      bool // not util.OptionalBool, it works only when it's true
 	Status        []Status
+	Events        []string // []webhook_module.HookEventType
+	RunNumber     int64
+	CommitSHA     string
 }
 
 func (opts FindRunOptions) ToConds() builder.Cond {
@@ -100,6 +103,15 @@ func (opts FindRunOptions) ToConds() builder.Cond {
 	if opts.TriggerEvent != "" {
 		cond = cond.And(builder.Eq{"trigger_event": opts.TriggerEvent})
 	}
+	if len(opts.Events) > 0 {
+		cond = cond.And(builder.In("event", opts.Events))
+	}
+	if opts.RunNumber > 0 {
+		cond = cond.And(builder.Eq{"`index`": opts.RunNumber})
+	}
+	if opts.CommitSHA != "" {
+		cond = cond.And(builder.Eq{"commit_sha": opts.CommitSHA})
+	}
 	return cond
 }
 

routers/api/v1/repo/action.go

@@ -882,6 +882,10 @@ func ListActionRuns(ctx *context.APIContext) {
 	//   in: query
 	//   description: Only returns workflow runs that are associated with the specified head_sha.
 	//   type: string
+	// - name: ref
+	//   in: query
+	//   description: Only return workflow runs that involve the given Git reference, for example, `refs/heads/main`.
+	//   type: string
 	// responses:
 	//   "200":
 	//     "$ref": "#/responses/ActionRunList"
@@ -901,14 +905,15 @@ func ListActionRuns(ctx *context.APIContext) {
 		}
 	}
 
-	runs, total, err := db.FindAndCount[actions_model.ActionRun](ctx, &actions_model.FindRunJobOptions{
+	runs, total, err := db.FindAndCount[actions_model.ActionRun](ctx, &actions_model.FindRunOptions{
 		ListOptions: utils.GetListOptions(ctx),
 		OwnerID:     ctx.Repo.Owner.ID,
 		RepoID:      ctx.Repo.Repository.ID,
 		Events:      ctx.FormStrings("event"),
-		Statuses:    statuses,
+		Status:      statuses,
 		RunNumber:   ctx.FormInt64("run_number"),
 		CommitSHA:   ctx.FormString("head_sha"),
+		Ref:         ctx.FormString("ref"),
 	})
 	if err != nil {
 		ctx.Error(http.StatusInternalServerError, "ListActionRuns", err)

templates/swagger/v1_json.tmpl

@@ -5781,6 +5781,12 @@
             "description": "Only returns workflow runs that are associated with the specified head_sha.",
             "name": "head_sha",
             "in": "query"
+          },
+          {
+            "type": "string",
+            "description": "Only return workflow runs that involve the given Git reference, for example, `refs/heads/main`.",
+            "name": "ref",
+            "in": "query"
           }
         ],
         "responses": {

tests/integration/api_repo_actions_test.go

@@ -271,6 +271,11 @@ func TestActionsAPIGetListActionRun(t *testing.T) {
 			query:       "?head_sha=97f29ee599c373c729132a5c46a046978311e0ee",
 			expectedIDs: []int64{892, 894},
 		},
+		{
+			name:        "Search for Git reference",
+			query:       "?ref=refs/heads/main",
+			expectedIDs: []int64{892, 894},
+		},
 	}
 
 	for _, tt := range testqueries {