From c531b8f020cd97d2211841b7b72ec25a4441dbd3 Mon Sep 17 00:00:00 2001
From: klausfyhn <klausfyhn@noreply.codeberg.org>
Date: Tue, 25 Mar 2025 21:22:32 +0000
Subject: [PATCH] feat(api): return `run_number` in workflow dispatch (#7286)

- This is a follow up on #7193 and resolves #6312.
- The ID by itself is not very useful, so also return the index of the workflow run.

Co-authored-by: Klaus Fyhn <klausfyhn@gmail.com>
Co-authored-by: Klaus Fyhn <klfj@mir-robots.com>
Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/7286
Reviewed-by: Gusted <gusted@noreply.codeberg.org>
Co-authored-by: klausfyhn <klausfyhn@noreply.codeberg.org>
Co-committed-by: klausfyhn <klausfyhn@noreply.codeberg.org>
---
 modules/structs/workflow.go                |  2 +
 routers/api/v1/repo/action.go              |  7 ++-
 templates/swagger/v1_json.tmpl             |  9 ++++
 tests/integration/api_repo_actions_test.go | 60 ++++++++++++++++++++++
 4 files changed, 76 insertions(+), 2 deletions(-)

diff --git a/modules/structs/workflow.go b/modules/structs/workflow.go
index f8f1e5a7a5..704ed0e65b 100644
--- a/modules/structs/workflow.go
+++ b/modules/structs/workflow.go
@@ -22,6 +22,8 @@ type DispatchWorkflowOption struct {
 type DispatchWorkflowRun struct {
 	// the workflow run id
 	ID int64 `json:"id"`
+	// a unique number for each run of a repository
+	RunNumber int64 `json:"run_number"`
 	// the jobs name
 	Jobs []string `json:"jobs"`
 }
diff --git a/routers/api/v1/repo/action.go b/routers/api/v1/repo/action.go
index a2cc70f4d7..2ce9ad253c 100644
--- a/routers/api/v1/repo/action.go
+++ b/routers/api/v1/repo/action.go
@@ -640,6 +640,8 @@ func DispatchWorkflow(ctx *context.APIContext) {
 	//   schema:
 	//     "$ref": "#/definitions/DispatchWorkflowOption"
 	// responses:
+	//   "201":
+	//     "$ref": "#/responses/DispatchWorkflowRun"
 	//   "204":
 	//     "$ref": "#/responses/empty"
 	//   "404":
@@ -681,8 +683,9 @@ func DispatchWorkflow(ctx *context.APIContext) {
 	}
 
 	workflowRun := &api.DispatchWorkflowRun{
-		ID:   run.ID,
-		Jobs: jobs,
+		ID:        run.ID,
+		RunNumber: run.Index,
+		Jobs:      jobs,
 	}
 
 	if opt.ReturnRunInfo {
diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl
index 4cc8f7eddd..cc95fc488d 100644
--- a/templates/swagger/v1_json.tmpl
+++ b/templates/swagger/v1_json.tmpl
@@ -5414,6 +5414,9 @@
           }
         ],
         "responses": {
+          "201": {
+            "$ref": "#/responses/DispatchWorkflowRun"
+          },
           "204": {
             "$ref": "#/responses/empty"
           },
@@ -23193,6 +23196,12 @@
             "type": "string"
           },
           "x-go-name": "Jobs"
+        },
+        "run_number": {
+          "description": "a unique number for each run of a repository",
+          "type": "integer",
+          "format": "int64",
+          "x-go-name": "RunNumber"
         }
       },
       "x-go-package": "code.gitea.io/gitea/modules/structs"
diff --git a/tests/integration/api_repo_actions_test.go b/tests/integration/api_repo_actions_test.go
index ec8bb501e3..302f0c93cb 100644
--- a/tests/integration/api_repo_actions_test.go
+++ b/tests/integration/api_repo_actions_test.go
@@ -4,15 +4,20 @@
 package integration
 
 import (
+	"fmt"
 	"net/http"
+	"net/url"
+	"strings"
 	"testing"
 
 	actions_model "code.gitea.io/gitea/models/actions"
 	auth_model "code.gitea.io/gitea/models/auth"
 	repo_model "code.gitea.io/gitea/models/repo"
+	unit_model "code.gitea.io/gitea/models/unit"
 	"code.gitea.io/gitea/models/unittest"
 	user_model "code.gitea.io/gitea/models/user"
 	api "code.gitea.io/gitea/modules/structs"
+	files_service "code.gitea.io/gitea/services/repository/files"
 	"code.gitea.io/gitea/tests"
 
 	"github.com/stretchr/testify/assert"
@@ -41,3 +46,58 @@ func TestAPISearchActionJobs_RepoRunner(t *testing.T) {
 	assert.Len(t, jobs, 1)
 	assert.EqualValues(t, job.ID, jobs[0].ID)
 }
+
+func TestAPIWorkflowDispatchReturnInfo(t *testing.T) {
+	onGiteaRun(t, func(t *testing.T, u *url.URL) {
+		workflowName := "dispatch.yml"
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		token := getUserToken(t, user2.LowerName, auth_model.AccessTokenScopeWriteRepository)
+
+		// create the repo
+		repo, _, f := tests.CreateDeclarativeRepo(t, user2, "api-repo-workflow-dispatch",
+			[]unit_model.Type{unit_model.TypeActions}, nil,
+			[]*files_service.ChangeRepoFile{
+				{
+					Operation: "create",
+					TreePath:  fmt.Sprintf(".forgejo/workflows/%s", workflowName),
+					ContentReader: strings.NewReader(`name: WD
+on: [workflow-dispatch]
+jobs:
+  t1:
+    runs-on: docker
+    steps:
+      - run: echo "test 1"
+  t2:
+    runs-on: docker
+    steps:
+      - run: echo "test 2"
+`,
+					),
+				},
+			},
+		)
+		defer f()
+
+		req := NewRequestWithJSON(
+			t,
+			http.MethodPost,
+			fmt.Sprintf(
+				"/api/v1/repos/%s/%s/actions/workflows/%s/dispatches",
+				repo.OwnerName, repo.Name, workflowName,
+			),
+			&api.DispatchWorkflowOption{
+				Ref:           repo.DefaultBranch,
+				ReturnRunInfo: true,
+			},
+		)
+		req.AddTokenAuth(token)
+
+		res := MakeRequest(t, req, http.StatusCreated)
+		run := new(api.DispatchWorkflowRun)
+		DecodeJSON(t, res, run)
+
+		assert.NotZero(t, run.ID)
+		assert.NotZero(t, run.RunNumber)
+		assert.Len(t, run.Jobs, 2)
+	})
+}