feat(api): add new /repos/{owner}/{repo}/actions/runs/{run_id}/cancel API endpoint (#12957)

This new API endpoint makes it possible to cancel action runs via the API. Previously this was only natively possible through the UI, the same `CancelRun` func has been reused for this feature.

### Tests for Go changes

- 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 ran...
  - [x] `make pr-go` before pushing

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

## Release notes
<!--URL:https://codeberg.org/forgejo/forgejo-->
- Features
  - [PR](https://codeberg.org/forgejo/forgejo/pulls/12957): <!--number 12957 --><!--line 0 --><!--description ZmVhdChhcGkpOiBhZGQgbmV3IGAvcmVwb3Mve293bmVyfS97cmVwb30vYWN0aW9ucy9ydW5zL3tydW5faWR9L2NhbmNlbGAgQVBJIGVuZHBvaW50-->feat(api): add new `/repos/{owner}/{repo}/actions/runs/{run_id}/cancel` API endpoint<!--description-->
<!--end release-notes-assistant-->

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/12957
Reviewed-by: limiting-factor <limiting-factor@noreply.codeberg.org>
Reviewed-by: Andreas Ahlenstorf <aahlenst@noreply.codeberg.org>
Reviewed-by: Mathieu Fenniak <mfenniak@noreply.codeberg.org>

routers/api/v1/api.go

@@ -1256,6 +1256,7 @@ func Routes() *web.Route {
 						m.Get("", repo.ListActionRuns)
 						m.Get("/{run_id}", repo.GetActionRun)
 						m.Delete("/{run_id}", reqToken(), reqAdmin(unit.TypeActions), repo.DeleteActionRun)
+						m.Post("/{run_id}/cancel", reqToken(), reqRepoWriter(unit.TypeActions), repo.CancelActionRun)
 						m.Get("/{run_id}/jobs", repo.ListActionRunJobs)
 						m.Get("/{run_id}/logs", repo.GetActionRunLogs)
 						m.Get("/{run_id}/artifacts", repo.ListActionRunArtifacts)

routers/api/v1/repo/action.go

@@ -1095,6 +1095,67 @@ func DeleteActionRun(ctx *context.APIContext) {
 	ctx.Status(http.StatusNoContent)
 }
 
+// CancelActionRun cancels a pending or running workflow run.
+func CancelActionRun(ctx *context.APIContext) {
+	// swagger:operation POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel repository CancelActionRun
+	// ---
+	// summary: Cancel a pending or running workflow run.
+	// description: >
+	//   Cancel a particular workflow run. Pending or running jobs of the run are cancelled. A run that has
+	//   already finished, whether cancelled, failed, skipped or succeeded, is left unchanged.
+	//   In both cases the endpoint responds with HTTP 204.
+	// 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 workflow run
+	//   type: integer
+	//   format: int64
+	//   required: true
+	// responses:
+	//   "204":
+	//     description: Workflow run has been cancelled
+	//   "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)
+			return
+		}
+
+		ctx.Error(http.StatusInternalServerError, "GetRunByID", err)
+		return
+	}
+
+	if ctx.Repo.Repository.ID != run.RepoID {
+		ctx.Error(http.StatusNotFound, "GetRunById", util.ErrNotExist)
+		return
+	}
+
+	err = actions_service.CancelRun(ctx, run)
+	if err != nil {
+		ctx.Error(http.StatusInternalServerError, "CancelRun", err)
+		return
+	}
+
+	ctx.Status(http.StatusNoContent)
+}
+
 // ListActionRunJobs return a filtered list of jobs that belong to a single workflow run
 func ListActionRunJobs(ctx *context.APIContext) {
 	// swagger:operation GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs repository ListActionRunJobs

templates/swagger/v1_json.tmpl

@@ -6422,6 +6422,54 @@
         }
       }
     },
