owen/gitocean
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: revise runner REST API endpoints (#10450)

Browse Source 
In https://codeberg.org/forgejo/forgejo/pulls/9409, REST API endpoints were added to manage runners. The REST API endpoints were modelled after GitHub's REST API. That comes at the cost of introducing methods and fields that Forgejo does not and is unlikely to support in the future, like label IDs or label types. But Forgejo would have to maintain them for a very long time.

The introduced endpoints have been revised and aligned with existing Forgejo REST API endpoints:

* POST for `/registration-token` has been removed because it was only an alias of GET.
* `/runners` returns a list of `ActionRunner` instead of a wrapper object. `total_count` was replaced with the header `x-total-count` that is used throughout Forgejo.
* `status` in `ActionRunner` was converted to an enum that is documented.
* `busy` in `ActionRunner` was combined with `status`. A single enum is easier to extend and consume.
* `labels` in `ActionRunner` was converted to a list of strings to match existing Forgejo REST API endpoints.
* `ephemeral` has been removed from `ActionRunner` because ephemeral runners have not been merged, yet.
*  `ActionRunner` received a number of new fields: `uuid`, `version`, `description`, `owner_id`, and `repo_id`.

In addition to those structural changes, the test coverage was enhanced and the API documentation polished.

## 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...
  - [x] 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.
- [ ] 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.

Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/10450
Reviewed-by: Mathieu Fenniak <mfenniak@noreply.codeberg.org>
Co-authored-by: Andreas Ahlenstorf <andreas@ahlenstorf.ch>
Co-committed-by: Andreas Ahlenstorf <andreas@ahlenstorf.ch>
This commit is contained in:
Andreas Ahlenstorf
2025-12-21 17:21:02 +01:00
committed by Mathieu Fenniak
parent 81baf75636
commit ddd4cf0d28
26 changed files with 971 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/swagger/v1_json.tmpl
Generated
+72 -171
View File
@@ -319,11 +319,11 @@
"tags": [
"admin"
],
"summary": "Get all runners",
"summary": "Get all runners, no matter whether they are global runners or scoped to an organization, user, or repository",
"operationId": "getAdminRunners",
"responses": {
"200": {
"$ref": "#/definitions/ActionRunnersResponse"
"$ref": "#/responses/ActionRunnerList"
},
"400": {
"$ref": "#/responses/error"
@@ -334,23 +334,6 @@
}
}
},
"/admin/actions/runners/registration-token": {
"post": {
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "Get a global actions runner registration token",
"operationId": "adminCreateRunnerRegistrationToken",
"responses": {
"200": {
"$ref": "#/responses/RegistrationToken"
}
}
}
},
"/admin/actions/runners/{runner_id}": {
"get": {
"produces": [
@@ -359,12 +342,12 @@
"tags": [
"admin"
],
"summary": "Get a global runner",
"summary": "Get a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository",
"operationId": "getAdminRunner",
"parameters": [
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -372,7 +355,7 @@
],
"responses": {
"200": {
"$ref": "#/definitions/ActionRunner"
"$ref": "#/responses/ActionRunner"
},
"400": {
"$ref": "#/responses/error"
@@ -389,12 +372,12 @@
"tags": [
"admin"
],
"summary": "Delete a global runner",
"summary": "Delete a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository",
"operationId": "deleteAdminRunner",
"parameters": [
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -1245,7 +1228,7 @@
"tags": [
"admin"
],
"summary": "Search action jobs according filter conditions",
"summary": "Search action jobs according to filter conditions",
"operationId": "adminSearchRunJobs",
"parameters": [
{
@@ -1273,7 +1256,7 @@
"tags": [
"admin"
],
"summary": "Get a global actions runner registration token",
"summary": "Get a runner registration token for registering global runners",
"operationId": "adminGetRunnerRegistrationToken",
"responses": {
"200": {
@@ -2635,7 +2618,7 @@
"tags": [
"organization"
],
"summary": "Get org-level runners",
"summary": "Get the organization's runners",
"operationId": "getOrgRunners",
"parameters": [
{
@@ -2648,7 +2631,7 @@
],
"responses": {
"200": {
"$ref": "#/definitions/ActionRunnersResponse"
"$ref": "#/responses/ActionRunnerList"
},
"400": {
"$ref": "#/responses/error"
@@ -2702,7 +2685,7 @@
"tags": [
"organization"
],
"summary": "Get an organization's actions runner registration token",
"summary": "Get the organization's runner registration token",
"operationId": "orgGetRunnerRegistrationToken",
"parameters": [
{
@@ -2718,30 +2701,6 @@
"$ref": "#/responses/RegistrationToken"
}
}
},
"post": {
"produces": [
"application/json"
],
"tags": [
"organization"
],
"summary": "Get an organization's actions runner registration token",
"operationId": "orgCreateRunnerRegistrationToken",
"parameters": [
{
"type": "string",
"description": "name of the organization",
"name": "org",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/RegistrationToken"
}
}
}
},
"/orgs/{org}/actions/runners/{runner_id}": {
@@ -2752,7 +2711,7 @@
"tags": [
"organization"
],
"summary": "Get an org-level runner",
"summary": "Get a particular runner that belongs to the organization",
"operationId": "getOrgRunner",
"parameters": [
{
@@ -2764,7 +2723,7 @@
},
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -2772,7 +2731,7 @@
],
"responses": {
"200": {
"$ref": "#/definitions/ActionRunner"
"$ref": "#/responses/ActionRunner"
},
"400": {
"$ref": "#/responses/error"
@@ -2789,7 +2748,7 @@
"tags": [
"organization"
],
"summary": "Delete an org-level runner",
"summary": "Delete a particular runner that belongs to the organization",
"operationId": "deleteOrgRunner",
"parameters": [
{
@@ -2801,7 +2760,7 @@
},
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -5333,7 +5292,7 @@
"tags": [
"repository"
],
"summary": "Get repo-level runners",
"summary": "Get runners belonging to the repository",
"operationId": "getRepoRunners",
"parameters": [
{
@@ -5353,7 +5312,7 @@
],
"responses": {
"200": {
"$ref": "#/definitions/ActionRunnersResponse"
"$ref": "#/responses/ActionRunnerList"
},
"400": {
"$ref": "#/responses/error"
@@ -5414,7 +5373,7 @@
"tags": [
"repository"
],
"summary": "Get a repository's actions runner registration token",
"summary": "Get a repository's runner registration token",
"operationId": "repoGetRunnerRegistrationToken",
"parameters": [
{
@@ -5437,37 +5396,6 @@
"$ref": "#/responses/RegistrationToken"
}
}
},
"post": {
"produces": [
"application/json"
],
"tags": [
"repository"
],
"summary": "Get a repository's actions runner registration token",
"operationId": "repoCreateRunnerRegistrationToken",
"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
}
],
"responses": {
"200": {
"$ref": "#/responses/RegistrationToken"
}
}
}
},
"/repos/{owner}/{repo}/actions/runners/{runner_id}": {
@@ -5478,7 +5406,7 @@
"tags": [
"repository"
],
"summary": "Get a repo-level runner",
"summary": "Get a particular runner that belongs to the repository",
"operationId": "getRepoRunner",
"parameters": [
{
@@ -5497,7 +5425,7 @@
},
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -5505,7 +5433,7 @@
],
"responses": {
"200": {
"$ref": "#/definitions/ActionRunner"
"$ref": "#/responses/ActionRunner"
},
"400": {
"$ref": "#/responses/error"
@@ -5522,7 +5450,7 @@
"tags": [
"repository"
],
"summary": "Delete a repo-level runner",
"summary": "Delete a particular runner that belongs to a repository",
"operationId": "deleteRepoRunner",
"parameters": [
{
@@ -5541,7 +5469,7 @@
},
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -18807,11 +18735,11 @@
"tags": [
"user"
],
"summary": "Get user-level runners",
"summary": "Get the user's runners",
"operationId": "getUserRunners",
"responses": {
"200": {
"$ref": "#/responses/ActionRunnersResponse"
"$ref": "#/responses/ActionRunnerList"
},
"400": {
"$ref": "#/responses/error"
@@ -18864,7 +18792,7 @@
"tags": [
"user"
],
"summary": "Get an user's actions runner registration token",
"summary": "Get the user's runner registration token",
"operationId": "userGetRunnerRegistrationToken",
"responses": {
"200": {
@@ -18877,24 +18805,6 @@
"$ref": "#/responses/forbidden"
}
}
},
"post": {
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "Get an user's actions runner registration token",
"operationId": "userCreateRunnerRegistrationToken",
"responses": {
"200": {
"$ref": "#/responses/RegistrationToken"
},
"401": {
"$ref": "#/responses/unauthorized"
}
}
}
},
"/user/actions/runners/{runner_id}": {
@@ -18905,12 +18815,12 @@
"tags": [
"user"
],
"summary": "Get an user-level runner",
"summary": "Get a particular runner that belongs to the user",
"operationId": "getUserRunner",
"parameters": [
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -18938,12 +18848,12 @@
"tags": [
"user"
],
"summary": "Delete an user-level runner",
"summary": "Delete a particular user-level runner",
"operationId": "deleteUserRunner",
"parameters": [
{
"type": "string",
"description": "id of the runner",
"description": "ID of the runner",
"name": "runner_id",
"in": "path",
"required": true
@@ -22181,76 +22091,64 @@
"x-go-package": "forgejo.org/modules/structs"
},
"ActionRunner": {
"description": "ActionRunner represents a Runner",
"description": "ActionRunner represents a runner",
"type": "object",
"properties": {
"busy": {
"type": "boolean",
"x-go-name": "Busy"
},
"ephemeral": {
"description": "currently unused as forgejo does not support ephemeral runners, but they are defined in gh api spec",
"type": "boolean",
"x-go-name": "Ephemeral"
"description": {
"description": "Description provides optional details about this runner.",
"type": "string",
"x-go-name": "Description"
},
"id": {
"description": "ID uniquely identifies this runner.",
"type": "integer",
"format": "int64",
"x-go-name": "ID"
},
"labels": {
"description": "Labels is a list of labels attached to this runner.",
"type": "array",
"items": {
"$ref": "#/definitions/ActionRunnerLabel"
"type": "string"
},
"x-go-name": "Labels"
},
"name": {
"description": "Name of the runner; not unique.",
"type": "string",
"x-go-name": "Name"
},
"owner_id": {
"description": "OwnerID is the identifier of the user or organization this runner belongs to. O if the runner is owned by a\nrepository.",
"type": "integer",
"format": "int64",
"x-go-name": "OwnerID"
},
"repo_id": {
"description": "RepoID is the identifier of the repository this runner belongs to. 0 if the runner belongs to a user or\norganization.",
"type": "integer",
"format": "int64",
"x-go-name": "RepoID"
},
"status": {
"description": "Status indicates whether this runner is offline, or active, for example.",
"type": "string",
"enum": [
"offline",
"idle",
"active"
],
"x-go-name": "Status"
}
},
"x-go-package": "forgejo.org/modules/structs"
},
"ActionRunnerLabel": {
"description": "ActionRunnerLabel represents a Runner Label",
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"x-go-name": "ID"
},
"name": {
"uuid": {
"description": "UUID uniquely identifies this runner.",
"type": "string",
"x-go-name": "Name"
"x-go-name": "UUID"
},
"type": {
"version": {
"description": "Version is the self-reported version string of Forgejo Runner.",
"type": "string",
"x-go-name": "Type"
}
},
"x-go-package": "forgejo.org/modules/structs"
},
"ActionRunnersResponse": {
"description": "ActionRunnersResponse returns Runners",
"type": "object",
"properties": {
"runners": {
"type": "array",
"items": {
"$ref": "#/definitions/ActionRunner"
},
"x-go-name": "Entries"
},
"total_count": {
"type": "integer",
"format": "int64",
"x-go-name": "TotalCount"
"x-go-name": "Version"
}
},
"x-go-package": "forgejo.org/modules/structs"
@@ -29939,15 +29837,18 @@
}
},
"ActionRunner": {
"description": "ActionRunner represents a Runner",
"description": "ActionRunner represents a runner",
"schema": {
"$ref": "#/definitions/ActionRunner"
}
},
"ActionRunnersResponse": {
"description": "ActionRunnersResponse returns Runners",
"ActionRunnerList": {
"description": "ActionRunnerList is a list of Forgejo Action runners",
"schema": {
"$ref": "#/definitions/ActionRunnersResponse"
"type": "array",
"items": {
"$ref": "#/definitions/ActionRunner"
}
}
},
"ActionVariable": {