From d158586ba5262bc5dbee7cce1bfd224a079a5f42 Mon Sep 17 00:00:00 2001 From: ecrupper Date: Wed, 30 Jul 2025 10:11:51 -0500 Subject: [PATCH] first steps --- docs/reference/api/admin/build.md | 190 ++++++++++++++--- docs/reference/api/admin/build_queue.md | 68 ++----- docs/reference/api/build/add.md | 105 ++++++++-- docs/reference/api/build/cancel.md | 93 ++++++++- docs/reference/api/build/get.md | 133 ------------ docs/reference/api/build/list.md | 259 ++++++++++++++++++++++++ docs/reference/api/build/logs.md | 2 +- docs/reference/api/build/remove.md | 2 +- docs/reference/api/build/restart.md | 97 +++++++-- docs/reference/api/build/update.md | 97 +++++++-- docs/reference/api/build/view.md | 196 ++++++++++++++---- docs/reference/api/dashboard/add.md | 6 +- docs/reference/api/dashboard/delete.md | 2 +- docs/reference/api/dashboard/get.md | 14 +- docs/reference/api/dashboard/list.md | 6 +- docs/reference/api/dashboard/update.md | 6 +- docs/reference/api/deployment/add.md | 79 +++++++- docs/reference/api/deployment/view.md | 121 ++++++++++- 18 files changed, 1132 insertions(+), 344 deletions(-) delete mode 100644 docs/reference/api/build/get.md create mode 100644 docs/reference/api/build/list.md diff --git a/docs/reference/api/admin/build.md b/docs/reference/api/admin/build.md index cfdedaa..49a3cbe 100644 --- a/docs/reference/api/admin/build.md +++ b/docs/reference/api/admin/build.md @@ -37,31 +37,94 @@ existing entry for the build. ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` @@ -80,30 +143,93 @@ curl \ ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` diff --git a/docs/reference/api/admin/build_queue.md b/docs/reference/api/admin/build_queue.md index b336b34..59cb093 100644 --- a/docs/reference/api/admin/build_queue.md +++ b/docs/reference/api/admin/build_queue.md @@ -44,58 +44,28 @@ curl \ ```json [ { - "id": 2, - "repo_id": 2, - "number": 1, - "parent": 1, - "event": "push", + "status": "running", + "number": 2142, + "created": 1740767426, + "full_name": "octocat/fav-repo" + }, + { "status": "pending", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" + "number": 2143, + "created": 1740767427, + "full_name": "octocat/fav-repo" }, { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "82823eb770b0", - "runtime": "", - "distribution": "" + "status": "pending", + "number": 2144, + "created": 1740767428, + "full_name": "octocat/fav-repo" + }, + { + "status": "pending", + "number": 2145, + "created": 1740767429, + "full_name": "octocat/fav-repo" } ] ``` \ No newline at end of file diff --git a/docs/reference/api/build/add.md b/docs/reference/api/build/add.md index 2ecc073..d8c533b 100644 --- a/docs/reference/api/build/add.md +++ b/docs/reference/api/build/add.md @@ -22,7 +22,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must have `admin` access to the repository in the SCM. ## Responses @@ -43,15 +43,15 @@ To authenticate to the API, please review the [authentication documentation](/do ```json { - "author": "Octokitty", + "author": "Octocat", "branch": "main", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", "clone": "https://github.com/github/octocat.git", "event": "push", "message": "First commit...", "ref": "refs/heads/main", - "sender": "Octokitty", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "sender": "Octocat", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat" } ``` @@ -71,30 +71,93 @@ curl \ ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` diff --git a/docs/reference/api/build/cancel.md b/docs/reference/api/build/cancel.md index c2741a5..ff97b5b 100644 --- a/docs/reference/api/build/cancel.md +++ b/docs/reference/api/build/cancel.md @@ -13,7 +13,7 @@ DELETE /api/v1/repos/:org/:repo/builds/:build/cancel ## Permissions -COMING SOON! +User must have `write` access to the repository in the SCM. ## Responses @@ -44,5 +44,94 @@ curl \ #### Response ```json - "canceled build github/octocat/36" +{ + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, + "event": "push", + "event_action": "", + "status": "canceled", + "error": "", + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, + "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, + "clone": "https://github.com/github/octocat.git", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", + "title": "push received from https://github.com/github/octocat", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", + "branch": "main", + "ref": "refs/heads/main", + "base_ref": "", + "head_ref": "", + "host": "worker1", + "runtime": "docker", + "distribution": "linux", + "approved_at": 0, + "approved_by": "" +} ``` diff --git a/docs/reference/api/build/get.md b/docs/reference/api/build/get.md deleted file mode 100644 index 736a348..0000000 --- a/docs/reference/api/build/get.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Get" -linkTitle: "Get" -description: > - Learn how to list builds. ---- - -## Endpoint - -``` -GET /api/v1/repos/:org/:repo/builds -``` - -## Parameters - -The following parameters are used to configure the endpoint: - -| Name | Description | -| ------ | -------------------- | -| `org` | name of organization | -| `repo` | name of repository | - -## Filters - -The following optional filters are available: - -| Name | Description | -| -------- | ----------------------------------------------------------------------- | -| `branch` | name of branch to filter to | -| `commit` | commit hash to filter to | -| `event` | name of event to filter to | -| `page` | page number for results (default 1) | -| `per_page` | number of results in a page (default 10, max 100) | -| `status` | name of status to filter to | -| `before` | return builds created before a certain time (UNIX Epoch, default "now") | -| `after` | return builds created after a certain time (UNIX Epoch, default 0) | - -## Permissions - -COMING SOON! - -## Responses - -| Status Code | Description | -| ----------- | --------------------------------------------------- | -| `200` | indicates the request has succeeded | -| `401` | indicates the user does not have proper permissions | - -## Sample - -:::warning -This section assumes you already know how to authenticate to the API. - -To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). -::: - -#### Request - -```sh -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds" -``` - -```sh -# with optional event filter -curl \ - -X GET \ - -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds?event=push" -``` - -#### Response - -```json -[ - { - "id": 2, - "repo_id": 1, - "number": 2, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474204, - "created": 1563474204, - "started": 1563474204, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "Second commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "ed95dcc0687c", - "runtime": "", - "distribution": "" - }, - { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, - "event": "push", - "status": "running", - "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, - "deploy": "", - "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", - "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", - "branch": "main", - "ref": "refs/heads/main", - "base_ref": "", - "host": "82823eb770b0", - "runtime": "", - "distribution": "" - } -] -``` diff --git a/docs/reference/api/build/list.md b/docs/reference/api/build/list.md new file mode 100644 index 0000000..bb18482 --- /dev/null +++ b/docs/reference/api/build/list.md @@ -0,0 +1,259 @@ +--- +title: "List" +linkTitle: "List" +description: > + Learn how to list builds. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## Filters + +The following optional filters are available: + +| Name | Description | +| -------- | ----------------------------------------------------------------------- | +| `branch` | name of branch to filter to | +| `commit` | commit hash to filter to | +| `event` | name of event to filter to | +| `page` | page number for results (default 1) | +| `per_page` | number of results in a page (default 10, max 100) | +| `status` | name of status to filter to | +| `before` | return builds created before a certain time (UNIX Epoch, default "now") | +| `after` | return builds created after a certain time (UNIX Epoch, default 0) | + +## Permissions + +User must have `read` access to the repository in the SCM. + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | + +## Sample + +:::warning +This section assumes you already know how to authenticate to the API. + +To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication.md). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds" +``` + +```sh +# with optional event filter +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds?event=push" +``` + +#### Response + +```json +[ + { + "id": 73081, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2146, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 2146, + "parent": 0, + "event": "push", + "event_action": "", + "status": "failure", + "error": "", + "enqueued": 1740768216, + "created": 1740768216, + "started": 1740768216, + "finished": 1740768217, + "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, + "clone": "https://github.com/github/octocat.git", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", + "title": "push received from https://github.com/github/octocat", + "message": "First commit...", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "", + "fork": false, + "author": "Octocat", + "email": "", + "link": "https://vela.example.com/github/octocat/2146", + "branch": "main", + "ref": "refs/heads/main", + "base_ref": "", + "head_ref": "", + "host": "worker1", + "runtime": "docker", + "distribution": "linux", + "approved_at": 0, + "approved_by": "" + }, + { + "id": 73080, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2146, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 13637, + "number": 2145, + "parent": 2127, + "event": "push", + "event_action": "", + "status": "canceled", + "error": "build was canceled by Octocat", + "enqueued": 1740767429, + "created": 1740767429, + "started": 0, + "finished": 0, + "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, + "clone": "https://github.com/github/octocat.git", + "source": "https://github.com/github/octocat/commit/d8ca6bccf7cc61bb62a491cedd94f6892b90412b", + "title": "push received from https://github.com/github/octocat", + "message": "test", + "commit": "d8ca6bccf7cc61bb62a491cedd94f6892b90412b", + "sender": "Octocat", + "sender_scm_id": "17043", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/2145", + "branch": "update-base-image", + "ref": "refs/heads/update-base-image", + "base_ref": "", + "head_ref": "", + "host": "worker2", + "runtime": "", + "distribution": "", + "approved_at": 0, + "approved_by": "" + } +] +``` diff --git a/docs/reference/api/build/logs.md b/docs/reference/api/build/logs.md index 51d6cd0..27a2f88 100644 --- a/docs/reference/api/build/logs.md +++ b/docs/reference/api/build/logs.md @@ -23,7 +23,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must have `read` access to the repository in the SCM. ## Responses diff --git a/docs/reference/api/build/remove.md b/docs/reference/api/build/remove.md index 2abca56..5be621e 100644 --- a/docs/reference/api/build/remove.md +++ b/docs/reference/api/build/remove.md @@ -23,7 +23,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must be a platform admin of the Vela installation. ## Responses diff --git a/docs/reference/api/build/restart.md b/docs/reference/api/build/restart.md index 0c7c7ba..b50eef9 100644 --- a/docs/reference/api/build/restart.md +++ b/docs/reference/api/build/restart.md @@ -23,7 +23,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must have `write` access to the repository in the SCM. ## Responses @@ -53,30 +53,93 @@ curl \ ```json { - "id": 2, - "repo_id": 1, - "number": 2, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "pending", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` diff --git a/docs/reference/api/build/update.md b/docs/reference/api/build/update.md index 5acebf5..10ef4fc 100644 --- a/docs/reference/api/build/update.md +++ b/docs/reference/api/build/update.md @@ -23,7 +23,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +Only vela workers can use this endpoint. ## Responses @@ -63,30 +63,93 @@ curl \ ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "this is an updated message", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` diff --git a/docs/reference/api/build/view.md b/docs/reference/api/build/view.md index 5e47e19..9e0acc5 100644 --- a/docs/reference/api/build/view.md +++ b/docs/reference/api/build/view.md @@ -23,7 +23,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must have `read` access to the repository in the SCM. ## Responses @@ -46,38 +46,101 @@ To authenticate to the API, please review the [authentication documentation](/do curl \ -X GET \ -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1000" ``` #### Response ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` @@ -120,37 +183,100 @@ To authenticate to the API, please review the [authentication documentation](/do curl \ -X GET \ -H "Authorization: Bearer " \ - "http://127.0.0.1:8080/api/v1/search/builds/1" + "http://127.0.0.1:8080/api/v1/search/builds/40063" ``` #### Response ```json { - "id": 1, - "repo_id": 1, - "number": 1, - "parent": 1, + "id": 40063, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "Octocat", + "active": true + }, + "org": "Octocat", + "name": "myvela", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2145, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "pipeline_id": 4177, + "number": 1000, + "parent": 999, "event": "push", - "status": "created", + "event_action": "", + "status": "success", "error": "", - "enqueued": 1563474077, - "created": 1563474076, - "started": 1563474077, - "finished": 0, + "enqueued": 1693341901, + "created": 1693341901, + "started": 1693341901, + "finished": 1693341903, "deploy": "", + "deploy_number": 0, + "deploy_payload": {}, "clone": "https://github.com/github/octocat.git", - "source": "https://github.com/github/octocat/commit/48afb5bdc41ad69bf22588491333f7cf71135163", + "source": "https://github.com/github/octocat/commit/1598250b3d002c9f25f82bb046296f831b6b9a53", "title": "push received from https://github.com/github/octocat", - "message": "First commit...", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "sender": "OctoKitty", - "author": "OctoKitty", + "message": "Update .vela.yml", + "commit": "1598250b3d002c9f25f82bb046296f831b6b9a53", + "sender": "Octocat", + "sender_scm_id": "0", + "fork": false, + "author": "Octocat", + "email": "octocat@github.com", + "link": "https://vela.example.com/github/octocat/1000", "branch": "main", "ref": "refs/heads/main", "base_ref": "", - "host": "company.localhost", + "head_ref": "", + "host": "worker1", "runtime": "docker", - "distribution": "linux" + "distribution": "linux", + "approved_at": 0, + "approved_by": "" } ``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/add.md b/docs/reference/api/dashboard/add.md index a3285ef..edfba50 100644 --- a/docs/reference/api/dashboard/add.md +++ b/docs/reference/api/dashboard/add.md @@ -13,7 +13,7 @@ POST /api/v1/dashboards ## Permissions -COMING SOON! +Users need a valid access token. ## Responses @@ -50,7 +50,7 @@ To authenticate to the API, please review the [authentication documentation](/do ], "repos": [ { - "name": "Octocat/myvela" + "name": "github/octocat" } ] } @@ -87,7 +87,7 @@ curl \ "repos": [ { "id": 293, - "name": "Octocat/myvela" + "name": "github/octocat" } ] } diff --git a/docs/reference/api/dashboard/delete.md b/docs/reference/api/dashboard/delete.md index 6b1b6b2..f14fc6d 100644 --- a/docs/reference/api/dashboard/delete.md +++ b/docs/reference/api/dashboard/delete.md @@ -13,7 +13,7 @@ DELETE /api/v1/dashboards/:id ## Permissions -COMING SOON! +User must be a member of the admin list for the dashboard. ## Responses diff --git a/docs/reference/api/dashboard/get.md b/docs/reference/api/dashboard/get.md index 10a6ec0..05a7cea 100644 --- a/docs/reference/api/dashboard/get.md +++ b/docs/reference/api/dashboard/get.md @@ -13,7 +13,7 @@ GET /api/v1/dashboards/:id ## Permissions -COMING SOON! +Any user with a valid access token can view a dashboard. ## Responses @@ -64,7 +64,7 @@ curl \ "repos": [ { "id": 293, - "name": "Octocat/myvela" + "name": "github/octocat" } ] }, @@ -83,7 +83,7 @@ curl \ "status": "success", "event": "push", "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1703" + "link": "https://http://127.0.0.1:8080/github/octocat/1703" }, { "number": 1702, @@ -91,7 +91,7 @@ curl \ "status": "pending approval", "event": "pull_request", "branch": "main", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1702" + "link": "https://http://127.0.0.1:8080/github/octocat/1702" }, { "number": 1701, @@ -101,7 +101,7 @@ curl \ "status": "failure", "event": "push", "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1701" + "link": "https://http://127.0.0.1:8080/github/octocat/1701" }, { "number": 1700, @@ -111,7 +111,7 @@ curl \ "status": "failure", "event": "push", "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1700" + "link": "https://http://127.0.0.1:8080/github/octocat/1700" }, { "number": 1699, @@ -121,7 +121,7 @@ curl \ "status": "failure", "event": "push", "branch": "develop", - "link": "https://http://127.0.0.1:8080/Octocat/myvela/1699" + "link": "https://http://127.0.0.1:8080/github/octocat/1699" } ] } diff --git a/docs/reference/api/dashboard/list.md b/docs/reference/api/dashboard/list.md index 1e7c81a..d3a1f86 100644 --- a/docs/reference/api/dashboard/list.md +++ b/docs/reference/api/dashboard/list.md @@ -13,7 +13,7 @@ GET /api/v1/user/dashboards ## Permissions -COMING SOON! +Any user with a valid access token can list their own saved dashboards. ## Responses @@ -70,7 +70,7 @@ curl \ "repos": [ { "id": 293, - "name": "Octocat/myvela" + "name": "github/octocat" }, { "id": 34, @@ -100,7 +100,7 @@ curl \ "repos": [ { "id": 293, - "name": "Octocat/myvela" + "name": "github/octocat" } ] }, diff --git a/docs/reference/api/dashboard/update.md b/docs/reference/api/dashboard/update.md index 55e7524..22dac2a 100644 --- a/docs/reference/api/dashboard/update.md +++ b/docs/reference/api/dashboard/update.md @@ -13,7 +13,7 @@ PUT /api/v1/dashboards/:id ## Permissions -COMING SOON! +User must be a member of the admin list for the dashboard. ## Responses @@ -50,7 +50,7 @@ To authenticate to the API, please review the [authentication documentation](/do ], "repos": [ { - "name": "Octocat/myvela" + "name": "github/octocat" }, { "name": "Octocat/other-repo" @@ -95,7 +95,7 @@ curl \ "repos": [ { "id": 293, - "name": "Octocat/myvela" + "name": "github/octocat" }, { "id": 294, diff --git a/docs/reference/api/deployment/add.md b/docs/reference/api/deployment/add.md index 9179979..943bd39 100644 --- a/docs/reference/api/deployment/add.md +++ b/docs/reference/api/deployment/add.md @@ -22,7 +22,7 @@ The following parameters are used to configure the endpoint: ## Permissions -COMING SOON! +User must have `admin` access to the repository in the SCM. ## Responses @@ -63,15 +63,74 @@ curl \ ```json { - "id": 1, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/1", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela" + "id": 466, + "number": 877720, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "github", + "active": true + }, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2162, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "url": "https://api.github.com/repos/github/octocat/deployments/877720", + "commit": "ae28c6ac990bc249041a07b31dfcdaf96e1338dd", + "ref": "deploy-config-test", + "task": "deploy:vela", + "target": "prod", + "description": "Deployment request from Vela", + "payload": { + "CLUSTER_COUNT": "50", + "region": "us-west-1" + }, + "created_at": 1740765107, + "created_by": "github", + "builds": [] } ``` diff --git a/docs/reference/api/deployment/view.md b/docs/reference/api/deployment/view.md index a995bad..9709dd9 100644 --- a/docs/reference/api/deployment/view.md +++ b/docs/reference/api/deployment/view.md @@ -53,14 +53,117 @@ curl \ ```json { - "id": 1, - "repo_id": 1, - "url": "https://api.github.com/repos/github/octocat/deployments/1", - "user": "octocat", - "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", - "ref": "main", - "task": "deploy:vela", - "target": "production", - "description": "Deployment request from Vela" + "id": 466, + "number": 877720, + "repo": { + "id": 293, + "owner": { + "id": 126, + "name": "github", + "active": true + }, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 2162, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": true, + "edited": true, + "synchronize": true, + "reopened": true, + "labeled": true, + "unlabeled": true + }, + "deployment": { + "created": true + }, + "comment": { + "created": true, + "edited": true + }, + "schedule": { + "run": true + } + }, + "pipeline_type": "go", + "previous_name": "", + "approve_build": "fork-always", + "approval_timeout": 7, + "install_id": 0 + }, + "url": "https://api.github.com/repos/github/octocat/deployments/877720", + "commit": "ae28c6ac990bc249041a07b31dfcdaf96e1338dd", + "ref": "deploy-config-test", + "task": "deploy:vela", + "target": "prod", + "description": "Deployment request from Vela", + "payload": { + "CLUSTER_COUNT": "50", + "region": "us-west-1" + }, + "created_at": 1740765107, + "created_by": "github", + "builds": [ + { + "id": 73075, + "repo": { + "id": 293 + }, + "pipeline_id": 13485, + "number": 2141, + "parent": 0, + "event": "deployment", + "event_action": "created", + "status": "success", + "error": "", + "enqueued": 1740765108, + "created": 1740765108, + "started": 1740765108, + "finished": 1740765111, + "deploy": "prod", + "deploy_number": 877720, + "deploy_payload": { + "CLUSTER_COUNT": "50", + "region": "us-west-1" + }, + "clone": "https://github.com/github/octocat.git", + "source": "https://api.github.com/repos/github/octocat/deployments/877720", + "title": "deployment received from https://github.com/github/octocat", + "message": "Deployment request from Vela", + "commit": "ae28c6ac990bc249041a07b31dfcdaf96e1338dd", + "sender": "github", + "sender_scm_id": "17043", + "fork": false, + "author": "github", + "email": "", + "link": "https://vela.dev.target.com/github/octocat/2141", + "branch": "deploy-config-test", + "ref": "refs/heads/deploy-config-test", + "base_ref": "", + "head_ref": "", + "host": "worker", + "runtime": "docker", + "distribution": "linux", + "approved_at": 0, + "approved_by": "" + } + ] } ```