feat: make action runs available in api (#7699)

## Summary

Inspired by https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-repository and https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#get-a-workflow-run

## 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

- [ ] I do not want this change to show in the release notes.
- [x] I want the title to show in the release notes with a link to this pull request.
- [ ] I want the content of the `release-notes/<pull request number>.md` to be be used for the release notes instead of the title.

<!--start release-notes-assistant-->

## Release notes
<!--URL:https://codeberg.org/forgejo/forgejo-->
- Features
  - [PR](https://codeberg.org/forgejo/forgejo/pulls/7699): <!--number 7699 --><!--line 0 --><!--description bWFrZSBhY3Rpb24gcnVucyBhdmFpbGFibGUgaW4gYXBp-->make action runs available in api<!--description-->
<!--end release-notes-assistant-->

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/7699
Reviewed-by: Earl Warren <[email protected]>
Co-authored-by: klausfyhn <[email protected]>
Co-committed-by: klausfyhn <[email protected]>

Author: klausfyhn

models/actions/run_job_list.go

@@ -54,6 +54,8 @@ type FindRunJobOptions struct {
 	CommitSHA     string
 	Statuses      []Status
 	UpdatedBefore timeutil.TimeStamp
+	Events        []string // []webhook_module.HookEventType
+	RunNumber     int64
 }
 
 func (opts FindRunJobOptions) ToConds() builder.Cond {
@@ -76,5 +78,11 @@ 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/status.go

@@ -34,6 +34,15 @@ var statusNames = map[Status]string{
 	StatusBlocked:   "blocked",
 }
 
+var nameToStatus = make(map[string]Status, len(statusNames))
+
+func init() {
+	// Populate name to status lookup map
+	for status, name := range statusNames {
+		nameToStatus[name] = status
+	}
+}
+
 // String returns the string name of the Status
 func (s Status) String() string {
 	return statusNames[s]
@@ -102,3 +111,8 @@ func (s Status) AsResult() runnerv1.Result {
 	}
 	return runnerv1.Result_RESULT_UNSPECIFIED
 }
+
+func StatusFromString(name string) (Status, bool) {
+	status, exists := nameToStatus[name]
+	return status, exists
+}

models/fixtures/action_run.yml

@@ -471,3 +471,64 @@
   need_approval: 0
   approved_by: 0
   event_payload: '{"head_commit":{"id":"5f22f7d0d95d614d25a5b68592adb345a4b5c7fd"}}'
+
+
+# GET action run(s) test
+-
+  id: 892
+  title: "successful push run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "success.yaml"
+  index: 1
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  event: "push"
+  is_fork_pull_request: 0
+  status: 1 # success
+  started: 1683636528
+  stopped: 1683636626
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
+
+-
+  id: 893
+  title: "failed pull_request run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "failed.yaml"
+  index: 2
+  trigger_user_id: 2
+  ref: "refs/heads/bugfix-1"
+  commit_sha: "35c5cddfc19397501ec8f4f7bb808a7c8f04445f"
+  event: "pull_request"
+  is_fork_pull_request: 0
+  status: 2 # failure
+  started: 1683636528
+  stopped: 1683636626
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0
+
+-
+  id: 894
+  title: "running workflow_dispatch run"
+  repo_id: 63
+  owner_id: 2
+  workflow_id: "running.yaml"
+  index: 3
+  trigger_user_id: 2
+  ref: "refs/heads/main"
+  commit_sha: "97f29ee599c373c729132a5c46a046978311e0ee"
+  event: "workflow_dispatch"
+  is_fork_pull_request: 0
+  status: 6 # running
+  started: 1683636528
+  created: 1683636108
+  updated: 1683636626
+  need_approval: 0
+  approved_by: 0

models/fixtures/repo_unit.yml

@@ -795,3 +795,10 @@
   type: 10
   config: "{}"
   created_unix: 946684810
+
+-
+  id: 115
+  repo_id: 63
+  type: 10
+  config: "{}"
+  created_unix: 946684810

models/fixtures/repository.yml

@@ -1889,3 +1889,35 @@
   is_fsck_enabled: true
   close_issues_via_commit_in_any_branch: false
   topics: '[]'
+
+-
+  id: 63
+  owner_id: 2
+  owner_name: user2
+  lower_name: test_action_run_search
+  name: test_action_run_search
+  default_branch: main
+  num_watches: 0
+  num_stars: 0
+  num_forks: 0
+  num_issues: 0
+  num_closed_issues: 0
+  num_pulls: 0
+  num_closed_pulls: 0
+  num_milestones: 0
+  num_closed_milestones: 0
+  num_projects: 0
+  num_closed_projects: 0
+  is_private: true
+  is_empty: false
+  is_archived: false
+  is_mirror: false
+  status: 0
+  is_fork: false
+  fork_id: 0
+  is_template: false
+  template_id: 0
+  size: 0
+  is_fsck_enabled: true
+  close_issues_via_commit_in_any_branch: false
+  topics: '[]'

models/fixtures/user.yml

@@ -70,7 +70,7 @@
   num_followers: 2
   num_following: 1
   num_stars: 2
-  num_repos: 17
+  num_repos: 18
   num_teams: 0
   num_members: 0
   visibility: 0

modules/structs/repo_actions.go

@@ -32,3 +32,23 @@ type ActionTaskResponse struct {
 	Entries    []*ActionTask `json:"workflow_runs"`
 	TotalCount int64         `json:"total_count"`
 }
+
+// ActionRun represents an ActionRun
+type ActionRun struct {
+	ID              int64  `json:"id"`
+	Name            string `json:"name"`
+	RunNumber       int64  `json:"run_number"`
+	Event           string `json:"event"`
+	Status          string `json:"status"`
+	HeadBranch      string `json:"head_branch"`
+	HeadSHA         string `json:"head_sha"`
+	WorkflowID      string `json:"workflow_id"`
+	URL             string `json:"url"`
+	TriggeringActor *User  `json:"triggering_actor"`
+}
+
+// ListActionRunResponse return a list of ActionRun
+type ListActionRunResponse struct {
+	Entries    []*ActionRun `json:"workflow_runs"`
+	TotalCount int64        `json:"total_count"`
+}

routers/api/v1/api.go

@@ -1172,6 +1172,10 @@ func Routes() *web.Route {
 				}, reqToken(), reqAdmin())
 				m.Group("/actions", func() {
 					m.Get("/tasks", repo.ListActionTasks)
+					m.Group("/runs", func() {
+						m.Get("", repo.ListActionRuns)
+						m.Get("/{run_id}", repo.GetActionRun)
+					})
 
 					m.Group("/workflows", func() {
 						m.Group("/{workflowname}", func() {

routers/api/v1/repo/action.go

@@ -5,6 +5,7 @@ package repo
 
 import (
 	"errors"
+	"fmt"
 	"net/http"
 
 	actions_model "forgejo.org/models/actions"
@@ -694,3 +695,160 @@ func DispatchWorkflow(ctx *context.APIContext) {
 		ctx.JSON(http.StatusNoContent, nil)
 	}
 }
+
+// ListActionRuns return a filtered list of ActionRun
+func ListActionRuns(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/actions/runs repository ListActionRuns
+	// ---
+	// summary: List a repository's action runs
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: page
+	//   in: query
+	//   description: page number of results to return (1-based)
+	//   type: integer
+	// - name: limit
+	//   in: query
+	//   description: page size of results, default maximum page size is 50
+	//   type: integer
+	// - name: event
+	//   in: query
+	//   description: Returns workflow run triggered by the specified events. For example, `push`, `pull_request` or `workflow_dispatch`.
+	//   type: array
+	//   items:
+	//     type: string
+	// - name: status
+	//   in: query
+	//   description: |
+	//     Returns workflow runs with the check run status or conclusion that is specified. For example, a conclusion can be success or a status can be in_progress. Only Forgejo Actions can set a status of waiting, pending, or requested.
+	//   type: array
+	//   items:
+	//     type: string
+	//     enum: [unknown, waiting, running, success, failure, cancelled, skipped, blocked]
+	// - name: run_number
+	//   in: query
+	//   description: |
+	//     Returns the workflow run associated with the run number.
+	//   type: integer
+	//   format: int64
+	// - name: head_sha
+	//   in: query
+	//   description: Only returns workflow runs that are associated with the specified head_sha.
+	//   type: string
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ActionRunList"
+	//   "400":
+	//     "$ref": "#/responses/error"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+
+	statusStrs := ctx.FormStrings("status")
+	statuses := make([]actions_model.Status, len(statusStrs))
+	for i, s := range statusStrs {
+		if status, exists := actions_model.StatusFromString(s); exists {
+			statuses[i] = status
+		} else {
+			ctx.Error(http.StatusBadRequest, "StatusFromString", fmt.Sprintf("unknown status: %s", s))
+			return
+		}
+	}
+
+	runs, total, err := db.FindAndCount[actions_model.ActionRun](ctx, &actions_model.FindRunJobOptions{
+		ListOptions: utils.GetListOptions(ctx),
+		OwnerID:     ctx.Repo.Owner.ID,
+		RepoID:      ctx.Repo.Repository.ID,
+		Events:      ctx.FormStrings("event"),
+		Statuses:    statuses,
+		RunNumber:   ctx.FormInt64("run_number"),
+		CommitSHA:   ctx.FormString("head_sha"),
+	})
+	if err != nil {
+		ctx.Error(http.StatusInternalServerError, "ListActionRuns", err)
+		return
+	}
+
+	res := new(api.ListActionRunResponse)
+	res.TotalCount = total
+
+	res.Entries = make([]*api.ActionRun, len(runs))
+	for i, r := range runs {
+		cr, err := convert.ToActionRun(ctx, r)
+		if err != nil {
+			ctx.Error(http.StatusInternalServerError, "ToActionRun", err)
+			return
+		}
+		res.Entries[i] = cr
+	}
+
+	ctx.JSON(http.StatusOK, &res)
+}
+
+// GetActionRun get one action instance
+func GetActionRun(ctx *context.APIContext) {
+	// swagger:operation GET /repos/{owner}/{repo}/actions/runs/{run_id} repository ActionRun
+	// ---
+	// summary: Get an action run
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: owner
+	//   in: path
+	//   description: owner of the repo
+	//   type: string
+	//   required: true
+	// - name: repo
+	//   in: path
+	//   description: name of the repo
+	//   type: string
+	//   required: true
+	// - name: run_id
+	//   in: path
+	//   description: id of the action run
+	//   type: integer
+	//   format: int64
+	//   required: true
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/ActionRun"
+	//   "400":
+	//     "$ref": "#/responses/error"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
+
+	run, err := actions_model.GetRunByID(ctx, ctx.ParamsInt64(":run_id"))
+	if err != nil {
+		if errors.Is(err, util.ErrNotExist) {
+			ctx.Error(http.StatusNotFound, "GetRunById", err)
+		} else {
+			ctx.Error(http.StatusInternalServerError, "GetRunByID", err)
+		}
+		return
+	}
+
+	if ctx.Repo.Repository.ID != run.RepoID {
+		ctx.Error(http.StatusNotFound, "GetRunById", util.ErrNotExist)
+		return
+	}
+
+	res, err := convert.ToActionRun(ctx, run)
+	if err != nil {
+		ctx.Error(http.StatusInternalServerError, "ToActionRun", err)
+		return
+	}
+
+	ctx.JSON(http.StatusOK, res)
+}

routers/api/v1/swagger/repo.go

@@ -455,3 +455,17 @@ type swaggerSyncForkInfo struct {
 	// in:body
 	Body []api.SyncForkInfo `json:"body"`
 }
+
+// ActionRunList
+// swagger:response ActionRunList
+type swaggerRepoActionRunList struct {
+	// in:body
+	Body api.ListActionRunResponse `json:"body"`
+}
+
+// ActionRun
+// swagger:response ActionRun
+type swaggerRepoActionRun struct {
+	// in:body
+	Body api.ActionRun `json:"body"`
+}