+    "/repos/{owner}/{repo}/actions/runs/{run_id}/cancel": {
+      "post": {
+        "description": "Cancel a particular workflow run. Pending or running jobs of the run are cancelled. A run that has already finished, whether cancelled, failed, skipped or succeeded, is left unchanged. In both cases the endpoint responds with HTTP 204.\n",
+        "produces": [
+          "application/json"
+        ],
+        "tags": [
+          "repository"
+        ],
+        "summary": "Cancel a pending or running workflow run.",
+        "operationId": "CancelActionRun",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "owner of the repo",
+            "name": "owner",
+            "in": "path",
+            "required": true
+          },
+          {
+            "type": "string",
+            "description": "name of the repo",
+            "name": "repo",
+            "in": "path",
+            "required": true
+          },
+          {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the workflow run",
+            "name": "run_id",
+            "in": "path",
+            "required": true
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Workflow run has been cancelled"
+          },
+          "403": {
+            "$ref": "#/responses/forbidden"
+          },
+          "404": {
+            "$ref": "#/responses/notFound"
+          }
+        }
+      }
+    },
     "/repos/{owner}/{repo}/actions/runs/{run_id}/jobs": {
       "get": {
         "produces": [

tests/integration/api_repo_actions_test.go

@@ -786,6 +786,124 @@ func TestActionsAPIDeleteActionRun(t *testing.T) {
 	})
 }
 
+func TestActionsAPICancelActionRun(t *testing.T) {
+	t.Run("Run cancelled", func(t *testing.T) {
+		defer unittest.OverrideFixtures("tests/integration/fixtures/TestActionsAPICancelActionRun")()
+		defer tests.PrepareTestEnv(t)()
+
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		repo1 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 1, OwnerID: user2.ID})
+		session := loginUser(t, user2.Name)
+		writeToken := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeWriteRepository)
+
+		run := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: 35011})
+		job := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRunJob{ID: 48011, RunID: run.ID})
+		assert.False(t, run.Status.IsDone())
+		assert.False(t, job.Status.IsDone())
+
+		requestURL := fmt.Sprintf("/api/v1/repos/%s/actions/runs/%d/cancel", repo1.FullName(), run.ID)
+		request := NewRequest(t, "POST", requestURL)
+		request.AddTokenAuth(writeToken)
+		MakeRequest(t, request, http.StatusNoContent)
+
+		run = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: run.ID})
+		assert.Equal(t, actions_model.StatusCancelled, run.Status)
+		job = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRunJob{ID: job.ID})
+		assert.Equal(t, actions_model.StatusCancelled, job.Status)
+	})
+
+	t.Run("Already finished run is left unchanged", func(t *testing.T) {
+		defer unittest.OverrideFixtures("tests/integration/fixtures/TestActionsAPICancelActionRun")()
+		defer tests.PrepareTestEnv(t)()
+
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		repo1 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 1, OwnerID: user2.ID})
+		session := loginUser(t, user2.Name)
+		writeToken := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeWriteRepository)
+
+		run := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: 35012})
+		require.Equal(t, actions_model.StatusSuccess, run.Status)
+
+		requestURL := fmt.Sprintf("/api/v1/repos/%s/actions/runs/%d/cancel", repo1.FullName(), run.ID)
+		request := NewRequest(t, "POST", requestURL)
+		request.AddTokenAuth(writeToken)
+		MakeRequest(t, request, http.StatusNoContent)
+
+		// The finished run keeps its status.
+		run = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: run.ID})
+		assert.Equal(t, actions_model.StatusSuccess, run.Status)
+	})
+
+	t.Run("Not found if run does not belong to repository", func(t *testing.T) {
+		defer unittest.OverrideFixtures("tests/integration/fixtures/TestActionsAPICancelActionRun")()
+		defer tests.PrepareTestEnv(t)()
+
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		repo62 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 62, OwnerID: user2.ID})
+		session := loginUser(t, user2.Name)
+		writeToken := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeWriteRepository)
+
+		run := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: 35011})
+		assert.Equal(t, actions_model.StatusRunning, run.Status)
+
+		requestURL := fmt.Sprintf("/api/v1/repos/%s/actions/runs/%d/cancel", repo62.FullName(), run.ID)
+		request := NewRequest(t, "POST", requestURL)
+		request.AddTokenAuth(writeToken)
+		MakeRequest(t, request, http.StatusNotFound)
+
+		// Verify that the run was not cancelled.
+		run = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: run.ID})
+		assert.Equal(t, actions_model.StatusRunning, run.Status)
+	})
+
+	t.Run("Not found if run does not exist", func(t *testing.T) {
+		defer tests.PrepareTestEnv(t)()
+
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		repo1 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 1, OwnerID: user2.ID})
+		session := loginUser(t, user2.Name)
+		writeToken := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeWriteRepository)
+
+		unittest.AssertNotExistsBean(t, &actions_model.ActionRun{ID: 260871})
+
+		requestURL := fmt.Sprintf("/api/v1/repos/%s/actions/runs/260871/cancel", repo1.FullName())
+		request := NewRequest(t, "POST", requestURL)
+		request.AddTokenAuth(writeToken)
+		MakeRequest(t, request, http.StatusNotFound)
+	})
+
+	t.Run("Run cancellation requires write token", func(t *testing.T) {
+		defer unittest.OverrideFixtures("tests/integration/fixtures/TestActionsAPICancelActionRun")()
+		defer tests.PrepareTestEnv(t)()
+
+		user2 := unittest.AssertExistsAndLoadBean(t, &user_model.User{ID: 2})
+		repo1 := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 1, OwnerID: user2.ID})
+		session := loginUser(t, user2.Name)
+		readToken := getTokenForLoggedInUser(t, session, auth_model.AccessTokenScopeReadRepository)
+
+		run := unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: 35011})
+		assert.Equal(t, actions_model.StatusRunning, run.Status)
+
+		requestURL := fmt.Sprintf("/api/v1/repos/%s/actions/runs/%d/cancel", repo1.FullName(), run.ID)
+		request := NewRequest(t, "POST", requestURL)
+		request.AddTokenAuth(readToken)
+		response := MakeRequest(t, request, http.StatusForbidden)
+
+		type errorResponse struct {
+			Message string `json:"message"`
+		}
+
+		var errorMessage *errorResponse
+		DecodeJSON(t, response, &errorMessage)
+
+		assert.Equal(t, "token does not have at least one of required scope(s): [write:repository]", errorMessage.Message)
+
+		// Verify that the run was not cancelled.
+		run = unittest.AssertExistsAndLoadBean(t, &actions_model.ActionRun{ID: run.ID})
+		assert.Equal(t, actions_model.StatusRunning, run.Status)
+	})
+}
+
 func TestActionsAPIListActionRunJobs(t *testing.T) {
 	defer tests.PrepareTestEnv(t)()
 

tests/integration/fixtures/TestActionsAPICancelActionRun/action_run.yml

@@ -0,0 +1,9 @@
+- id: 35011
+  repo_id: 1
+  owner_id: 2
+  status: 6 # StatusRunning
+
+- id: 35012
+  repo_id: 1
+  owner_id: 2
+  status: 1 # StatusSuccess

tests/integration/fixtures/TestActionsAPICancelActionRun/action_run_job.yml

@@ -0,0 +1,8 @@
+- id: 48011
+  run_id: 35011
+  task_id: 72011
+  status: 6 # StatusRunning
+
+- id: 48012
+  run_id: 35012
+  status: 1 # StatusSuccess

tests/integration/fixtures/TestActionsAPICancelActionRun/action_task.yml

@@ -0,0 +1,6 @@
+- id: 72011
+  job_id: 48011
+  log_filename: cancel-test/72/011.log
+  log_in_storage: false
+  status: 6 # StatusRunning
+  runner_id: 1