diff --git a/docs/installation/_category_.json b/docs/installation/_category_.json deleted file mode 100644 index 8f26407..0000000 --- a/docs/installation/_category_.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "label": "Installation", - "position": 1, - "link": { - "type": "generated-index", - "description": "A Vela cluster is deployed as a self-hosted solution and consists of two core services, the server and the worker. The relationship between these services is considered many-to-many meaning many workers can connect to many servers. - -The server is considered the brains of the application while the worker is considered the brawn of the application. - -An optional third service, the UI, can also be deployed but is not required for the Vela platform to operate as intended. This service provides a means for utilizing and interacting with the Vela platform." - } -} diff --git a/docs/reference/_index.md b/docs/reference/_index.md new file mode 100644 index 0000000..903122c --- /dev/null +++ b/docs/reference/_index.md @@ -0,0 +1,10 @@ +--- +title: "Reference" +linkTitle: "Reference" +layout: reference +description: > + Reference information for creating pipelines and using the CLI, API, or SDKs. +menu: + main: + weight: 605 +--- diff --git a/docs/reference/api/_category_.json b/docs/reference/api/_category_.json index cccf88d..c995733 100644 --- a/docs/reference/api/_category_.json +++ b/docs/reference/api/_category_.json @@ -1,5 +1,7 @@ { "label": "API", "position": 1, - "link": {"type": "generated-index"}, + "link": { + "type": "generated-index" + } } diff --git a/docs/reference/api/admin/_category_.json b/docs/reference/api/admin/_category_.json deleted file mode 100644 index e4d6677..0000000 --- a/docs/reference/api/admin/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Admin", - "position": 2, -"link": {"type": "generated-index"}, -} \ No newline at end of file diff --git a/docs/reference/api/admin/admin.md b/docs/reference/api/admin/admin.md new file mode 100644 index 0000000..189447f --- /dev/null +++ b/docs/reference/api/admin/admin.md @@ -0,0 +1,14 @@ +--- +title: "Admin" +linkTitle: "Admin" +description: > + Learn how to use API endpoints as an admin of the platform. +--- + +The below endpoints are available to operate on as an admin of the platform. + +:::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/). +::: diff --git a/docs/reference/api/admin/build.md b/docs/reference/api/admin/build.md index 30b0b29..4bedb9f 100644 --- a/docs/reference/api/admin/build.md +++ b/docs/reference/api/admin/build.md @@ -11,6 +11,10 @@ description: > PUT /api/v1/admin/build ``` +## Permissions + +COMING SOON! + ## Responses | Status Code | Description | diff --git a/docs/reference/api/admin/build-queue.md b/docs/reference/api/admin/build_queue.md similarity index 98% rename from docs/reference/api/admin/build-queue.md rename to docs/reference/api/admin/build_queue.md index 5adda20..50fbf8b 100644 --- a/docs/reference/api/admin/build-queue.md +++ b/docs/reference/api/admin/build_queue.md @@ -11,6 +11,10 @@ description: > GET /api/v1/admin/builds/queue ``` +## Permissions + +COMING SOON! + ## Responses | Status Code | Description | diff --git a/docs/reference/api/admin/clean.md b/docs/reference/api/admin/clean.md new file mode 100644 index 0000000..df98178 --- /dev/null +++ b/docs/reference/api/admin/clean.md @@ -0,0 +1,68 @@ +--- +title: "Clean" +linkTitle: "Clean" +description: > + Learn how to clean dangling resources as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/clean +``` + +## Filters + +The following optional filters are available: + +| Name | Description | +| -------- | ---------------------------------------------------------------------------------------------------------- | +| `before` | clean resources created before a certain time (UNIX Epoch, default = "now" minus repo timeout + 5 minutes) | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | indicates bad request | +| `401` | indicates user does not have proper permissions | +| `500` | indicates internal server issue while cleaning | + +## 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/). +::: + +#### File + +```json +{ + "message": "this resource has been set to error by platform admins during maintenance" +} +``` + +Note: the default value for `message` is "build cleaned by platform admin" + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/clean" +``` + +#### Response + +```json + "42 builds cleaned. 42 services cleaned. 42 steps cleaned." +``` \ No newline at end of file diff --git a/docs/reference/api/admin/hook.md b/docs/reference/api/admin/hook.md new file mode 100644 index 0000000..880f9a7 --- /dev/null +++ b/docs/reference/api/admin/hook.md @@ -0,0 +1,83 @@ +--- +title: "Hook" +linkTitle: "Hook" +description: > + Learn how to update a hook as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/hook +``` + +## 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/). +::: + +Note: You must provide the entire hook object, as this endpoint overwrites the +existing entry for the hook. + +#### File + +```json +{ + "id": 1, + "repo_id": 1, + "build_id": 1, + "number": 1, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "failure", + "link": "" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/admin/hook" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "build_id": 1, + "number": 1, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "failure", + "link": "" +} +``` diff --git a/docs/reference/api/admin/repo.md b/docs/reference/api/admin/repo.md new file mode 100644 index 0000000..206308e --- /dev/null +++ b/docs/reference/api/admin/repo.md @@ -0,0 +1,101 @@ +--- +title: "Repo" +linkTitle: "Repo" +description: > + Learn how to update a repo as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/repo +``` + +## 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/). +::: + +Note: You must provide the entire repo object, as this endpoint overwrites the +existing entry for the repo. + +#### File + +```json +{ + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": true, + "allow_comment": false, + "pipeline_type": "yaml" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/repo" +``` + +#### Response + +```json +{ + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": true, + "allow_comment": false, + "pipeline_type": "yaml" +} +``` diff --git a/docs/reference/api/admin/secret.md b/docs/reference/api/admin/secret.md new file mode 100644 index 0000000..9797fd7 --- /dev/null +++ b/docs/reference/api/admin/secret.md @@ -0,0 +1,141 @@ +--- +title: "Secret" +linkTitle: "Secret" +description: > + Learn how to update a secret as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/secret +``` + +## 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/). +::: + +Note: You must provide the entire secret object, as this endpoint overwrites the +existing entry for the secret. + +#### File + +```json +{ + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": "", + "type": "repo", + "images": ["alpine"], + "events": ["push", "tag"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314500, + "updated_by": "octocat" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" + "http://127.0.0.1:8080/api/v1/admin/secret" +``` + +#### Response + +```json +{ + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": "", + "type": "repo", + "images": ["alpine"], + "events": ["push", "tag"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314500, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/admin/service.md b/docs/reference/api/admin/service.md new file mode 100644 index 0000000..423ed9d --- /dev/null +++ b/docs/reference/api/admin/service.md @@ -0,0 +1,81 @@ +--- +title: "Service" +linkTitle: "Service" +description: > + Learn how to update a service as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/service +``` + +## 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/). +::: + +Note: You must provide the entire service object, as this endpoint overwrites the +existing entry for the service. + +#### File + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/service" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 +} +``` diff --git a/docs/reference/api/admin/settings/restore.md b/docs/reference/api/admin/settings/restore.md new file mode 100644 index 0000000..2ff5419 --- /dev/null +++ b/docs/reference/api/admin/settings/restore.md @@ -0,0 +1,69 @@ +--- +title: "Restore" +linkTitle: "Restore" +description: > + Learn how to restore settings to the server environment defaults. +--- + +## Endpoint + +``` +DELETE /api/v1/admin/settings +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | ---------------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates the server was unable to retrieve a resource | +| `500` | indicates a server failure while processing the request | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/admin/settings" +``` + +#### Response + +```json +{ + "id": 1, + "compiler": { + "clone_image": "target/vela-git:latest", + "template_depth": 3, + "starlark_exec_limit": 7500 + }, + "queue": { + "routes": [ + "vela" + ] + }, + "repo_allowlist": [ + "*", + ], + "schedule_allowlist": [ + "github/octocat", + ], + "created_at": 1715718878, + "updated_at": 1715718879, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/admin/settings/settings.md b/docs/reference/api/admin/settings/settings.md new file mode 100644 index 0000000..ed4f908 --- /dev/null +++ b/docs/reference/api/admin/settings/settings.md @@ -0,0 +1,14 @@ +--- +title: "Settings" +linkTitle: "Settings" +description: > + Learn how to use API endpoints for platform settings. +--- + +The below endpoints are available to operate on the `settings` resource. + +:::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/). +::: diff --git a/docs/reference/api/admin/settings/update.md b/docs/reference/api/admin/settings/update.md new file mode 100644 index 0000000..68c0852 --- /dev/null +++ b/docs/reference/api/admin/settings/update.md @@ -0,0 +1,94 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to update platform settings. +--- + +## Endpoint + +``` +PUT /api/v1/admin/settings +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | ---------------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates the server was unable to retrieve a resource | +| `500` | indicates a server failure while processing the request | + +## 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/). +::: + +#### File + +```json +{ + "compiler": { + "clone_image": "target/vela-git:latest", + "template_depth": 3, + "starlark_exec_limit": 7500 + }, + "queue": { + "routes": [ + "vela" + ] + }, + "repo_allowlist": [ + "*", + ], + "schedule_allowlist": [ + "github/octocat", + ] +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/settings" +``` + +#### Response + +```json +{ + "id": 1, + "compiler": { + "clone_image": "target/vela-git:latest", + "template_depth": 3, + "starlark_exec_limit": 7500 + }, + "queue": { + "routes": [ + "vela" + ] + }, + "repo_allowlist": [ + "*", + ], + "schedule_allowlist": [ + "github/octocat", + ], + "created_at": 1715718878, + "updated_at": 1715718879, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/admin/settings/view.md b/docs/reference/api/admin/settings/view.md new file mode 100644 index 0000000..94771e5 --- /dev/null +++ b/docs/reference/api/admin/settings/view.md @@ -0,0 +1,68 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to view active platform settings. +--- + +## Endpoint + +``` +GET /api/v1/admin/settings +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | ---------------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates the server was unable to retrieve a resource | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/admin/settings" +``` + +#### Response + +```json +{ + "id": 1, + "compiler": { + "clone_image": "target/vela-git:latest", + "template_depth": 3, + "starlark_exec_limit": 7500 + }, + "queue": { + "routes": [ + "vela" + ] + }, + "repo_allowlist": [ + "*", + ], + "schedule_allowlist": [ + "github/octocat", + ], + "created_at": 1715718878, + "updated_at": 1715718879, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/admin/step.md b/docs/reference/api/admin/step.md new file mode 100644 index 0000000..fc01247 --- /dev/null +++ b/docs/reference/api/admin/step.md @@ -0,0 +1,87 @@ +--- +title: "Step" +linkTitle: "Step" +description: > + Learn how to update a step as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/step +``` + +## 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/). +::: + +Note: You must provide the entire step object, as this endpoint overwrites the +existing entry for the step. + +#### File + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/step" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/admin/user.md b/docs/reference/api/admin/user.md new file mode 100644 index 0000000..8616263 --- /dev/null +++ b/docs/reference/api/admin/user.md @@ -0,0 +1,71 @@ +--- +title: "User" +linkTitle: "User" +description: > + Learn how to update a user as an admin in the system. +--- + +## Endpoint + +``` +PUT /api/v1/admin/user +``` + +## 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/). +::: + +Note: You must provide the entire service object, as this endpoint overwrites the +existing entry for the service. + +#### File + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": true +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/admin/user" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": true +} +``` diff --git a/docs/reference/api/admin/worker.md b/docs/reference/api/admin/worker.md new file mode 100644 index 0000000..cb1e03f --- /dev/null +++ b/docs/reference/api/admin/worker.md @@ -0,0 +1,49 @@ +--- +title: "Worker" +linkTitle: "Worker" +description: > + Learn how to request a worker registration token as an admin. +--- + +## Endpoint + +``` +POST /api/v1/admin/workers/:worker/register-token +``` + +## 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/). +::: + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + "http://127.0.0.1:8080/api/v1/admin/workers/worker_1/register-token" +``` + +#### Response + +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3b3JrZXJfMSIsImlhdCI6MTUxNjIzOTAyMiwiZWF0IjoxNTE2MjQ1MDIyLCJ0b2tlbl90eXBlIjoiV29ya2VyUmVnaXN0ZXIifQ.U2zNa3E8Wwd6ndoVMrwEZ1TWlmMVTZP8-UaShZA1Qpw" +} +``` \ No newline at end of file diff --git a/docs/reference/api/authentication.md b/docs/reference/api/authentication.md index 4d0c348..cee017b 100644 --- a/docs/reference/api/authentication.md +++ b/docs/reference/api/authentication.md @@ -1,9 +1,6 @@ --- title: "Authentication" -linkTitle: "Authentication" -weight: 5 -description: > - Learn how authenticating to the Vela API works. +sidebar_position: 1 --- ## Overview @@ -18,7 +15,7 @@ The content of this header should be using the `Bearer ` scheme. Authorization: Bearer ``` -:::tip +:::info For more information, you can visit the [Swagger authentication documentation](https://swagger.io/docs/specification/authentication/bearer-authentication/). ::: @@ -40,7 +37,7 @@ header.payload.signature xxxxx.yyyyy.zzzzz ``` -:::tip +:::info For more information, you can visit the [JWT introduction documentation](https://jwt.io/introduction/). ::: diff --git a/docs/reference/api/build/add.md b/docs/reference/api/build/add.md new file mode 100644 index 0000000..b79744e --- /dev/null +++ b/docs/reference/api/build/add.md @@ -0,0 +1,100 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a build. +--- + +## Endpoint + +``` +POST /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 | + +## 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/). +::: + +#### File + +```json +{ + "author": "Octokitty", + "branch": "main", + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "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", + "title": "push received from https://github.com/github/octocat" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "number": 1, + "parent": 1, + "event": "push", + "status": "created", + "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": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/build/build.md b/docs/reference/api/build/build.md new file mode 100644 index 0000000..960462b --- /dev/null +++ b/docs/reference/api/build/build.md @@ -0,0 +1,14 @@ +--- +title: "Build" +linkTitle: "Build" +description: > + Learn how to use API endpoints for the build resource. +--- + +The below endpoints are available to operate on the `build` resource. + +:::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/). +::: diff --git a/docs/reference/api/build/cancel.md b/docs/reference/api/build/cancel.md new file mode 100644 index 0000000..bed7713 --- /dev/null +++ b/docs/reference/api/build/cancel.md @@ -0,0 +1,48 @@ +--- +title: "Cancel" +linkTitle: "Cancel" +description: > + Learn how to cancel a build. +--- + +## Endpoint + +``` +DELETE /api/v1/repos/:org/:repo/builds/:build/cancel +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | ---------------------------------------------------------| +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates that the server was unable to cancel the build | +| `500` | indicates there was an error trying to cancel the build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/cancel" +``` + +#### Response + +```json + "canceled build github/octocat/36" +``` diff --git a/docs/reference/api/build/get.md b/docs/reference/api/build/get.md new file mode 100644 index 0000000..9a0a8ed --- /dev/null +++ b/docs/reference/api/build/get.md @@ -0,0 +1,133 @@ +--- +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/). +::: + +#### 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/logs.md b/docs/reference/api/build/logs.md new file mode 100644 index 0000000..fbd6a9d --- /dev/null +++ b/docs/reference/api/build/logs.md @@ -0,0 +1,77 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: > + Learn how to view logs for a build. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/logs +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/logs" +``` + +#### Response + +```json +[ + { + "id": 1, + "step_id": 1, + "build_id": 1, + "repo_id": 1, + "data": "SGVsbG8sIFdvcmxkIQ==" + }, + { + "id": 2, + "step_id": 2, + "build_id": 1, + "repo_id": 1, + "data": "SGVsbG8sIFdvcmxkIQ==" + } +] +``` + +The `data` field is base64 encoded. To decode the data, you can use the following command: + +```sh +echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode +``` diff --git a/docs/reference/api/build/remove.md b/docs/reference/api/build/remove.md new file mode 100644 index 0000000..46edf54 --- /dev/null +++ b/docs/reference/api/build/remove.md @@ -0,0 +1,56 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a build. +--- + +## Endpoint + +``` +DELETE /api/v1/repos/:org/:repo/builds/:build +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" +``` + +#### Response + +```sh +Build github/octocat/1 deleted +``` diff --git a/docs/reference/api/build/restart.md b/docs/reference/api/build/restart.md new file mode 100644 index 0000000..c32753b --- /dev/null +++ b/docs/reference/api/build/restart.md @@ -0,0 +1,82 @@ +--- +title: "Restart" +linkTitle: "Restart" +description: > + Learn how to rerun a build. +--- + +## Endpoint + +``` +POST /api/v1/repos/:org/:repo/builds/:build +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" +``` + +#### Response + +```json +{ + "id": 2, + "repo_id": 1, + "number": 2, + "parent": 1, + "event": "push", + "status": "created", + "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": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/build/update.md b/docs/reference/api/build/update.md new file mode 100644 index 0000000..41b1cbe --- /dev/null +++ b/docs/reference/api/build/update.md @@ -0,0 +1,92 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a build. +--- + +## Endpoint + +``` +PUT /api/v1/repos/:org/:repo/builds/:build +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### File + +```json +{ + "message": "this is an updated message" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "number": 1, + "parent": 1, + "event": "push", + "status": "created", + "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": "this is an updated message", + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "sender": "OctoKitty", + "author": "OctoKitty", + "branch": "main", + "ref": "refs/heads/main", + "base_ref": "", + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/build/view.md b/docs/reference/api/build/view.md new file mode 100644 index 0000000..69e57f4 --- /dev/null +++ b/docs/reference/api/build/view.md @@ -0,0 +1,156 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a build. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "number": 1, + "parent": 1, + "event": "push", + "status": "created", + "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": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` + +## Alternative Endpoint (By ID) + +``` +GET /api/v1/search/builds/:id +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | ----------------------- | +| `id` | unique ID of Vela build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/search/builds/1" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "number": 1, + "parent": 1, + "event": "push", + "status": "created", + "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": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/add.md b/docs/reference/api/dashboard/add.md new file mode 100644 index 0000000..f43ca92 --- /dev/null +++ b/docs/reference/api/dashboard/add.md @@ -0,0 +1,94 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a dashboard. +--- + +## Endpoint + +``` +POST /api/v1/dashboards +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `201` | indicates the request has succeeded | +| `400` | indicates a bad request | +| `401` | indicates the user does not have proper permissions | +| `500` | indicates a server error | + +## 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/). +::: + +#### File + +```json +{ + "name": "test", + "created_at": 1721251709, + "created_by": "Octocat", + "updated_at": 1721251709, + "updated_by": "Octocat", + "admins": [ + { + "id": 1, + "name": "Octocat", + "active": true + } + ], + "repos": [ + { + "name": "Octocat/myvela" + } + ] +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/dashboards" +``` + +#### Response + +```json +{ + "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", + "name": "test", + "created_at": 1721251709, + "created_by": "Octocat", + "updated_at": 1721253772, + "updated_by": "Octocat", + "admins": [ + { + "id": 1, + "name": "Octocat", + "active": true + } + ], + "repos": [ + { + "id": 293, + "name": "Octocat/myvela" + } + ] +} +``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/dashboard.md b/docs/reference/api/dashboard/dashboard.md new file mode 100644 index 0000000..5a845ed --- /dev/null +++ b/docs/reference/api/dashboard/dashboard.md @@ -0,0 +1,14 @@ +--- +title: "Dashboard" +linkTitle: "Dashboard" +description: > + Learn how to use API endpoints for the dashboard resource. +--- + +The below endpoints are available to operate on the `dashboard` resource. + +:::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/). +::: \ No newline at end of file diff --git a/docs/reference/api/dashboard/delete.md b/docs/reference/api/dashboard/delete.md new file mode 100644 index 0000000..b387731 --- /dev/null +++ b/docs/reference/api/dashboard/delete.md @@ -0,0 +1,50 @@ +--- +title: "Delete" +linkTitle: "Delete" +description: > + Learn how to delete a dashboard. +--- + +## Endpoint + +``` +DELETE /api/v1/dashboards/:id +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | indicates a bad request | +| `401` | indicates the user does not have proper permissions | +| `500` | indicates a server error | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/dashboards/f460e0a1-a6a5-4724-89e8-4b2b39e12012" +``` + +#### Response + +``` +"dashboard test deleted" +``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/get.md b/docs/reference/api/dashboard/get.md new file mode 100644 index 0000000..c6527a9 --- /dev/null +++ b/docs/reference/api/dashboard/get.md @@ -0,0 +1,130 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to get a dashboard. +--- + +## Endpoint + +``` +GET /api/v1/dashboards/:id +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | indicates a bad request | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates the resource does not exist | +| `500` | indicates a server error | + +## 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/). +::: + +#### Request + +```sh +curl \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/dashboards/3e84cf64-4730-4067-bdbc-6961e37a3a92" +``` + +#### Response + +```json +{ + "dashboard": { + "id": "3e84cf64-4730-4067-bdbc-6961e37a3a92", + "name": "test", + "created_at": 1721254450, + "created_by": "Octocat", + "updated_at": 1721254596, + "updated_by": "Octocat", + "admins": [ + { + "id": 126, + "name": "Octocat", + "active": true + } + ], + "repos": [ + { + "id": 293, + "name": "Octocat/myvela" + } + ] + }, + "repos": [ + { + "org": "Octocat", + "name": "myvela", + "counter": 1703, + "active": true, + "builds": [ + { + "number": 1703, + "started": 1721164234, + "finished": 1721164240, + "sender": "Octocat", + "status": "success", + "event": "push", + "branch": "develop", + "link": "https://http://127.0.0.1:8080/Octocat/myvela/1703" + }, + { + "number": 1702, + "sender": "Octocat", + "status": "pending approval", + "event": "pull_request", + "branch": "main", + "link": "https://http://127.0.0.1:8080/Octocat/myvela/1702" + }, + { + "number": 1701, + "started": 1721071014, + "finished": 1721071016, + "sender": "Octocat", + "status": "failure", + "event": "push", + "branch": "develop", + "link": "https://http://127.0.0.1:8080/Octocat/myvela/1701" + }, + { + "number": 1700, + "started": 1721070428, + "finished": 1721070441, + "sender": "Octocat", + "status": "failure", + "event": "push", + "branch": "develop", + "link": "https://http://127.0.0.1:8080/Octocat/myvela/1700" + }, + { + "number": 1699, + "started": 1721070363, + "finished": 1721070375, + "sender": "Octocat", + "status": "failure", + "event": "push", + "branch": "develop", + "link": "https://http://127.0.0.1:8080/Octocat/myvela/1699" + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/list.md b/docs/reference/api/dashboard/list.md new file mode 100644 index 0000000..21a0642 --- /dev/null +++ b/docs/reference/api/dashboard/list.md @@ -0,0 +1,112 @@ +--- +title: "List" +linkTitle: "List" +description: > + Learn how to list your dashboards. +--- + +## Endpoint + +``` +GET /api/v1/user/dashboards +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | indicates a bad request | +| `401` | indicates the user does not have proper permissions | +| `404` | indicates the resource does not exist | +| `500` | indicates a server error | + +## 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/). +::: + +#### Request + +```sh +curl \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/user/dashboards" +``` + +#### Response + +```json +[ + { + "dashboard": { + "id": "215d0834-a08a-4203-aee5-542681c4dc8d", + "name": "Friends", + "created_at": 1718118753, + "created_by": "Octocat", + "updated_at": 1718120350, + "updated_by": "OctoKitty", + "admins": [ + { + "id": 287, + "name": "OctoKitty", + "active": true + }, + { + "id": 126, + "name": "Octocat", + "active": true + } + ], + "repos": [ + { + "id": 293, + "name": "Octocat/myvela" + }, + { + "id": 34, + "name": "OctoPal/heyvela" + } + ] + }, + "repos": [ + // repo build information + ] + }, + { + "dashboard": { + "id": "3e84cf64-4730-4067-bdbc-6961e37a3a92", + "name": "test", + "created_at": 1721254450, + "created_by": "Octocat", + "updated_at": 1721254596, + "updated_by": "Octocat", + "admins": [ + { + "id": 126, + "name": "Octocat", + "active": true + } + ], + "repos": [ + { + "id": 293, + "name": "Octocat/myvela" + } + ] + }, + "repos": [ + // repo build information + ] + } +] +``` \ No newline at end of file diff --git a/docs/reference/api/dashboard/update.md b/docs/reference/api/dashboard/update.md new file mode 100644 index 0000000..7891f6c --- /dev/null +++ b/docs/reference/api/dashboard/update.md @@ -0,0 +1,106 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to update a dashboard. +--- + +## Endpoint + +``` +PUT /api/v1/dashboards/:id +``` + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | indicates a bad request | +| `401` | indicates the user does not have proper permissions | +| `500` | indicates a server error | + +## 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/). +::: + +#### File + +```json +{ + "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", + "name": "new-name", + "admins": [ + { + "id": 1, + "name": "Octocat", + "active": true + }, + { + "name": "MyFriend" + } + ], + "repos": [ + { + "name": "Octocat/myvela" + }, + { + "name": "Octocat/other-repo" + } + ] +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/dashboards/f460e0a1-a6a5-4724-89e8-4b2b39e12012" +``` + +#### Response + +```json +{ + "id": "f460e0a1-a6a5-4724-89e8-4b2b39e12012", + "name": "new-name", + "created_at": 1721251709, + "created_by": "Octocat", + "updated_at": 1721253772, + "updated_by": "Octocat", + "admins": [ + { + "id": 1, + "name": "Octocat", + "active": true + }, + { + "id": 2, + "name": "MyFriend", + "active": true + } + ], + "repos": [ + { + "id": 293, + "name": "Octocat/myvela" + }, + { + "id": 294, + "name": "Octocat/other-repo" + } + ] +} +``` \ No newline at end of file diff --git a/docs/reference/api/deployment/add.md b/docs/reference/api/deployment/add.md new file mode 100644 index 0000000..c67404d --- /dev/null +++ b/docs/reference/api/deployment/add.md @@ -0,0 +1,122 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a deployment. +--- + +## Endpoint + +``` +POST /api/v1/deployments/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### File + +```json +{ + "ref": "main", + "target": "production" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/deployments/github/octocat" +``` + +#### Response + +```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" +} +``` + +#### File with Parameters + +If you would like to pass parameters, which can be referenced in the pipeline as `$DEPLOYMENT_PARAMETER_`, include them as a map inside the `payload` key. + +```json +{ + "ref": "main", + "target": "production", + "payload": { + "FIRST_EXAMPLE": "hello", + "SECOND_EXAMPLE": "goodbye" + } +} +``` + +#### Request with Parameters + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/deployments/github/octocat" +``` + +#### Response with Parameters + +```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", + "payload": { + "EXAMPLE": "hello", + "SECOND_EXAMPLE": "goodbye" + } +} +``` diff --git a/docs/reference/api/deployment/deployment.md b/docs/reference/api/deployment/deployment.md new file mode 100644 index 0000000..bd126a7 --- /dev/null +++ b/docs/reference/api/deployment/deployment.md @@ -0,0 +1,14 @@ +--- +title: "Deployment" +linkTitle: "Deployment" +description: > + Learn how to use API endpoints for the deployment resource. +--- + +The below endpoints are available to operate on the `deployment` resource. + +:::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/). +::: diff --git a/docs/reference/api/deployment/get.md b/docs/reference/api/deployment/get.md new file mode 100644 index 0000000..c38794b --- /dev/null +++ b/docs/reference/api/deployment/get.md @@ -0,0 +1,138 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list deployments. +--- + +## Endpoint + +``` +GET /api/v1/deployments/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/deployments/github/octocat" +``` + +#### Response + +```json +[ + { + "id": 2, + "repo_id": 1, + "url": "https://api.github.com/repos/github/octocat/deployments/2", + "user": "octocat", + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "ref": "main", + "task": "deploy:vela", + "target": "production", + "description": "Deployment request from Vela", + "payload": {}, + "builds": [ + { + "id": 10, + "repo_id": 1, + "number": 5, + "parent": 4, + "event": "push", + "status": "created", + "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": 9, + "repo_id": 1, + "url": "https://api.github.com/repos/github/octocat/deployments/9", + "user": "octocat", + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "ref": "main", + "task": "deploy:vela", + "target": "production", + "description": "Deployment request from Vela", + "payload": {}, + "builds": [ + { + "id": 1, + "repo_id": 1, + "number": 3, + "parent": 2, + "event": "push", + "status": "created", + "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/deployment/view.md b/docs/reference/api/deployment/view.md new file mode 100644 index 0000000..0a8bc7b --- /dev/null +++ b/docs/reference/api/deployment/view.md @@ -0,0 +1,66 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a deployment. +--- + +## Endpoint + +``` +GET /api/v1/deployments/:org/:repo/:deployment +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `deployment` | number of deployment | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/deployments/github/octocat/1" +``` + +#### Response + +```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" +} +``` diff --git a/docs/reference/api/hook/add.md b/docs/reference/api/hook/add.md new file mode 100644 index 0000000..33d3c90 --- /dev/null +++ b/docs/reference/api/hook/add.md @@ -0,0 +1,159 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a hook. +--- + +## Endpoint + +``` +POST /api/v1/hooks/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### File + +```json +{ + "number": 1, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "host": "github.com", + "event": "push", + "branch": "main", + "status": "success" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/hooks/github/octocat" +``` + +#### Response + +```json +{ + "id": 2, + "number": 2, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "success", + "link": "", + "repo": { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + "build": { + "id": 10, + "repo": { + "id": 1, + }, + "number": 5, + "parent": 4, + "event": "push", + "status": "created", + "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": "" + } +} +``` diff --git a/docs/reference/api/hook/get.md b/docs/reference/api/hook/get.md new file mode 100644 index 0000000..17ad1b6 --- /dev/null +++ b/docs/reference/api/hook/get.md @@ -0,0 +1,146 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list hooks. +--- + +## Endpoint + +``` +GET /api/v1/hooks/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/hooks/github/octocat" +``` + +#### Response + +```json +[ + { + "id": 2, + "number": 2, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "success", + "link": "", + "repo": { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + "build": { + "id": 10, + "repo": { + "id": 1, + }, + "number": 5, + "parent": 4, + "event": "push", + "status": "created", + "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": "" + } + } +] +``` diff --git a/docs/reference/api/hook/hook.md b/docs/reference/api/hook/hook.md new file mode 100644 index 0000000..abd81c6 --- /dev/null +++ b/docs/reference/api/hook/hook.md @@ -0,0 +1,14 @@ +--- +title: "Hook" +linkTitle: "Hook" +description: > + Learn how to use API endpoints for the hook resource. +--- + +The below endpoints are available to operate on the `hook` resource. + +:::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/). +::: diff --git a/docs/reference/api/hook/remove.md b/docs/reference/api/hook/remove.md new file mode 100644 index 0000000..e394c46 --- /dev/null +++ b/docs/reference/api/hook/remove.md @@ -0,0 +1,56 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a hook. +--- + +## Endpoint + +``` +DELETE /api/v1/hooks/:org/:repo/:hook +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `hook` | number of hook | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" +``` + +#### Response + +```sh +Hook github/octocat/1 deleted +``` diff --git a/docs/reference/api/hook/update.md b/docs/reference/api/hook/update.md new file mode 100644 index 0000000..e3b0cf8 --- /dev/null +++ b/docs/reference/api/hook/update.md @@ -0,0 +1,155 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a hook. +--- + +## Endpoint + +``` +PUT /api/v1/hooks/:org/:repo/:hook +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `hook` | number of hook | + +## 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/). +::: + +#### File + +```json +{ + "status": "failure" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" +``` + +#### Response + +```json +{ + "id": 2, + "number": 2, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "success", + "link": "", + "repo": { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + "build": { + "id": 10, + "repo": { + "id": 1, + }, + "number": 5, + "parent": 4, + "event": "push", + "status": "created", + "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": "" + } +} +``` diff --git a/docs/reference/api/hook/view.md b/docs/reference/api/hook/view.md new file mode 100644 index 0000000..5bd6bbf --- /dev/null +++ b/docs/reference/api/hook/view.md @@ -0,0 +1,145 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a hook. +--- + +## Endpoint + +``` +GET /api/v1/hooks/:org/:repo/:hook +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `hook` | number of hook | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/hooks/github/octocat/1" +``` + +#### Response + +```json +{ + "id": 2, + "number": 2, + "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8", + "created": "1563474076", + "host": "github.com", + "event": "push", + "branch": "main", + "error": "", + "status": "success", + "link": "", + "repo": { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + "build": { + "id": 10, + "repo": { + "id": 1, + }, + "number": 5, + "parent": 4, + "event": "push", + "status": "created", + "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": "" + } +} +``` diff --git a/docs/reference/api/metrics/metrics.md b/docs/reference/api/metrics/metrics.md new file mode 100644 index 0000000..aa464f5 --- /dev/null +++ b/docs/reference/api/metrics/metrics.md @@ -0,0 +1,71 @@ +--- +title: "Metrics" +linkTitle: "Metrics" +description: > + Learn how to list metrics. +--- + +## Endpoint + +``` +GET /metrics +``` + +## Query Parameters + +The following parameters are used to configure the endpoint: + +| Query Parameter | Description | +| ------------------------ | ----------------------------------------------------------------------------- | +| `user_count` | count of total users | +| `repo_count` | count of total repos | +| `build_count` | count of total builds | +| `running_build_count` | count of builds with status 'running' | +| `failure_build_count` | count of builds with status 'failure' | +| `pending_build_count` | count of builds with status 'pending' | +| `queued_build_count` | count of builds inside the queue | +| `killed_build_count` | count of builds with status 'killed' | +| `success_build_count` | count of builds with status 'success' | +| `error_build_count` | count of builds with status 'error' | +| `step_image_count` | count of total steps executed with each unique image | +| `step_status_count` | count of total steps with each status | +| `service_image_count` | count of total services executed with each unique image | +| `service_status_count` | count of total services with each status | +| `worker_build_limit` | count of worker build limits | +| `active_worker_count` | count of active workers | +| `inactive_worker_count` | count of inactive workers | +| `idle_worker_count` | count of workers with a status of idle (no running builds) | +| `available_worker_count` | count of workers with a status of available (one or more available executors) | +| `busy_worker_count` | count of workers with a status of busy (no available executors) | +| `error_worker_count` | count of workers with a status of error | + +## Permissions + +No permission restrictions for this endpoint. + +## Responses + +| Status Code | Description | +| ----------- | ------------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `500` | indicates a server failure while processing the request | + +## Sample + +#### Request + +```sh +curl \ + -X GET \ + "http://127.0.0.1:8080/metrics?pending_build_count=true" +``` + +#### Response + +```json +# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles. +# TYPE go_gc_duration_seconds summary +go_gc_duration_seconds{quantile="0"} 4.0986e-05 +# TYPE vela_totals gauge +vela_totals{field="status",resource="build",value="pending"} 31 +``` diff --git a/docs/reference/api/pipeline/add.md b/docs/reference/api/pipeline/add.md new file mode 100644 index 0000000..0950be2 --- /dev/null +++ b/docs/reference/api/pipeline/add.md @@ -0,0 +1,86 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a pipeline. +--- + +## Endpoint + +``` +POST /api/v1/pipelines/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|----------------------| +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### File + +```json +{ + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "steps": true, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "flavor": "", + "platform": "", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "external_secrets": false, + "internal_secrets": false, + "services": false, + "stages": false, + "steps": true, + "templates": false, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" +} +``` diff --git a/docs/reference/api/pipeline/compile.md b/docs/reference/api/pipeline/compile.md new file mode 100644 index 0000000..6fa249e --- /dev/null +++ b/docs/reference/api/pipeline/compile.md @@ -0,0 +1,212 @@ +--- +title: "Compile" +linkTitle: "Compile" +description: > + Learn how to compile a pipeline configuration with templates. +--- + +## Endpoint + +``` +POST /api/v1/pipelines/:org/:repo/:pipeline/compile +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | +| `output` | format the output for the compiled pipeline configuration | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve or compile the pipeline configuration and templates | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve or compile the pipeline configuration or templates | +| `500` | system error while retrieving or compiling the pipeline configuration templates | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/compile" +``` + +#### Response + +:::warning +Notice, when compiling a pipeline configuration step fields such as `image` and `commands` will be arranged in alphabetical order. +::: + +```yaml +version: "1" +secrets: +- name: go_module + key: github/octocat/template_secret + engine: native + type: repo +steps: +- commands: + - go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) + - go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) + image: golang:latest + name: go_validate + pull: not_present +- commands: + - go test ./... + image: golang:latest + name: go_test + pull: not_present +- commands: + - go build -a -ldflags '-extldflags "-static"' -o release/heyvela {$GO_MODULE} + image: golang:latest + name: go_build + pull: not_present + environment: + CGO_ENABLED: "0" + GOOS: linux +templates: +- name: go + source: github.com/github/octocat/go/template.yml + type: github +``` + +```json +{ + "version": "1", + "metadata": {}, + "worker": {}, + "secrets": [ + { + "name": "go_module", + "key": "github/octocat/template_secret", + "engine": "native", + "type": "repo", + "origin": { + "ruleset": { + "if": {}, + "unless": {} + } + } + } + ], + "steps": [ + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", + "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" + ], + "template": {}, + "image": "golang:latest", + "name": "go_validate", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go test ./..." + ], + "template": {}, + "image": "golang:latest", + "name": "go_test", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" + ], + "template": {}, + "image": "golang:latest", + "name": "go_build", + "pull": "not_present", + "environment": { + "CGO_ENABLED": "0", + "GOOS": "linux" + } + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", + "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" + ], + "template": {}, + "image": "golang:latest", + "name": "go-tag_validate", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go test ./..." + ], + "template": {}, + "image": "golang:latest", + "name": "go-tag_test", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" + ], + "template": {}, + "image": "golang:latest", + "name": "go-tag_build", + "pull": "not_present", + "environment": { + "CGO_ENABLED": "0", + "GOOS": "linux" + } + }, + ], + "templates": [ + { + "name": "go", + "source": "github.com/github/octocat/go/template.yml", + "type": "github" + } + ] +} +``` \ No newline at end of file diff --git a/docs/reference/api/pipeline/expand.md b/docs/reference/api/pipeline/expand.md new file mode 100644 index 0000000..d571a9f --- /dev/null +++ b/docs/reference/api/pipeline/expand.md @@ -0,0 +1,168 @@ +--- +title: "Expand" +linkTitle: "Expand" +description: > + Learn how to expand a pipeline configuration with templates. +--- + +## Endpoint + +``` +POST /api/v1/pipelines/:org/:repo/:pipeline/expand +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | +| `output` | format the output for the compiled pipeline configuration | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve or expand the pipeline configuration and templates | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve or expand the pipeline configuration or templates | +| `500` | system error while retrieving or expanding the pipeline configuration templates | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/expand" +``` + +#### Response + +:::warning +Notice, when expanding a pipeline configuration step fields such as `image` and `commands` will be arranged in alphabetical order. +::: + +```yaml +version: "1" +secrets: +- name: go_module + key: github/octocat/template_secret + engine: native + type: repo +steps: +- commands: + - go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) + - go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code) + image: golang:latest + name: go_validate + pull: not_present +- commands: + - go test ./... + image: golang:latest + name: go_test + pull: not_present +- commands: + - go build -a -ldflags '-extldflags "-static"' -o release/heyvela {$GO_MODULE} + image: golang:latest + name: go_build + pull: not_present + environment: + CGO_ENABLED: "0" + GOOS: linux +templates: +- name: go + source: github.com/github/octocat/go/template.yml + type: github +``` + +```json +{ + "version": "1", + "metadata": {}, + "worker": {}, + "secrets": [ + { + "name": "go_module", + "key": "github/octocat/template_secret", + "engine": "native", + "type": "repo", + "origin": { + "ruleset": { + "if": {}, + "unless": {} + } + } + } + ], + "steps": [ + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go vet ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)", + "go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)" + ], + "template": {}, + "image": "golang:latest", + "name": "go_validate", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go test ./..." + ], + "template": {}, + "image": "golang:latest", + "name": "go_test", + "pull": "not_present" + }, + { + "ruleset": { + "if": {}, + "unless": {} + }, + "commands": [ + "go build -a -ldflags '-extldflags \"-static\"' -o release/heyvela {$GO_MODULE}" + ], + "template": {}, + "image": "golang:latest", + "name": "go_build", + "pull": "not_present", + "environment": { + "CGO_ENABLED": "0", + "GOOS": "linux" + } + }, + ], + "templates": [ + { + "name": "go", + "source": "github.com/github/octocat/go/template.yml", + "type": "github" + } + ] +} +``` \ No newline at end of file diff --git a/docs/reference/api/pipeline/get.md b/docs/reference/api/pipeline/get.md new file mode 100644 index 0000000..a5cbcfa --- /dev/null +++ b/docs/reference/api/pipeline/get.md @@ -0,0 +1,93 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list pipelines. +--- + +## Endpoint + +``` +GET /api/v1/pipelines/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|----------------------| +| `org` | name of organization | +| `repo` | name of repository | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- |----------------------------------------------------------| +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve the pipeline configuration | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve the pipeline configuration | +| `500` | system error while retrieving the pipeline configuration | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat" +``` + +#### Response + +```json +[ + { + "id": 2, + "repo_id": 1, + "commit": "a49aaf4afae6431a79239c95247a2b169fd9f067", + "flavor": "", + "platform": "", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "external_secrets": false, + "internal_secrets": false, + "services": false, + "stages": false, + "steps": true, + "templates": false, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" + }, + { + "id": 1, + "repo_id": 1, + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "flavor": "", + "platform": "", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "external_secrets": false, + "internal_secrets": false, + "services": false, + "stages": false, + "steps": true, + "templates": false, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" + } +] +``` \ No newline at end of file diff --git a/docs/reference/api/pipeline/pipeline.md b/docs/reference/api/pipeline/pipeline.md new file mode 100644 index 0000000..4395b59 --- /dev/null +++ b/docs/reference/api/pipeline/pipeline.md @@ -0,0 +1,14 @@ +--- +title: "Pipeline" +linkTitle: "Pipeline" +description: > + Learn how to use API endpoints for the pipeline resource. +--- + +The below endpoints are available to operate on the `pipeline` resource. + +:::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/). +::: diff --git a/docs/reference/api/pipeline/remove.md b/docs/reference/api/pipeline/remove.md new file mode 100644 index 0000000..3ebb327 --- /dev/null +++ b/docs/reference/api/pipeline/remove.md @@ -0,0 +1,56 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a pipeline. +--- + +## Endpoint + +``` +DELETE /api/v1/pipelines/:org/:repo/:pipeline +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" +``` + +#### Response + +```sh +Pipeline github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163 deleted +``` diff --git a/docs/reference/api/pipeline/templates.md b/docs/reference/api/pipeline/templates.md new file mode 100644 index 0000000..2a913ef --- /dev/null +++ b/docs/reference/api/pipeline/templates.md @@ -0,0 +1,75 @@ +--- +title: "Templates" +linkTitle: "Templates" +description: > + Learn how to list pipeline templates. +--- + +## Endpoint + +``` +GET /api/v1/pipelines/:org/:repo/:pipeline/templates +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | +| `output` | format the output for the compiled pipeline configuration | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- |--------------------------------------------------------------------| +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve the pipeline configuration templates | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve the pipeline configuration or templates | +| `500` | system error while retrieving the pipeline configuration templates | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/templates" +``` + +#### Response + +```yaml +some_template: + link: https://github.com/github/octocat/blob/main/template.yml + name: some_template + source: github.com/github/octocat/template.yml + type: github +``` + +```json +{ + "some_template": { + "link": "https://github.com/github/octocat/blob/main/template.yml", + "name": "some_template", + "source": "github.com/github/octocat/template.yml", + "type": "github" + }, +} +``` \ No newline at end of file diff --git a/docs/reference/api/pipeline/update.md b/docs/reference/api/pipeline/update.md new file mode 100644 index 0000000..94a4ad2 --- /dev/null +++ b/docs/reference/api/pipeline/update.md @@ -0,0 +1,82 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a pipeline. +--- + +## Endpoint + +``` +PUT /api/v1/pipelines/:org/:repo/:pipeline +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | + +## 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/). +::: + +#### File + +```json +{ + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgZW52aXJvbm1lbnQ6CiAgICAgIEhFTExPOiB3b3JsZAogICAgY29tbWFuZHM6IFtlY2hvICRIRUxMT10=" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "flavor": "", + "platform": "", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "external_secrets": false, + "internal_secrets": false, + "services": false, + "stages": false, + "steps": true, + "templates": false, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgZW52aXJvbm1lbnQ6CiAgICAgIEhFTExPOiB3b3JsZAogICAgY29tbWFuZHM6IFtlY2hvICRIRUxMT10=" +} +``` diff --git a/docs/reference/api/pipeline/validate.md b/docs/reference/api/pipeline/validate.md new file mode 100644 index 0000000..bf5ed7f --- /dev/null +++ b/docs/reference/api/pipeline/validate.md @@ -0,0 +1,60 @@ +--- +title: "Validate" +linkTitle: "Validate" +description: > + Learn how to validate a pipeline configuration with templates. +--- + +## Endpoint + +``` +POST /api/v1/pipelines/:org/:repo/:pipeline/validate +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | +| `output` | format the output for the compiled pipeline configuration | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve or validate the pipeline configuration and templates | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve or validate the pipeline configuration or templates | +| `500` | system error while retrieving or validating the pipeline configuration templates | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163/validate" +``` + +#### Response + +``` +"pipeline is valid" +``` \ No newline at end of file diff --git a/docs/reference/api/pipeline/view.md b/docs/reference/api/pipeline/view.md new file mode 100644 index 0000000..db462af --- /dev/null +++ b/docs/reference/api/pipeline/view.md @@ -0,0 +1,74 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a pipeline. +--- + +## Endpoint + +``` +GET /api/v1/pipelines/:org/:repo/:pipeline +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|-----------------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `pipeline` | commit SHA for pipeline from repository | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +| ----------- |----------------------------------------------------------| +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve the pipeline configuration | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve the pipeline configuration | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/pipelines/github/octocat/48afb5bdc41ad69bf22588491333f7cf71135163" +``` + +#### Response + +```json +{ + "id": 1, + "repo_id": 1, + "commit": "48afb5bdc41ad69bf22588491333f7cf71135163", + "flavor": "", + "platform": "", + "ref": "refs/heads/main", + "type": "yaml", + "version": "1", + "external_secrets": false, + "internal_secrets": false, + "services": false, + "stages": false, + "steps": true, + "templates": false, + "data": "LS0tCnZlcnNpb246ICIxIgoKc3RlcHM6CiAgLSBuYW1lOiBlY2hvCiAgICBpbWFnZTogYWxwaW5lOmxhdGVzdAogICAgY29tbWFuZHM6IFtlY2hvIGZvb10=" +} +``` \ No newline at end of file diff --git a/docs/reference/api/repo/add.md b/docs/reference/api/repo/add.md new file mode 100644 index 0000000..08586e0 --- /dev/null +++ b/docs/reference/api/repo/add.md @@ -0,0 +1,107 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a repo. +--- + +## Endpoint + +``` +POST /api/v1/repos +``` + +## 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/). +::: + +#### File + +```json +{ + "org": "github", + "name": "octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos" +``` + +#### Response + +```json +{ + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" +} +``` diff --git a/docs/reference/api/repo/chown.md b/docs/reference/api/repo/chown.md new file mode 100644 index 0000000..da873f3 --- /dev/null +++ b/docs/reference/api/repo/chown.md @@ -0,0 +1,55 @@ +--- +title: "Chown" +linkTitle: "Chown" +description: > + Learn how to change ownership of a repo. +--- + +## Endpoint + +``` +PATCH /api/v1/repos/:org/:repo/chown +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X PATCH \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/chown" +``` + +#### Response + +``` +Repo github/octocat changed owner +``` diff --git a/docs/reference/api/repo/get.md b/docs/reference/api/repo/get.md new file mode 100644 index 0000000..8084b55 --- /dev/null +++ b/docs/reference/api/repo/get.md @@ -0,0 +1,313 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list repos by current user or by organization. +--- + +## Endpoint + +``` +GET /api/v1/repos +``` +This will return a list of all repos owned by the user. + +## Filters + +The following optional filters are available: + +| Name | Description | +| -------- | ----------------------------------------------------------------------- | +| `page` | page number for results (default 1) | +| `per_page` | number of results in a page (default 10, max 100) | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos" +``` + +#### Response + +```json +[ + { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + { + "id": 2, + "user_id": 1, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + } +] +``` + +## Endpoint + +``` +GET /api/v1/repos/:org +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | + +## Filters + +The following optional filters are available: + +| Name | Description | +| -------- | ----------------------------------------------------------------------------------- | +| `active` | filter whether repos are active (default true) | +| `page` | page number for results (default 1) | +| `per_page` | number of results in a page (default 10, max 100) | +| `sort_by` | sort repos by `name` (default) or by `latest`, which sorts by latest build activity | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/octocat" +``` + +#### Response + +```json +[ + { + "id": 1, + "user_id": 1, + "org": "octocat", + "name": "example", + "full_name": "octocat/example", + "link": "https://github.com/octocat/example", + "clone": "https://github.com/octocat/example.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + }, + { + "id": 2, + "user_id": 1, + "org": "octocat", + "name": "octokitty", + "full_name": "octocat/octokitty", + "link": "https://github.com/octocat/octokitty", + "clone": "https://github.com/octocat/octokitty.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" + } +] +``` diff --git a/docs/reference/api/repo/remove.md b/docs/reference/api/repo/remove.md new file mode 100644 index 0000000..52499c7 --- /dev/null +++ b/docs/reference/api/repo/remove.md @@ -0,0 +1,55 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a repo. +--- + +## Endpoint + +``` +DELETE /api/v1/repos/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat" +``` + +#### Response + +``` +Repo github/octocat deleted +``` diff --git a/docs/reference/api/repo/repair.md b/docs/reference/api/repo/repair.md new file mode 100644 index 0000000..7f4c59b --- /dev/null +++ b/docs/reference/api/repo/repair.md @@ -0,0 +1,55 @@ +--- +title: "Repair" +linkTitle: "Repair" +description: > + Learn how to restore a repo. +--- + +## Endpoint + +``` +PATCH /api/v1/repos/:org/:repo/repair +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X PATCH \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/repair" +``` + +#### Response + +``` +Repo github/octocat repaired +``` diff --git a/docs/reference/api/repo/repo.md b/docs/reference/api/repo/repo.md new file mode 100644 index 0000000..e53a2aa --- /dev/null +++ b/docs/reference/api/repo/repo.md @@ -0,0 +1,14 @@ +--- +title: "Repo" +linkTitle: "Repo" +description: > + Learn how to use API endpoints for the repo resource. +--- + +The below endpoints are available to operate on the `repo` resource. + +:::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/). +::: diff --git a/docs/reference/api/repo/update.md b/docs/reference/api/repo/update.md new file mode 100644 index 0000000..7f1a618 --- /dev/null +++ b/docs/reference/api/repo/update.md @@ -0,0 +1,113 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a repo. +--- + +## Endpoint + +``` +PUT /api/v1/repos/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### File + +```json +{ + "allow_tag": true +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat" +``` + +#### Response + +```json +{ + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": true, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" +} +``` diff --git a/docs/reference/api/repo/view.md b/docs/reference/api/repo/view.md new file mode 100644 index 0000000..b34855d --- /dev/null +++ b/docs/reference/api/repo/view.md @@ -0,0 +1,103 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a repo. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat" +``` + +#### Response + +```json +{ + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "build_limit": 10, + "timeout": 60, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml" +} +``` diff --git a/docs/reference/api/schedule/add.md b/docs/reference/api/schedule/add.md new file mode 100644 index 0000000..a3f3f72 --- /dev/null +++ b/docs/reference/api/schedule/add.md @@ -0,0 +1,131 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a schedule. +--- + +## Endpoint + +``` +POST /api/v1/schedules/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|--------|----------------------| +| `org` | name of organization | +| `repo` | name of repository | + +## 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/). +::: + +#### File + +```json +{ + "name": "hourly", + "entry": "0 * * * *", + "active": true +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/schedules/github/octocat" +``` + +#### Response + +```json +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` \ No newline at end of file diff --git a/docs/reference/api/schedule/get.md b/docs/reference/api/schedule/get.md new file mode 100644 index 0000000..57e71fc --- /dev/null +++ b/docs/reference/api/schedule/get.md @@ -0,0 +1,189 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list schedules. +--- + +## Endpoint + +``` +GET /api/v1/schedules/:org/:repo +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|--------|----------------------| +| `org` | name of organization | +| `repo` | name of repository | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +|-------------|-----------------------------------------------------| +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve the schedules | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve the schedules | +| `500` | system error while retrieving the schedules | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/schedules/github/octocat" +``` + +#### Response + +```json +[ + { + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 + }, + { + "id": 2, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "nightly", + "entry": "0 0 * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 + } +] +``` \ No newline at end of file diff --git a/docs/reference/api/schedule/remove.md b/docs/reference/api/schedule/remove.md new file mode 100644 index 0000000..3524b5a --- /dev/null +++ b/docs/reference/api/schedule/remove.md @@ -0,0 +1,56 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a schedule. +--- + +## Endpoint + +``` +DELETE /api/v1/schedules/:org/:repo/:schedule +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|----------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `schedule` | name of schedule from repository | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" +``` + +#### Response + +```sh +"schedule hourly deleted" +``` \ No newline at end of file diff --git a/docs/reference/api/schedule/schedule.md b/docs/reference/api/schedule/schedule.md new file mode 100644 index 0000000..4a1e7cf --- /dev/null +++ b/docs/reference/api/schedule/schedule.md @@ -0,0 +1,14 @@ +--- +title: "Schedule" +linkTitle: "Schedule" +description: > + Learn how to use API endpoints for the schedule resource. +--- + +The below endpoints are available to operate on the `schedule` resource. + +:::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/). +::: \ No newline at end of file diff --git a/docs/reference/api/schedule/update.md b/docs/reference/api/schedule/update.md new file mode 100644 index 0000000..d14930c --- /dev/null +++ b/docs/reference/api/schedule/update.md @@ -0,0 +1,130 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a schedule. +--- + +## Endpoint + +``` +PUT /api/v1/schedules/:org/:repo/:schedule +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|----------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `schedule` | name of schedule from repository | + +## 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/). +::: + +#### File + +```json +{ + "active": false +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" +``` + +#### Response + +```json +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": false, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` \ No newline at end of file diff --git a/docs/reference/api/schedule/view.md b/docs/reference/api/schedule/view.md new file mode 100644 index 0000000..3ff1562 --- /dev/null +++ b/docs/reference/api/schedule/view.md @@ -0,0 +1,122 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a schedule. +--- + +## Endpoint + +``` +GET /api/v1/schedules/:org/:repo/:schedule +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +|------------|----------------------------------| +| `org` | name of organization | +| `repo` | name of repository | +| `schedule` | name of schedule from repository | + +## Permissions + +COMING SOON! + +## Responses + +| Status Code | Description | +|-------------|-----------------------------------------------------| +| `200` | indicates the request has succeeded | +| `400` | unable to retrieve the schedule | +| `401` | indicates the user does not have proper permissions | +| `404` | unable to retrieve the schedule | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/schedules/github/octocat/hourly" +``` + +#### Response + +```json +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` \ No newline at end of file diff --git a/docs/reference/api/scm/scm.md b/docs/reference/api/scm/scm.md new file mode 100644 index 0000000..ade0776 --- /dev/null +++ b/docs/reference/api/scm/scm.md @@ -0,0 +1,14 @@ +--- +title: "SCM" +linkTitle: "SCM" +description: > + Learn how to use API endpoints for the SCM resource. +--- + +The below endpoints are available to operate on the `scm` resource. + +:::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/). +::: \ No newline at end of file diff --git a/docs/reference/api/scm/sync.md b/docs/reference/api/scm/sync.md new file mode 100644 index 0000000..ab86f23 --- /dev/null +++ b/docs/reference/api/scm/sync.md @@ -0,0 +1,63 @@ +--- +title: "Sync" +linkTitle: "Sync" +description: > + Learn how to sync a repo with SCM. +--- + +## Endpoint + +``` +PATCH /api/v1/scm/repos/:org/:repo/sync +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | + +## Description + +The sync endpoint allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. + +Further, as of `v0.19.0`, the sync endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like + +```sh +"unable to process webhook: / does not have comment events enabled" +``` + +hitting the sync endpoint should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed. + +## 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/). +::: + +#### Request + +```sh +curl \ + -X PATCH \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/scm/repos/github/octocat/sync" +``` + +#### Response + +```sh +repo "github/octocat" synced +``` \ No newline at end of file diff --git a/docs/reference/api/scm/syncAll.md b/docs/reference/api/scm/syncAll.md new file mode 100644 index 0000000..6c8be4b --- /dev/null +++ b/docs/reference/api/scm/syncAll.md @@ -0,0 +1,62 @@ +--- +title: "SyncAll" +linkTitle: "SyncAll" +description: > + Learn how to sync org repos with SCM. +--- + +## Endpoint + +``` +GET /api/v1/scm/orgs/:org/sync +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | -------------------- | +| `org` | name of organization | + +## Responses + +| Status Code | Description | +| ----------- | --------------------------------------------------- | +| `200` | indicates the request has succeeded | +| `401` | indicates the user does not have proper permissions | + +## Description + +The sync-all endpoint allows users to re-align their organization's repositories in Vela with their SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. + +Further, as of `v0.19.0`, the sync-all endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like + +```sh +"unable to process webhook: / does not have comment events enabled" +``` + +hitting the sync-all endpoint should re-configure the SCM webhook for all repos in the organization to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed. + +## 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/). +::: + +#### Request + +```sh +curl \ + -X PATCH \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/scm/orgs/github/sync" +``` + +#### Response + +```sh +org "github" synced +``` diff --git a/docs/reference/api/secret/add.md b/docs/reference/api/secret/add.md new file mode 100644 index 0000000..8601f77 --- /dev/null +++ b/docs/reference/api/secret/add.md @@ -0,0 +1,112 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a secret. +--- + +## Endpoint + +``` +POST /api/v1/secrets/:engine/:type/:org/:name +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| -------- | -------------------------- | +| `engine` | name of engine | +| `type` | name of type of secret | +| `org` | name of organization | +| `name` | name of repository or team | + +## 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/). +::: + +#### File + +```json +{ + "name": "foo", + "value": "bar", + "images": ["alpine"], + "events": ["push"] +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" + "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat" +``` + +#### Response + +```json +{ + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": null, + "type": "repo", + "images": ["alpine"], + "events": ["push"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314085, + "updated_by": "octokitty" +} +``` diff --git a/docs/reference/api/secret/get.md b/docs/reference/api/secret/get.md new file mode 100644 index 0000000..7042e90 --- /dev/null +++ b/docs/reference/api/secret/get.md @@ -0,0 +1,144 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list secrets. +--- + +## Endpoint + +``` +GET /api/v1/secrets/:engine/:type/:org/:name +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| -------- | -------------------------- | +| `engine` | name of engine | +| `type` | name of type of secret | +| `org` | name of organization | +| `name` | name of repository or team | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat" +``` + +#### Response + +```json +[ + { + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": null, + "type": "repo", + "images": ["alpine"], + "events": ["push"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314085, + "updated_by": "octokitty" + }, + { + "id": 2, + "org": "github", + "repo": "octocat", + "team": "", + "name": "bar", + "value": null, + "type": "repo", + "images": ["alpine"], + "events": ["push"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314500, + "created_by": "octokitty", + "updated_at": 1641314500, + "updated_by": "octokitty" + } +] +``` diff --git a/docs/reference/api/secret/remove.md b/docs/reference/api/secret/remove.md new file mode 100644 index 0000000..e28a56c --- /dev/null +++ b/docs/reference/api/secret/remove.md @@ -0,0 +1,58 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a secret. +--- + +## Endpoint + +``` +DELETE /api/v1/secrets/:engine/:type/:org/:name/:secret +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| -------- | -------------------------- | +| `engine` | name of engine | +| `type` | name of type of secret | +| `org` | name of organization | +| `name` | name of repository or team | +| `secret` | name of secret | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" +``` + +#### Response + +```json +Secret repo/github/octocat/foo deleted from native service +``` diff --git a/docs/reference/api/secret/secret.md b/docs/reference/api/secret/secret.md new file mode 100644 index 0000000..f108bbd --- /dev/null +++ b/docs/reference/api/secret/secret.md @@ -0,0 +1,14 @@ +--- +title: "Secret" +linkTitle: "Secret" +description: > + Learn how to use API endpoints for the secret resource. +--- + +The below endpoints are available to operate on the `secret` resource. + +:::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/). +::: diff --git a/docs/reference/api/secret/update.md b/docs/reference/api/secret/update.md new file mode 100644 index 0000000..3618b4a --- /dev/null +++ b/docs/reference/api/secret/update.md @@ -0,0 +1,110 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a secret. +--- + +## Endpoint + +``` +PUT /api/v1/secrets/:engine/:type/:org/:name/:secret +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| -------- | -------------------------- | +| `engine` | name of engine | +| `type` | name of type of secret | +| `org` | name of organization | +| `name` | name of repository or team | +| `secret` | name of secret | + +## 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/). +::: + +#### File + +```json +{ + "allow_command": false +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" + "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" +``` + +#### Response + +```json +{ + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": "", + "type": "repo", + "images": ["alpine"], + "events": ["push", "tag"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314500, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/secret/view.md b/docs/reference/api/secret/view.md new file mode 100644 index 0000000..bf2e4d6 --- /dev/null +++ b/docs/reference/api/secret/view.md @@ -0,0 +1,100 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a secret. +--- + +## Endpoint + +``` +GET /api/v1/secrets/:engine/:type/:org/:name/:secret +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| -------- | -------------------------- | +| `engine` | name of engine | +| `type` | name of type of secret | +| `org` | name of organization | +| `name` | name of repository or team | +| `secret` | name of secret | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/secrets/native/repo/github/octocat/foo" +``` + +#### Response + +```json +{ + "id": 1, + "org": "github", + "repo": "octocat", + "team": "", + "name": "foo", + "value": "", + "type": "repo", + "images": ["alpine"], + "events": ["push"], + "allow_command": true, + "allow_substitution": true, + "allow_events": { + "push": { + "branch": true, + "tag": true, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": true + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "created_at": 1641314085, + "created_by": "octokitty", + "updated_at": 1641314500, + "updated_by": "octocat" +} +``` diff --git a/docs/reference/api/service/add.md b/docs/reference/api/service/add.md new file mode 100644 index 0000000..b5fec5e --- /dev/null +++ b/docs/reference/api/service/add.md @@ -0,0 +1,79 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a service. +--- + +## Endpoint + +``` +POST /api/v1/repos/:org/:repo/builds/:build/services +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### File + +```json +{ + "number": 1, + "name": "clone" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 +} +``` diff --git a/docs/reference/api/service/get.md b/docs/reference/api/service/get.md new file mode 100644 index 0000000..52585bd --- /dev/null +++ b/docs/reference/api/service/get.md @@ -0,0 +1,83 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list services. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/services +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services" +``` + +#### Response + +```json +[ + { + "id": 2, + "build_id": 1, + "repo_id": 1, + "number": 2, + "name": "build", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 + }, + { + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 + } +] +``` diff --git a/docs/reference/api/service/logs.md b/docs/reference/api/service/logs.md new file mode 100644 index 0000000..6d0931e --- /dev/null +++ b/docs/reference/api/service/logs.md @@ -0,0 +1,69 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: > + Learn how to view logs for a service. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/services/:service/logs +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| --------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `service` | number of service | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1/logs" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "service_id": 1, + "data": "SGVsbG8sIFdvcmxkIQ==" +} +``` + +The `data` field is base64 encoded. To decode the data, you can use the following command: + +```sh +echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode +``` diff --git a/docs/reference/api/service/remove.md b/docs/reference/api/service/remove.md new file mode 100644 index 0000000..495ca47 --- /dev/null +++ b/docs/reference/api/service/remove.md @@ -0,0 +1,57 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a service. +--- + +## Endpoint + +``` +DELETE /api/v1/repos/:org/:repo/builds/:build/services/:service +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| --------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `service` | number of service | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" +``` + +#### Response + +``` +Service github/octocat/1/1 deleted +``` diff --git a/docs/reference/api/service/service.md b/docs/reference/api/service/service.md new file mode 100644 index 0000000..d6f24bc --- /dev/null +++ b/docs/reference/api/service/service.md @@ -0,0 +1,14 @@ +--- +title: "Service" +linkTitle: "Service" +description: > + Learn how to use API endpoints for the service resource. +--- + +The below endpoints are available to operate on the `service` resource. + +:::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/). +::: diff --git a/docs/reference/api/service/update.md b/docs/reference/api/service/update.md new file mode 100644 index 0000000..dfc798d --- /dev/null +++ b/docs/reference/api/service/update.md @@ -0,0 +1,79 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a service. +--- + +## Endpoint + +``` +PUT /api/v1/repos/:org/:repo/builds/:build/services/:service +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| --------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `service` | number of service | + +## 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/). +::: + +#### File + +```json +{ + "status": "failure" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 +} +``` diff --git a/docs/reference/api/service/view.md b/docs/reference/api/service/view.md new file mode 100644 index 0000000..835aad6 --- /dev/null +++ b/docs/reference/api/service/view.md @@ -0,0 +1,69 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a service. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/services/:service +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| --------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `service` | number of service | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/services/1" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 1563475420, + "finished": 1563475421 +} +``` diff --git a/docs/reference/api/step/add.md b/docs/reference/api/step/add.md new file mode 100644 index 0000000..82db72c --- /dev/null +++ b/docs/reference/api/step/add.md @@ -0,0 +1,82 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a step. +--- + +## Endpoint + +``` +POST /api/v1/repos/:org/:repo/builds/:build/steps +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### File + +```json +{ + "number": 1, + "name": "clone" +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/step/get.md b/docs/reference/api/step/get.md new file mode 100644 index 0000000..73d096a --- /dev/null +++ b/docs/reference/api/step/get.md @@ -0,0 +1,89 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list steps. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/steps +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps" +``` + +#### Response + +```json +[ + { + "id": 2, + "build_id": 1, + "repo_id": 1, + "number": 2, + "name": "build", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" + }, + { + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" + } +] +``` diff --git a/docs/reference/api/step/logs.md b/docs/reference/api/step/logs.md new file mode 100644 index 0000000..0245c0b --- /dev/null +++ b/docs/reference/api/step/logs.md @@ -0,0 +1,69 @@ +--- +title: "Logs" +linkTitle: "Logs" +description: > + Learn how to view step logs. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/steps/:step/logs +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `step` | number of step | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1/logs" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "step_id": 1, + "data": "SGVsbG8sIFdvcmxkIQ==" +} +``` + +The `data` field is base64 encoded. To decode the data, you can use the following command: + +```sh +echo "SGVsbG8sIFdvcmxkIQ==" | base64 --decode +``` diff --git a/docs/reference/api/step/remove.md b/docs/reference/api/step/remove.md new file mode 100644 index 0000000..8b8d83b --- /dev/null +++ b/docs/reference/api/step/remove.md @@ -0,0 +1,57 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a step. +--- + +## Endpoint + +``` +DELETE /api/v1/repos/:org/:repo/builds/:build/steps/:step +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `step` | number of step | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" +``` + +#### Response + +``` +Step github/octocat/1/1 deleted +``` diff --git a/docs/reference/api/step/step.md b/docs/reference/api/step/step.md new file mode 100644 index 0000000..1f73da7 --- /dev/null +++ b/docs/reference/api/step/step.md @@ -0,0 +1,14 @@ +--- +title: "Step" +linkTitle: "Step" +description: > + Learn how to use API endpoints for the step resource. +--- + +The below endpoints are available to operate on the `step` resource. + +:::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/). +::: diff --git a/docs/reference/api/step/update.md b/docs/reference/api/step/update.md new file mode 100644 index 0000000..e6aab7c --- /dev/null +++ b/docs/reference/api/step/update.md @@ -0,0 +1,82 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a step. +--- + +## Endpoint + +``` +PUT /api/v1/repos/:org/:repo/builds/:build/steps/:step +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `step` | number of step | + +## 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/). +::: + +#### File + +```json +{ + "status": "failure" +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "failure", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/step/view.md b/docs/reference/api/step/view.md new file mode 100644 index 0000000..d746ab1 --- /dev/null +++ b/docs/reference/api/step/view.md @@ -0,0 +1,72 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a step. +--- + +## Endpoint + +``` +GET /api/v1/repos/:org/:repo/builds/:build/steps/:step +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------- | -------------------- | +| `org` | name of organization | +| `repo` | name of repository | +| `build` | number of build | +| `step` | number of step | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/repos/github/octocat/builds/1/steps/1" +``` + +#### Response + +```json +{ + "id": 1, + "build_id": 1, + "repo_id": 1, + "number": 1, + "name": "clone", + "status": "success", + "error": "", + "exit_code": 0, + "created": 1563475419, + "started": 0, + "finished": 0, + "host": "company.localhost", + "runtime": "docker", + "distribution": "linux" +} +``` diff --git a/docs/reference/api/user/add.md b/docs/reference/api/user/add.md new file mode 100644 index 0000000..04bac56 --- /dev/null +++ b/docs/reference/api/user/add.md @@ -0,0 +1,66 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a user. +--- + +## Endpoint + +``` +POST /api/v1/users +``` + +## 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/). +::: + +#### File + +```json +{ + "name": "OctoKitty", + "favorites": ["github/octocat"], + "active": true, + "admin": false +} +``` + +#### Request + +```sh +curl \ + -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/users" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": false +} +``` diff --git a/docs/reference/api/user/current/current.md b/docs/reference/api/user/current/current.md new file mode 100644 index 0000000..121f12a --- /dev/null +++ b/docs/reference/api/user/current/current.md @@ -0,0 +1,14 @@ +--- +title: "Current" +linkTitle: "Current" +description: > + Learn how to use API endpoints for the current user. +--- + +The below endpoints are available to operate on for the current user. + +:::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/). +::: diff --git a/docs/reference/api/user/current/repos.md b/docs/reference/api/user/current/repos.md new file mode 100644 index 0000000..cd4afdd --- /dev/null +++ b/docs/reference/api/user/current/repos.md @@ -0,0 +1,87 @@ +--- +title: "Repos" +linkTitle: "Repos" +description: > + Learn how to list repos for the current user. +--- + +## Endpoint + +``` +GET /api/v1/user/source/repos +``` + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/user/source/repos" +``` + +#### Response + +```json +[ + { + "id": 1, + "user_id": 1, + "org": "github", + "name": "octocat", + "full_name": "github/octocat", + "link": "https://github.com/github/octocat", + "clone": "https://github.com/github/octocat.git", + "branch": "main", + "timeout": 60, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false + }, + { + "id": 2, + "user_id": 1, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "timeout": 60, + "visibility": "public", + "private": false, + "trusted": true, + "active": true, + "allow_pull": true, + "allow_push": true, + "allow_deploy": false, + "allow_tag": false, + "allow_comment": false + } +] +``` diff --git a/docs/reference/api/user/current/update.md b/docs/reference/api/user/current/update.md new file mode 100644 index 0000000..6f3f299 --- /dev/null +++ b/docs/reference/api/user/current/update.md @@ -0,0 +1,63 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify the current user. +--- + +## Endpoint + +``` +PUT /api/v1/user +``` + +## 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/). +::: + +#### File + +```json +{ + "admin": true +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/user" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": true +} +``` diff --git a/docs/reference/api/user/current/view.md b/docs/reference/api/user/current/view.md new file mode 100644 index 0000000..02f4cdb --- /dev/null +++ b/docs/reference/api/user/current/view.md @@ -0,0 +1,53 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect the current user. +--- + +## Endpoint + +``` +GET /api/v1/user +``` + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/user" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": false +} +``` diff --git a/docs/reference/api/user/get.md b/docs/reference/api/user/get.md new file mode 100644 index 0000000..4142a22 --- /dev/null +++ b/docs/reference/api/user/get.md @@ -0,0 +1,63 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list users. +--- + +## Endpoint + +``` +GET /api/v1/users +``` + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/users" +``` + +#### Response + +```json +[ + { + "id": 2, + "name": "octocat", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": false + }, + { + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": false + } +] +``` diff --git a/docs/reference/api/user/remove.md b/docs/reference/api/user/remove.md new file mode 100644 index 0000000..e45b232 --- /dev/null +++ b/docs/reference/api/user/remove.md @@ -0,0 +1,54 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a user. +--- + +## Endpoint + +``` +DELETE /api/v1/users/:user +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | ------------ | +| `user` | name of user | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X DELETE \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/users/OctoKitty" +``` + +#### Response + +```sh +User OctoKitty deleted +``` diff --git a/docs/reference/api/user/update.md b/docs/reference/api/user/update.md new file mode 100644 index 0000000..6b52015 --- /dev/null +++ b/docs/reference/api/user/update.md @@ -0,0 +1,71 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a user. +--- + +## Endpoint + +``` +PUT /api/v1/users/:user +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | ------------ | +| `user` | name of user | + +## 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/). +::: + +#### File + +```json +{ + "admin": true +} +``` + +#### Request + +```sh +curl \ + -X PUT \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d "@data.json" \ + "http://127.0.0.1:8080/api/v1/users/OctoKitty" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": true +} +``` diff --git a/docs/reference/api/user/user.md b/docs/reference/api/user/user.md new file mode 100644 index 0000000..d5ab4f4 --- /dev/null +++ b/docs/reference/api/user/user.md @@ -0,0 +1,14 @@ +--- +title: "User" +linkTitle: "User" +description: > + Learn how to use API endpoints for the user resource. +--- + +The below endpoints are available to operate on the `user` resource. + +:::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/). +::: diff --git a/docs/reference/api/user/view.md b/docs/reference/api/user/view.md new file mode 100644 index 0000000..5f7241a --- /dev/null +++ b/docs/reference/api/user/view.md @@ -0,0 +1,61 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a user. +--- + +## Endpoint + +``` +GET /api/v1/users/:user +``` + +## Parameters + +The following parameters are used to configure the endpoint: + +| Name | Description | +| ------ | ------------ | +| `user` | name of user | + +## 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/). +::: + +#### Request + +```sh +curl \ + -X GET \ + -H "Authorization: Bearer " \ + "http://127.0.0.1:8080/api/v1/users/OctoKitty" +``` + +#### Response + +```json +{ + "id": 1, + "name": "OctoKitty", + "token": null, + "favorites": ["github/octocat"], + "active": true, + "admin": false +} +``` diff --git a/docs/reference/cli/_category_.json b/docs/reference/cli/_category_.json index 5569091..1e341af 100644 --- a/docs/reference/cli/_category_.json +++ b/docs/reference/cli/_category_.json @@ -1,5 +1,7 @@ { "label": "CLI", - "position": 1, - "link": {"type": "generated-index"}, + "position": 2, + "link": { + "type": "generated-index" + } } diff --git a/docs/reference/cli/authentication.md b/docs/reference/cli/authentication.md new file mode 100644 index 0000000..7a12f1e --- /dev/null +++ b/docs/reference/cli/authentication.md @@ -0,0 +1,80 @@ +--- +title: "Authentication" +sidebar_position: 1 +--- + +## Overview + +Authentication with the Vela CLI is the responsibility of the client initiating the request. + +Each request requires a server address. You can provide this variable to the CLI in three ways: + +- Configuration File +- Environment Variable +- Flag + +:::tip +A configuration file is the recommended method for providing the API address to the CLI. +::: + +### Configuration File + +:::tip +The default path for this configuration file can be found @ `$HOME/.vela/config.yml`. +::: + +Log in: + +```sh +# Syntax +vela login --api.addr + +# Example +vela login --api.addr https://vela.example.com +``` + +Confirm authentication via browser prompt: + +``` +Open https://vela.example.com in your browser and complete authentication (Press Enter to confirm): +``` + +Confirm to generate or update the configuration file prompt: + +``` +Authentication complete. Continue to save configuration (existing config will be overwritten): +``` + +:::tip +For more information, you can visit the [CLI config documentation](/docs/reference/cli/config/). +::: + +### Environment Variables + +Configure the environment with the `VELA_ADDR` environment variable: + +```sh +export VELA_ADDR=https://vela.example.com +``` + +Log in and confirm the two prompts as stated above: + +```sh +vela login +``` + +:::tip +It's recommended to add these to your terminal profile (`~/.bashrc` or `~/.zshrc`) +::: + +### Flags + +Log in and confirm the two prompts as stated above: + +```sh +# Syntax +vela login --api.addr + +# Example +vela login --api.addr https://vela.example.com +``` diff --git a/docs/reference/cli/build/approve.md b/docs/reference/cli/build/approve.md new file mode 100644 index 0000000..627396a --- /dev/null +++ b/docs/reference/cli/build/approve.md @@ -0,0 +1,71 @@ +--- +title: "Approve" +linkTitle: "Approve" +description: > + Learn how to approve a build as a repository admin. +--- + +## Command + +``` +$ vela approve build +``` + +:::tip +For more information, you can run `vela approve build --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ---------------------------------- | --------------------------------- | +| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | +| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | +| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | +| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela approve build --build 1 +``` + +#### Targeted Request + +```sh +$ vela approve build --org github --repo octocat --build 1 +``` + +#### Response + +```sh +"successfully approved build github/octocat/1" +``` \ No newline at end of file diff --git a/docs/reference/cli/build/build.md b/docs/reference/cli/build/build.md new file mode 100644 index 0000000..b0a43ba --- /dev/null +++ b/docs/reference/cli/build/build.md @@ -0,0 +1,13 @@ +--- +title: "Build" +--- + +The below commands are available to operate on the `build` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/build/cancel.md b/docs/reference/cli/build/cancel.md new file mode 100644 index 0000000..cf8b7a8 --- /dev/null +++ b/docs/reference/cli/build/cancel.md @@ -0,0 +1,71 @@ +--- +title: "Cancel" +linkTitle: "Cancel" +description: > + Learn how to cancel a build. +--- + +## Command + +``` +$ vela cancel build +``` + +:::tip +For more information, you can run `vela cancel build --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ---------------------------------- | --------------------------------- | +| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | +| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | +| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | +| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela cancel build --build 1 +``` + +#### Targeted Request + +```sh +$ vela cancel build --org github --repo octocat --build 1 +``` + +#### Response + +```sh +canceled build github/octocat/1 +``` diff --git a/docs/reference/cli/build/get.md b/docs/reference/cli/build/get.md new file mode 100644 index 0000000..5bd8a5d --- /dev/null +++ b/docs/reference/cli/build/get.md @@ -0,0 +1,80 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list builds. +--- + +## Command + +``` +$ vela get build +``` + +:::tip +For more information, you can run `vela get build --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ------------------------------------ | --------------------------------- | +| `org` | name of organization for the builds | `VELA_ORG`, `BUILD_ORG` | +| `repo` | name of repository for the builds | `VELA_REPO`, `BUILD_REPO` | +| `event` | name of event filter for the builds | `VELA_EVENT`, `BUILD_EVENT` | +| `status` | name of status filter for the builds | `VELA_STATUS`, `BUILD_STATUS` | +| `branch` | name of branch filter for the builds | `VELA_BRANCH`, `BUILD_BRANCH` | +| `output` | format the output for the builds | `VELA_OUTPUT`, `BUILD_OUTPUT` | +| `page` | prints a specific page of builds | `VELA_PAGE`, `BUILD_PAGE` | +| `per.page` | number of builds to print per page | `VELA_PER_PAGE`, `BUILD_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get build --build 1 +``` + +#### Targeted Request + +```sh +$ vela get build --org github --repo octocat --build 1 +``` + +#### Response + +```sh +NUMBER STATUS EVENT BRANCH DURATION +5 failure push main 45s +4 failure push main 50s +3 success push main 54s +2 success push main 55s +1 pending push main ... +``` diff --git a/docs/reference/cli/build/restart.md b/docs/reference/cli/build/restart.md new file mode 100644 index 0000000..348665f --- /dev/null +++ b/docs/reference/cli/build/restart.md @@ -0,0 +1,95 @@ +--- +title: "Restart" +linkTitle: "Restart" +description: > + Learn how to rerun a build. +--- + +## Command + +``` +$ vela restart build +``` + +:::tip +For more information, you can run `vela restart build --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ---------------------------------- | --------------------------------- | +| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | +| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | +| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | +| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela restart build --build 1 +``` + +#### Targeted Request + +```sh +$ vela restart build --org github --repo octocat --build 1 +``` + +#### Response + +```sh +id: 2 +repo_id: 1 +number: 2 +parent: 1 +event: push +status: created +error: "" # Populates when the platform runs into an error with the build +enqueued: 1563474087 +created: 1563474086 +started: 1563474087 +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 +baseref: "" +host: "company.localhost" +runtime: "docker" +distribution: "linux" +``` diff --git a/docs/reference/cli/build/view.md b/docs/reference/cli/build/view.md new file mode 100644 index 0000000..d805e42 --- /dev/null +++ b/docs/reference/cli/build/view.md @@ -0,0 +1,95 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a build. +--- + +## Command + +``` +$ vela view build +``` + +:::tip +For more information, you can run `vela view build --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ---------------------------------- | --------------------------------- | +| `org` | name of organization for the build | `VELA_ORG`, `BUILD_ORG` | +| `repo` | name of repository for the build | `VELA_REPO`, `BUILD_REPO` | +| `build` | number of the build | `VELA_BUILD`, `BUILD_NUMBER` | +| `output` | format the output for the build | `VELA_OUTPUT`, `BUILD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view build --build 1 +``` + +#### Targeted Request + +```sh +$ vela view build --org github --repo octocat --build 1 +``` + +#### Response + +```sh +id: 1 +repo_id: 1 +number: 1 +parent: 1 +event: push +status: created +error: "" # Populates when the platform runs into an error with the build +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 +baseref: "" +host: "company.localhost" +runtime: "docker" +distribution: "linux" +``` diff --git a/docs/reference/cli/completion/completion.md b/docs/reference/cli/completion/completion.md new file mode 100644 index 0000000..3be1149 --- /dev/null +++ b/docs/reference/cli/completion/completion.md @@ -0,0 +1,16 @@ +--- +title: "Completion" +linkTitle: "Completion" +description: > + Learn how to enable auto-completion in your terminal. +--- + +The below commands are available to operate on the `completion` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/completion/generate.md b/docs/reference/cli/completion/generate.md new file mode 100644 index 0000000..49c4a5b --- /dev/null +++ b/docs/reference/cli/completion/generate.md @@ -0,0 +1,140 @@ +--- +title: "Generate" +linkTitle: "Generate" +description: > + Learn how to produce auto-completion for your terminal. +--- + +## Command + +``` +$ vela generate completion +``` + +:::info +For more information, you can run `vela generate completion --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------ | -------------------------------------- | ------------------------------ | +| `bash` | generate a Bash auto-completion script | `VELA_BASH`, `COMPLETION_BASH` | +| `zsh` | generate a Zsh auto-completion script | `VELA_ZSH`, `COMPLETION_ZSH` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela generate completion --bash +``` + +#### Response + +```sh +#! /bin/bash + +_cli_bash_autocomplete() { + if [[ "${COMP_WORDS[0]}" != "source" ]]; then + local cur opts base + COMPREPLY=() + cur="${COMP_WORDS[COMP_CWORD]}" + + if [[ "$cur" == "-"* ]]; then + opts=$( ${COMP_WORDS[@]:0:$COMP_CWORD} ${cur} --generate-bash-completion ) + else + opts=$( ${COMP_WORDS[@]:0:$COMP_CWORD} --generate-bash-completion ) + fi + + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi +} + +complete -o bashdefault -o default -o nospace -F _cli_bash_autocomplete vela +``` + +## Permanent Automatic Completion + +This section covers how to enable auto-completion for your terminal permanently. + +#### Bash + +:::info +This section assumes you have a version of Bash greater than 4. + +You can check your Bash version with: + +```sh +bash --version +``` + +If you have a version older than 4, you can use [brew](https://brew.sh) to install a newer version. + +```sh +brew install bash +``` +::: + +1. Install v2 of Bash Completion + +```sh +brew install bash-completion@2 +``` + +2. Copy Vela Bash Completion script + +```sh +vela generate completion --bash >> /usr/local/etc/bash_completion.d/vela.sh +``` + +3. Update Bash Profile with Completion + +```sh +export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d" >> $HOME/.bash_profile +[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh" >> $HOME/.bash_profile +``` + +4. Source Bash Profile in Current Terminal + +```sh +source $HOME/.bash_profile +``` + +#### Zsh + +1. Update Zsh Profile with Completion + +```sh +source <(vela generate completion --zsh) >> $HOME/.zshrc +``` + +:::info +If you're met with an error like: + +```sh +complete:13: command not found: compdef +``` + +Then you need to add the following to the top of your `$HOME/.zshrc`: + +```sh +autoload -Uz compinit +compinit +``` +::: diff --git a/docs/reference/cli/config/config.md b/docs/reference/cli/config/config.md new file mode 100644 index 0000000..5787b69 --- /dev/null +++ b/docs/reference/cli/config/config.md @@ -0,0 +1,16 @@ +--- +title: "Config" +linkTitle: "Config" +description: > + Learn how to use CLI commands for the config resource. +--- + +The below commands are available to operate on the `config` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/config/generate.md b/docs/reference/cli/config/generate.md new file mode 100644 index 0000000..5bdf979 --- /dev/null +++ b/docs/reference/cli/config/generate.md @@ -0,0 +1,66 @@ +--- +title: "Generate" +linkTitle: "Generate" +description: > + Learn how to produce a config. +--- + +## Command + +``` +$ vela generate config +``` + +:::tip +For more information, you can run `vela generate config --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------------- | ----------------------------------------------- | -------------------------------------------- | +| `api.addr` | full URL to API server | `VELA_ADDR`, `CONFIG_ADDR` | +| `api.token.access` | API access token | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | +| `api.token.refresh` | API refresh token | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | +| `api.token` | PAT for API server | `VELA_TOKEN`, `CONFIG_TOKEN` | +| `api.version` | version of API for server | `VELA_API_VERSION`, `CONFIG_API_VERSION` | +| `log.level` | set the level of logging | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | +| `no-git` | set whether CLI finds repo of cwd automatically | `VELA_NO_GIT`, `CONFIG_NO_GIT` | +| `output` | format the output for API results | `VELA_OUTPUT`, `CONFIG_OUTPUT` | +| `org` | name of organization for API calls | `VELA_ORG`, `CONFIG_ORG` | +| `repo` | name of repository for API calls | `VELA_REPO`, `CONFIG_REPO` | +| `secret.engine` | name of secret engine for API calls | `VELA_ENGINE`, `CONFIG_ENGINE` | +| `secret.type` | name of secret type for API calls | `VELA_TYPE`, `CONFIG_TYPE` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela generate config --api.addr https://vela.example.com --log.level info +``` + +#### Response + +```sh +api: + addr: https://vela.example.com +log: + level: info +no-git: "false" +secret: {} +``` diff --git a/docs/reference/cli/config/remove.md b/docs/reference/cli/config/remove.md new file mode 100644 index 0000000..12dbf03 --- /dev/null +++ b/docs/reference/cli/config/remove.md @@ -0,0 +1,60 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a config. +--- + +## Command + +``` +$ vela remove config +``` + +:::tip +For more information, you can run `vela remove config --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +:::warning +Providing no parameters to this command will remove the entire configuration file. +::: + +| Name | Description | Environment Variables | +| ------------------- | ----------------------------------- | -------------------------------------------- | +| `api.addr` | removes the API address field | `VELA_ADDR`, `CONFIG_ADDR` | +| `api.token.access` | removes the API access token field | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | +| `api.token.refresh` | removes the API refresh token field | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | +| `api.token` | removes the API token field | `VELA_TOKEN`, `CONFIG_TOKEN` | +| `api.version` | removes the API version field | `VELA_API_VERSION`, `CONFIG_API_VERSION` | +| `log.level` | removes the log level field | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | +| `output` | removes the output field | `VELA_OUTPUT`, `CONFIG_OUTPUT` | +| `org` | removes the org field | `VELA_ORG`, `CONFIG_ORG` | +| `repo` | removes the repo field | `VELA_REPO`, `CONFIG_REPO` | +| `secret.engine` | removes the secret engine field | `VELA_ENGINE`, `CONFIG_ENGINE` | +| `secret.type` | removes the secret type field | `VELA_TYPE`, `CONFIG_TYPE` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela remove config +``` + +#### Response diff --git a/docs/reference/cli/config/update.md b/docs/reference/cli/config/update.md new file mode 100644 index 0000000..bdd6895 --- /dev/null +++ b/docs/reference/cli/config/update.md @@ -0,0 +1,69 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a config. +--- + +## Command + +``` +$ vela update config +``` + +:::tip +For more information, you can run `vela update config --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------------- | ----------------------------------- | -------------------------------------------- | +| `api.addr` | updates the API address field | `VELA_ADDR`, `CONFIG_ADDR` | +| `api.token.access` | updates the API access token field | `VELA_ACCESS_TOKEN`, `CONFIG_ACCESS_TOKEN` | +| `api.token.refresh` | updates the API refresh token field | `VELA_REFRESH_TOKEN`, `CONFIG_REFRESH_TOKEN` | +| `api.token` | updates the API token field | `VELA_TOKEN`, `CONFIG_TOKEN` | +| `api.version` | updates the API version field | `VELA_API_VERSION`, `CONFIG_API_VERSION` | +| `log.level` | updates the log level field | `VELA_LOG_LEVEL`, `CONFIG_LOG_LEVEL` | +| `output` | updates the output field | `VELA_OUTPUT`, `CONFIG_OUTPUT` | +| `org` | updates the org field | `VELA_ORG`, `CONFIG_ORG` | +| `repo` | updates the repo field | `VELA_REPO`, `CONFIG_REPO` | +| `secret.engine` | updates the secret engine field | `VELA_ENGINE`, `CONFIG_ENGINE` | +| `secret.type` | updates the secret type field | `VELA_TYPE`, `CONFIG_TYPE` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela update config --org github +``` + +#### Response + +```sh +api: + addr: https://vela.example.com + access_token: superSecretAccessToken + refresh_token: superSecretRefreshToken + version: v1 +log: + level: info +no-git: "false" +secret: {} +org: github +``` diff --git a/docs/reference/cli/config/view.md b/docs/reference/cli/config/view.md new file mode 100644 index 0000000..4a666c1 --- /dev/null +++ b/docs/reference/cli/config/view.md @@ -0,0 +1,50 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a config. +--- + +## Command + +``` +$ vela view config +``` + +:::tip +For more information, you can run `vela view config --help`. +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela view config +``` + +#### Response + +```sh +api: + addr: https://vela.example.com + access_token: superSecretAccessToken + refresh_token: superSecretRefreshToken + version: v1 +log: + level: info +no-git: "false" +secret: {} +``` diff --git a/docs/reference/cli/dashboard/add.md b/docs/reference/cli/dashboard/add.md new file mode 100644 index 0000000..802fc8c --- /dev/null +++ b/docs/reference/cli/dashboard/add.md @@ -0,0 +1,100 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a dashboard. +--- + +## Command + +``` +$ vela add dashboard +``` + +:::tip +For more information, you can run `vela add dashboard --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ------------------------------------------------- | ------------------------------------------------------- | +| `name` | name for the dashboard | `VELA_DASHBOARD_NAME`, `DASHBOARD_NAME` | +| `repos` | list of repositories (org/repo) for the dashboard | `VELA_DASHBOARD_REPOS`, `DASHBOARD_REPOS` | +| `branches` | filter builds in all repositories by branch | `VELA_DASHBOARD_REPOS_BRANCH`, `DASHBOARD_REPOS_BRANCH` | +| `events` | filter builds in all repositories by event | `VELA_DASHBOARD_REPOS_EVENT`, `DASHBOARD_REPOS_EVENT` | +| `admins` | provide the list of admins for the dashboard | `VELA_DASHBOARD_ADMINS`, `DASHBOARD_ADMINS` | +| `output` | format the output for the dashboard | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela add dashboard --name 'Octocat Main Branches' --repos octocat/Hello-World,octocat/Spoon-Knife --branches main +``` + +#### Response + +```sh +{ + Name: Octocat Main Branches, + ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, + Admins: [{ + Active: true, + Admin: false, + Dashboards: [], + Favorites: [], + ID: 1, + Name: octokitty, + Token: , +}], + CreatedAt: 1716572402, + CreatedBy: octokitty, + UpdatedAt: 1716572402, + UpdatedBy: octokitty, + Repos: [{ + Name: octocat/Hello-World, + ID: 1, + Branches: [main], + Events: [], +} { + Name: octocat/Spoon-Knife, + ID: 2, + Branches: [main], + Events: [], +}], +} +``` + +## Examples + +```sh +EXAMPLES: + 1. Add a dashboard. + $ vela add dashboard --name my-dashboard + 2. Add a dashboard with repositories. + $ vela add dashboard --name my-dashboard --repos Org-1/Repo-1,Org-2/Repo-2 + 3. Add a dashboard with repositories filtering builds by pushes to main. + $ vela add dashboard --name my-dashboard --repos Org-1/Repo-1,Org-2/Repo-2 --branch main --event push + 4. Add a dashboard with multiple admins. + $ vela add dashboard --name my-dashboard --admins JohnDoe,JaneDoe +``` diff --git a/docs/reference/cli/dashboard/dashboard.md b/docs/reference/cli/dashboard/dashboard.md new file mode 100644 index 0000000..cf46593 --- /dev/null +++ b/docs/reference/cli/dashboard/dashboard.md @@ -0,0 +1,16 @@ +--- +title: "Dashboard" +linkTitle: "Dashboard" +description: > + Learn how to use CLI commands for the dashboard resource. +--- + +The below commands are available to operate on the `dashboard` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/dashboard/get.md b/docs/reference/cli/dashboard/get.md new file mode 100644 index 0000000..17e324d --- /dev/null +++ b/docs/reference/cli/dashboard/get.md @@ -0,0 +1,119 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list dashboards. +--- + +## Command + +``` +$ vela get dashboard +``` + +:::tip +For more information, you can run `vela get dashboard --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ------------------------------------------------------- | --------------------------------- | +| `full` | output the repo and build information for the dashboard | `VELA_FULL`, `DASHBOARD_FULL` | +| `output` | format the output for dashboards | `VELA_OUTPUT`, `DASHBOARD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela get dashboard +``` + +#### Response + +```sh +[{ + Name: Octocat Main Branches, + ID: 59376e53-879f-478e-b6d2-b8aefe219c6d, + Admins: [{ + Active: true, + Admin: false, + Dashboards: [], + Favorites: [], + ID: 1, + Name: octokitty, + Token: , +}], + CreatedAt: 1715117480, + CreatedBy: octokitty, + UpdatedAt: 1715117480, + UpdatedBy: octokitty, + Repos: [{ + Name: octocat/Hello-World, + ID: 1, + Branches: [main], + Events: [], +} { + Name: octocat/Spoon-Knife, + ID: 2, + Branches: [main], + Events: [], +}], +} { + Name: Octocat PR Events, + ID: 0ebb9f01-389c-4a0f-b301-6bf2f9a0fe3b, + Admins: [{ + Active: true, + Admin: false, + Dashboards: [], + Favorites: [], + ID: 1, + Name: octokitty, + Token: , +}], + CreatedAt: 1716397739, + CreatedBy: octokitty, + UpdatedAt: 1716397739, + UpdatedBy: octokitty, + Repos: [{ + Name: octocat/Hello-World, + ID: 1, + Branches: [], + Events: [pull_request], +} { + Name: octocat/Spoon-Knife, + ID: 2, + Branches: [], + Events: [pull_request], +}], +}] +``` + +## Examples + +```sh +EXAMPLES: + 1. Get user dashboards. + $ vela get dashboard + 2. Get user dashboards with repo and build information. + $ vela get dashboard --full +``` diff --git a/docs/reference/cli/dashboard/update.md b/docs/reference/cli/dashboard/update.md new file mode 100644 index 0000000..b1bd625 --- /dev/null +++ b/docs/reference/cli/dashboard/update.md @@ -0,0 +1,108 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a dashboard. +--- + +## Command + +``` +$ vela update dashboard +``` + +:::tip +For more information, you can run `vela update dashboard --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------------- | ------------------------------------------------------------ | ------------------------------------------------------- | +| `id` | uuid for the dashboard | `VELA_DASHBOARD_ID`, `DASHBOARD_ID` | +| `name` | name for the dashboard | `VELA_DASHBOARD_NAME`, `DASHBOARD_NAME` | +| `add-repos` | list of repositories to add for the dashboard | `VELA_DASHBOARD_ADD_REPOS`, `DASHBOARD_ADD_REPOS` | +| `drop-repos` | list of repositories to remove from the dashboard | `VELA_DASHBOARD_DROP_REPOS`, `DASHBOARD_DROP_REPOS` | +| `target-repos` | list of repositories to target for updates for the dashboard | `VELA_DASHBOARD_TARGET_REPOS`, `DASHBOARD_TARGET_REPOS` | +| `add-admins` | list of admins to add for the dashboard | `VELA_DASHBOARD_ADD_ADMINS`, `DASHBOARD_ADD_ADMINS` | +| `drop-admins` | list of admins to remove from the dashboard | `VELA_DASHBOARD_DROP_ADMINS`, `DASHBOARD_DROP_ADMINS` | +| `branches` | filter builds in all repositories by branch | `VELA_DASHBOARD_REPOS_BRANCH`, `DASHBOARD_REPOS_BRANCH` | +| `events` | filter builds in all repositories by event | `VELA_DASHBOARD_REPOS_EVENT`, `DASHBOARD_REPOS_EVENT` | +| `output` | format the output for the dashboard | `VELA_OUTPUT`, `DASHBOARD_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela update dashboard --id d3040cd7-9bb6-45d1-a2a1-d794483a902c --name 'Octocat Dev Branches' --target-repos octocat/Hello-world,octocat/Spoon-Knife --branches dev +``` + +#### Response + +```sh +{ + Name: Octocat Dev Branches, + ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, + Admins: [{ + Active: true, + Admin: false, + Dashboards: [], + Favorites: [], + ID: 1, + Name: octokitty, + Token: , +}], + CreatedAt: 1716572402, + CreatedBy: octokitty, + UpdatedAt: 1716572402, + UpdatedBy: octokitty, + Repos: [{ + Name: octocat/Hello-World, + ID: 1, + Branches: [dev], + Events: [], +} { + Name: octocat/Spoon-Knife, + ID: 2, + Branches: [dev], + Events: [], +}], +} +``` + +## Examples + +```sh +EXAMPLES: + 1. Update a dashboard to add a repository. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --add-repos Org-1/Repo-1 + 2. Update a dashboard to remove a repository. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --drop-repos Org-1/Repo-1 + 3. Update a dashboard to add event and branch filters to specific repositories. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --target-repos Org-1/Repo-1,Org-2/Repo-2 --branches main --events push + 4. Update a dashboard to change the name. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --name MyDashboard + 5. Update a dashboard to add an admin. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --add-admins JohnDoe + 6. Update a dashboard to remove an admin. + $ vela update dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --drop-admins JohnDoe +``` diff --git a/docs/reference/cli/dashboard/view.md b/docs/reference/cli/dashboard/view.md new file mode 100644 index 0000000..558284c --- /dev/null +++ b/docs/reference/cli/dashboard/view.md @@ -0,0 +1,93 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a dashboard. +--- + +## Command + +``` +$ vela view dashboard +``` + +:::tip +For more information, you can run `vela view dashboard --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ------------------------------------------------------- | ----------------------------------- | +| `id` | uuid for the dashboard | `VELA_DASHBOARD_ID`, `DASHBOARD_ID` | +| `full` | output the repo and build information for the dashboard | `VELA_FULL`, `DASHBOARD_FULL` | +| `output` | format the output for the dashboard | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela view dashboard --id d3040cd7-9bb6-45d1-a2a1-d794483a902c +``` + +#### Response + +```sh +{ + Name: Octocat Main Branches, + ID: d3040cd7-9bb6-45d1-a2a1-d794483a902c, + Admins: [{ + Active: true, + Admin: false, + Dashboards: [], + Favorites: [], + ID: 1, + Name: octokitty, + Token: , +}], + CreatedAt: 1716572402, + CreatedBy: octokitty, + UpdatedAt: 1716572402, + UpdatedBy: octokitty, + Repos: [{ + Name: octocat/Hello-World, + ID: 1, + Branches: [main], + Events: [], +} { + Name: octocat/Spoon-Knife, + ID: 2, + Branches: [main], + Events: [], +}], +} +``` + +## Examples + +```sh +EXAMPLES: + 1. View a dashboard. + $ vela view dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 + 2. View a dashboard with repo and build information. + $ vela view dashboard --id c8da1302-07d6-11ea-882f-4893bca275b8 --full +``` diff --git a/docs/reference/cli/deployment/add.md b/docs/reference/cli/deployment/add.md new file mode 100644 index 0000000..2f357b0 --- /dev/null +++ b/docs/reference/cli/deployment/add.md @@ -0,0 +1,92 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a deployment. +--- + +## Command + +``` +$ vela add deployment +``` + +:::tip +For more information, you can run `vela add deployment --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------- | --------------------------------------------------- | -------------------------------------------- | +| `org` | name of organization for the deployment | `VELA_ORG`, `DEPLOYMENT_ORG` | +| `repo` | name of repository for the deployment | `VELA_REPO`, `DEPLOYMENT_REPO` | +| `ref` | name of branch, commit, or tag for the deployment | `VELA_DEPLOYMENT`, `DEPLOYMENT_NUMBER` | +| `target` | name of target environment for the deployment | `VELA_TARGET`, `DEPLOYMENT_TARGET` | +| `description` | short description for the deployment | `VELA_DESCRIPTION`, `DEPLOYMENT_DESCRIPTION` | +| `parameter` | parameter(s) in key=value format for the deployment | `VELA_PARAMETERS,`, `DEPLOYMENT_PARAMETERS` | +| `task` | name of task for the deployment | `VELA_TASK`, `DEPLOYMENT_TASK` | +| `output` | format the output for the deployment | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela add deployment +``` + +#### Targeted Request + +```sh +$ vela add deployment --org github --repo octocat +``` + +#### Response generated from successful CLI command +```sh +deployment "https://api.github.com/repos/github/octocat/deployments/1" was created +``` + +## Examples + +```sh +EXAMPLES: + 1. Add a deployment for a repository. + $ vela add deployment --org MyOrg --repo MyRepo + 2. Add a deployment for a repository with a specific target environment. + $ vela add deployment --org MyOrg --repo MyRepo --target stage + 3. Add a deployment for a repository with a specific branch reference. + $ vela add deployment --org MyOrg --repo MyRepo --ref dev + 4. Add a deployment for a repository with a specific commit reference. + $ vela add deployment --org MyOrg --repo MyRepo --ref 48afb5bdc41ad69bf22588491333f7cf71135163 + 5. Add a deployment for a repository with a specific tag. + $ vela add deployment --org MyOrg --repo MyRepo --ref 'refs/tags/example.tag' + 6. Add a deployment for a repository with a specific description. + $ vela add deployment --org MyOrg --repo MyRepo --description 'my custom message' + 7. Add a deployment for a repository with two parameters. + $ vela add deployment --org MyOrg --repo MyRepo --parameter 'key=value' --parameter 'foo=bar' + 8. Add a deployment for a repository when config or environment variables are set. + $ vela add deployment +``` diff --git a/docs/reference/cli/deployment/deployment.md b/docs/reference/cli/deployment/deployment.md new file mode 100644 index 0000000..4555370 --- /dev/null +++ b/docs/reference/cli/deployment/deployment.md @@ -0,0 +1,16 @@ +--- +title: "Deployment" +linkTitle: "Deployment" +description: > + Learn how to use CLI commands for the deployment resource. +--- + +The below commands are available to operate on the `deployment` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/deployment/get.md b/docs/reference/cli/deployment/get.md new file mode 100644 index 0000000..3750619 --- /dev/null +++ b/docs/reference/cli/deployment/get.md @@ -0,0 +1,85 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list deployments. +--- + +## Command + +``` +$ vela get deployment +``` + +:::tip +For more information, you can run `vela get deployment --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ---------------------------------------- | -------------------------------------- | +| `org` | name of organization for the deployments | `VELA_ORG`, `DEPLOYMENT_ORG` | +| `repo` | name of repository for the deployments | `VELA_REPO`, `DEPLOYMENT_REPO` | +| `output` | format the output for the deployments | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | +| `page` | prints a specific page of deployments | `VELA_PAGE`, `DEPLOYMENT_PAGE` | +| `per.page` | number of deployments to print per page | `VELA_PER_PAGE`, `DEPLOYMENT_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get deployment +``` + +#### Targeted Request + +```sh +$ vela get deployment --org github --repo octocat +``` + +#### Response generated from successful CLI command +```sh +ID TASK USER REF TARGET +2 deploy:vela octocat main production +1 deploy:vela octocat main production +``` + +## Examples + +```sh +EXAMPLES: + 1. Get deployments for a repository. + $ vela get deployment --org MyOrg --repo MyRepo + 2. Get deployments for a repository with wide view output. + $ vela get deployment --org MyOrg --repo MyRepo --output wide + 3. Get deployments for a repository with yaml output. + $ vela get deployment --org MyOrg --repo MyRepo --output yaml + 4. Get deployments for a repository with json output. + $ vela get deployment --org MyOrg --repo MyRepo --output json + 5. Get deployments for a repository when config or environment variables are set. + $ vela get deployment +``` diff --git a/docs/reference/cli/deployment/view.md b/docs/reference/cli/deployment/view.md new file mode 100644 index 0000000..bd1b559 --- /dev/null +++ b/docs/reference/cli/deployment/view.md @@ -0,0 +1,86 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a deployment. +--- + +## Command + +``` +$ vela view deployment +``` + +:::tip +For more information, you can run `vela view deployment --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------ | --------------------------------------- | -------------------------------------- | +| `org` | name of organization for the deployment | `VELA_ORG`, `DEPLOYMENT_ORG` | +| `repo` | name of repository for the deployment | `VELA_REPO`, `DEPLOYMENT_REPO` | +| `deployment` | number of the deployment | `VELA_DEPLOYMENT`, `DEPLOYMENT_NUMBER` | +| `output` | format the output for the deployment | `VELA_OUTPUT`, `DEPLOYMENT_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view deployment --deployment 1 +``` + +#### Targeted Request + +```sh +$ vela view deployment --org github --repo octocat --deployment 1 +``` + +#### Response generated from successful CLI command +```sh +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 +``` + +## Examples + +```sh +EXAMPLES: + 1. View deployment details for a repository. + $ vela view deployment --org MyOrg --repo MyRepo --deployment 1 + 2. View deployment details for a repository with json output. + $ vela view deployment --org MyOrg --repo MyRepo --deployment 1 --output json + 3. View deployment details for a repository config or environment variables are set. + $ vela view deployment --deployment 1 +``` \ No newline at end of file diff --git a/docs/reference/cli/hook/get.md b/docs/reference/cli/hook/get.md new file mode 100644 index 0000000..c066bea --- /dev/null +++ b/docs/reference/cli/hook/get.md @@ -0,0 +1,77 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list hooks. +--- + +## Command + +``` +$ vela get hook +``` + +:::tip +For more information, you can run `vela get hook --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ---------------------------------- | -------------------------------- | +| `org` | name of organization for the hooks | `VELA_ORG`, `HOOK_ORG` | +| `repo` | name of repository for the hooks | `VELA_REPO`, `HOOK_REPO` | +| `output` | format the output for the hooks | `VELA_OUTPUT`, `HOOK_OUTPUT` | +| `page` | prints a specific page of hooks | `VELA_PAGE`, `HOOK_PAGE` | +| `per.page` | number of hooks to print per page | `VELA_PER_PAGE`, `HOOK_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get hook +``` + +#### Targeted Request + +```sh +$ vela get hook --org github --repo octocat +``` + +#### Response + +```sh +NUMBER STATUS EVENT BRANCH +5 failure push main +4 failure push main +3 success push main +2 success push main +1 success push main +``` diff --git a/docs/reference/cli/hook/hook.md b/docs/reference/cli/hook/hook.md new file mode 100644 index 0000000..68a93fe --- /dev/null +++ b/docs/reference/cli/hook/hook.md @@ -0,0 +1,16 @@ +--- +title: "Hook" +linkTitle: "Hook" +description: > + Learn how to use CLI commands for the hook resource. +--- + +The below commands are available to operate on the `hook` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/hook/view.md b/docs/reference/cli/hook/view.md new file mode 100644 index 0000000..20f43ff --- /dev/null +++ b/docs/reference/cli/hook/view.md @@ -0,0 +1,82 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a hook. +--- + +## Command + +``` +$ vela view hook +``` + +:::tip +For more information, you can run `vela view hook --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------- | ---------------------------- | +| `org` | name of organization for the hook | `VELA_ORG`, `HOOK_ORG` | +| `repo` | name of repository for the hook | `VELA_REPO`, `HOOK_REPO` | +| `hook` | number of the hook | `VELA_HOOK`, `HOOK_NUMBER` | +| `output` | format the output for the hook | `VELA_OUTPUT`, `HOOK_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view hook --hook 1 +``` + +#### Targeted Request + +```sh +$ vela view hook --org github --repo octocat --hook 1 +``` + +#### Response + +```sh +id: 1 +repo_id: 1 +build_id: 1 +number: 1 +source_id: c8da1302-07d6-11ea-882f-4893bca275b8 +created: 1563475419 +host: github.com +event: push +branch: main +error: +status: success +link: https://github.com/github/octocat/settings/hooks/1 +``` diff --git a/docs/reference/cli/install.md b/docs/reference/cli/install.md new file mode 100644 index 0000000..1dc39b2 --- /dev/null +++ b/docs/reference/cli/install.md @@ -0,0 +1,120 @@ +--- +title: "Install" +sidebar_position: 2 +--- + +:::tip +Please keep in mind your operating system (OS) when referring to the installation instructions below. +::: + +## MacOS + +:::tip +[Homebrew](https://brew.sh/) is the recommended method for installing the Vela CLI on a Mac. +::: + +#### Homebrew + +```sh +# add Vela tap to your brew configuration +brew tap go-vela/vela + +# update your taps +brew update + +# install Vela CLI +brew install vela +``` + +#### cURL + +```sh +# download the binary +curl -L https://github.com/go-vela/cli/releases/latest/download/vela_darwin_amd64.tar.gz | tar zx + +# copy binary to $PATH +sudo cp vela /usr/local/bin/ +``` + +## Linux + +#### cURL + +```sh +# download the binary +curl -L https://github.com/go-vela/cli/releases/latest/download/vela_linux_amd64.tar.gz | tar zx + +# copy binary to $PATH +sudo cp vela /usr/local/bin/ +``` + +## Windows + +:::tip +The `curl` utility must be installed before following the instructions below. +::: + +#### Command Prompt + +```sh +# download the binary +curl -L https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz --output vela_windows_amd64.tar.gz + +# unzip the tarball +tar xzvf vela_windows_amd64.tar.gz + +# copy binary to $PATH +copy vela C:\Windows\System32/vela.exe +``` + +#### Windows PowerShell + +```sh +# download the binary +curl https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz -OutFile vela_windows_amd64.tar.gz + +# unzip the tarball +tar xzvf vela_windows_amd64.tar.gz + +# copy binary to $PATH +cp vela C:\Windows\System32/vela.exe +``` + +#### PowerShell 6 (PowerShell Core) + +```sh +# download the binary +curl -L https://github.com/go-vela/cli/releases/latest/download/vela_windows_amd64.tar.gz --output vela_windows_amd64.tar.gz + +# unzip the tarball +tar xzvf vela_windows_amd64.tar.gz + +# copy binary to $PATH +cp vela C:\Windows\System32/vela.exe +``` + +## From Source + +:::warning +This method is intended for **developers and advanced users only**. +::: + +:::tip +This section assumes you have already installed and setup [Golang](https://golang.org/). + +To install and setup Golang, please review the [installation documentation](https://golang.org/doc/install). +::: + +```sh +# download the repo +go get -d github.com/go-vela/cli + +# change to the cli directory +cd ${GOPATH}/src/github.com/go-vela/cli + +# build a release binary with Go +go build -o releases/vela + +# copy binary to $PATH +sudo cp releases/vela /usr/local/bin/ +``` diff --git a/docs/reference/cli/log/get.md b/docs/reference/cli/log/get.md new file mode 100644 index 0000000..f3f7433 --- /dev/null +++ b/docs/reference/cli/log/get.md @@ -0,0 +1,85 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list logs for a build. +--- + +## Command + +``` +$ vela get log +``` + +:::tip +For more information, you can run `vela get log --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | -------------------------------- | --------------------------- | +| `org` | name of organization for the log | `VELA_ORG`, `LOG_ORG` | +| `repo` | name of repository for the log | `VELA_REPO`, `LOG_REPO` | +| `build` | number of the build for the log | `VELA_BUILD`, `LOG_BUILD` | +| `output` | format the output for the logs | `VELA_OUTPUT`, `LOG_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get log --build 5 +``` + +#### Targeted Request + +```sh +$ vela get log --org github --repo octocat --build 5 +``` + +#### Response + +```sh +$ git init +Initialized empty Git repository in /vela/src/github.com/github/octocat/.git/ +$ git remote add origin https://github.com/github/octocat.git +$ git remote --verbose +origin https://github.com/github/octocat.git (fetch) +origin https://github.com/github/octocat.git (push) +$ git fetch --no-tags origin refs/heads/main +From https://github.com/github/octocat + * branch main -> FETCH_HEAD + * [new branch] main -> origin/main +$ git reset --hard afafce5e33a8efd4340613b31a953107d6dec3a3 +HEAD is now at afafce5 Dummy commit + +$ echo "Hello World!" +Hello World! +``` diff --git a/docs/reference/cli/log/log.md b/docs/reference/cli/log/log.md new file mode 100644 index 0000000..179df11 --- /dev/null +++ b/docs/reference/cli/log/log.md @@ -0,0 +1,16 @@ +--- +title: "Log" +linkTitle: "Log" +description: > + Learn how to use CLI commands for the log resource. +--- + +The below commands are available to operate on the `log` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/log/view.md b/docs/reference/cli/log/view.md new file mode 100644 index 0000000..80c53dc --- /dev/null +++ b/docs/reference/cli/log/view.md @@ -0,0 +1,84 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect logs for a build, step, or service. +--- + +## Command + +``` +$ vela view log +``` + +:::tip +For more information, you can run `vela view log --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------- | --------------------------------- | ----------------------------- | +| `org` | name of organization for the log | `VELA_ORG`, `LOG_ORG` | +| `repo` | name of repository for the log | `VELA_REPO`, `LOG_REPO` | +| `build` | number of the build for the log | `VELA_BUILD`, `LOG_BUILD` | +| `service` | number of the service for the log | `VELA_SERVICE`, `LOG_SERVICE` | +| `step` | number of the step for the log | `VELA_STEP`, `LOG_STEP` | +| `output` | format the output for the logs | `VELA_OUTPUT`, `LOG_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view log --build 5 --step 1 +``` + +#### Targeted Request + +```sh +$ vela view log --org github --repo octocat --build 5 --step 1 +``` + +#### Response + +```sh +$ git init +Initialized empty Git repository in /vela/src/github.com/github/octocat/.git/ +$ git remote add origin https://github.com/github/octocat.git +$ git remote --verbose +origin https://github.com/github/octocat.git (fetch) +origin https://github.com/github/octocat.git (push) +$ git fetch --no-tags origin refs/heads/main +From https://github.com/github/octocat + * branch main -> FETCH_HEAD + * [new branch] main -> origin/main +$ git reset --hard afafce5e33a8efd4340613b31a953107d6dec3a3 +HEAD is now at afafce5 Dummy commit +``` diff --git a/docs/reference/cli/pipeline/exec.md b/docs/reference/cli/pipeline/exec.md new file mode 100644 index 0000000..b65bae8 --- /dev/null +++ b/docs/reference/cli/pipeline/exec.md @@ -0,0 +1,271 @@ +--- +title: "Exec" +linkTitle: "Exec" +description: > + Learn how to execute a pipeline locally. +--- + +## Command + +``` +$ vela exec pipeline +``` + +:::tip +For more information, you can run `vela exec pipeline --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +### Ruleset Parameters + +| Name | Description | Environment Variables | +| ---------------- | --------------------------------------------- | -------------------------------------- | +| `branch` | the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH` | +| `comment` | the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT` | +| `event` | the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT` | +| `tag` | the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG` | +| `target` | the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET` | +| `file-changeset` | the build file changeset for the pipeline | `VELA_FILE_CHANGESET`, `FILE_CHANGESET`| + +### Repo Settings Parameters + +| Name | Description | Environment Variables | +| --------------- | --------------------------------------------- | -------------------------------------- | +| `org` | provide the organization for the pipeline | `VELA_ORG`, `PIPELINE_ORG` | +| `repo` | provide the repository for the pipeline | `VELA_REPO`, `PIPELINE_REPO` | +| `pipeline-type` | provide the repository pipeline type | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | + +### Template Parameters + +| Name | Description | Environment Variables | +| ----------------------- | ------------------------------------------------ | ----------------------------------------------------- | +| `compiler.github.token` | PAT for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_TOKEN`, `COMPILER_GITHUB_TOKEN` | +| `compiler.github.url` | URL for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_URL`, `COMPILER_GITHUB_URL` | +| `template-file` | list of local templates in form of \:\ | `VELA_TEMPLATE_FILE`, `PIPELINE_TEMPLATE_FILE` | +| `max-template-depth` | maximum depth for requesting nested templates | `VELA_MAX_TEMPLATE_DEPTH`, `MAX_TEMPLATE_DEPTH` | + +### Environment Parameters + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------- | +| `env-file` | Bool value for whether or not to source from an env file (default `.env`) | `VELA_ENV_FILE`, `ENV_FILE` | +| `env-file-path` | Path to override default `.env` sourcing of environment | `VELA_ENV_FILE_PATH`, `ENV_FILE_PATH` | +| `local-env` | Bool value for whether or not to onboard your local environment | `ONBOARD_LOCAL_ENV`, `LOCAL_ENV` | +| `env-vars` | list of environment variables to include in form of \=\ | `VELA_ENV_VARS` | + +### Other Parameters + +| Name | Description | Environment Variables | +| -------- | --------------------------------------------- | --------------------------------- | +| `output` | format the output in json, spew or yaml | `VELA_OUTPUT`, `PIPELINE_OUTPUT` | +| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | +| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | +| `local` | enables mounting local directory to pipeline | `VELA_LOCAL`, `PIPELINE_LOCAL` | +| `volume` | provide list of local volumes to mount | `VELA_VOLUMES`, `PIPELINE_VOLUMES`| + +## Environment + +Unless the `local-env` flag is supplied, the `vela exec pipeline` command will execute without any set environment. Instead, users are encouraged to supply their own environment variables in the form of an env file (e.g. `--env-file` OR `--env-file-path custom.env`). + +Many plugins, Starlark/Go templates, and other build resources depend on Vela-injected environment variables, such as `VELA_BUILD_COMMIT`. These variables will have to be supplied by the user, as there is no way for the compiler to determine these values locally. + +## Secrets + +The Vela Exec command does not have access to any secret you have stored in Vela or any other attached secret store. + +Environment variables can be set for the command by using the `env-vars` flag, ie `vela exec pipeline --env-vars MY_SECRET=foo`. They can also be set with the `env-file` or `local-env` flags. + +For example, if a pipeline is using the [kaniko plugin](https://go-vela.github.io/docs/plugins/registry/pipeline/kaniko/), it may require the secret `kaniko_password`, which can be provided with `vela exec pipeline --env-vars KANIKO_PASSWORD=mypass`. + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela exec pipeline +``` + +#### Response + +```sh +[step: init] > Inspecting runtime network... +[step: init] $ docker network inspect localOrg_localRepo_1 +{ + "Name": "localOrg_localRepo_1", + "Id": "cf204e6081cd4c10e3a285e7545790152afca05991c2dc67534f496844c1d274", + "Created": "2021-06-01T19:37:35.4772628Z", + "Scope": "local", + "Driver": "bridge", + "EnableIPv6": false, + "IPAM": { + "Driver": "default", + "Options": null, + "Config": [ + { + "Subnet": "192.168.0.0/20", + "Gateway": "192.168.0.1" + } + ] + }, + "Internal": false, + "Attachable": false, + "Ingress": false, + "ConfigFrom": { + "Network": "" + }, + "ConfigOnly": false, + "Containers": {}, + "Options": {}, + "Labels": {} +} + +[step: init] > Inspecting runtime volume... +[step: init] $ docker volume inspect localOrg_localRepo_1 +{ + "CreatedAt": "2021-06-01T19:37:35Z", + "Driver": "local", + "Labels": null, + "Mountpoint": "/var/lib/docker/volumes/localOrg_localRepo_1/_data", + "Name": "localOrg_localRepo_1", + "Options": null, + "Scope": "local" +} + +[step: init] > Pulling service images... +[step: init] > Pulling stage images... +[step: init] > Pulling step images... +[step: init] $ docker image inspect alpine:latest +sha256:6dbb9cc54074106d46d4ccb330f2a40a682d49dda5f4844962b7dce9fe44aaec + + +[step: hello Vela] $ echo "hello Vela!" +[step: hello Vela] hello Vela! +``` + +## Complex Samples + +Below are several examples using the following Vela pipeline + template + +### .vela.yml +```yaml +version: "1" + +templates: + - name: tmpl + source: git.example.com/cloud/vela-templates/kaniko.yml@main + type: github + +steps: + - name: testing + image: alpine:latest + commands: + - echo hello + + - name: file path ruleset + image: alpine:latest + ruleset: + matcher: regexp + path: [ src/* ] + commands: + - echo ran + + - name: docker build + template: + name: tmpl + vars: + repo: docker.example.com/octocat/hello-world +``` + +### kaniko.yml Template +```yaml +version: "1" + +metadata: + template: true + +environment: + REPO: {{ .repo }} + +secrets: + - name: docker_username + key: octocat/docker_username + engine: native + type: org + + - name: docker_password + key: octocat/docker_password + engine: native + type: org + +steps: + - name: Build and Publish + image: target/vela-kaniko:latest + secrets: [ docker_username, docker_password ] + parameters: + registry: docker.example.com + repo: ${REPO} +``` + +### Remote Template + Local Environment Onboarding + +```sh +$ DOCKER_USERNAME=octocat DOCKER_PASSWORD=abc123 VELA_BUILD_COMMIT=1a2b3c vela exec pipeline --ct --cgu https://git.example.com --local-env +``` + +Note: `--local-env` onboards the entire bash environment. To load specific environment variables, use `--env-vars`: + +```sh +$ vela exec pipeline --ct --cgu https://git.example.com --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c +``` + +### Template Override + +```sh +$ vela exec pipeline --template-file tmpl:path/to/template.yml --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c +``` + +### Environment File + +`.env` +``` +DOCKER_USERNAME=octocat +DOCKER_PASSWORD=abc123 +VELA_BUILD_COMMIT=1a2b3c +``` + +```sh +$ vela exec pipeline --ct --cgu https://git.example.com --env-file +``` + +`vela_exec.env` +``` +DOCKER_USERNAME=octocat +DOCKER_PASSWORD=abc123 +VELA_BUILD_COMMIT=1a2b3c +``` + +```sh +$ vela exec pipeline --ct --cgu https://git.example.com --env-file-path vela_exec.env +``` + +### Path Ruleset Inclusion + +In order to execute steps with rulesets, be sure to include all necessary flags that match the rules + +```sh +$ vela exec pipeline --ct --cgu https://git.example.com --env-file --file-changeset src/main.go +``` + +Other rules: `--branch`, `--event`, `--comment`, `--tag`, `--target` + diff --git a/docs/reference/cli/pipeline/generate.md b/docs/reference/cli/pipeline/generate.md new file mode 100644 index 0000000..5ccd8d2 --- /dev/null +++ b/docs/reference/cli/pipeline/generate.md @@ -0,0 +1,53 @@ +--- +title: "Generate" +linkTitle: "Generate" +description: > + Learn how to produce a pipeline. +--- + +## Command + +``` +$ vela generate pipeline +``` + +:::tip +For more information, you can run `vela generate pipeline --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | ---------------------------------- | -------------------------------- | +| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | +| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | +| `stages` | generates the pipeline with stages | `VELA_STAGES`, `PIPELINE_STAGES` | +| `type` | type of pipeline being generated | `VELA_TYPE`, `PIPELINE_TYPE` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela generate pipeline +``` + +#### Response + +```sh +".vela.yml" go pipeline generated +``` diff --git a/docs/reference/cli/pipeline/get.md b/docs/reference/cli/pipeline/get.md new file mode 100644 index 0000000..52f9e42 --- /dev/null +++ b/docs/reference/cli/pipeline/get.md @@ -0,0 +1,74 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list pipelines. +--- + +## Command + +``` +$ vela get pipeline +``` + +:::tip +For more information, you can run `vela get pipeline --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- |----------------------------------------| -------------------------------- | +| `org` | name of organization for the pipelines | `VELA_ORG`, `HOOK_ORG` | +| `repo` | name of repository for the pipelines | `VELA_REPO`, `HOOK_REPO` | +| `output` | format the output for the pipelines | `VELA_OUTPUT`, `HOOK_OUTPUT` | +| `page` | prints a specific page of pipelines | `VELA_PAGE`, `HOOK_PAGE` | +| `per.page` | number of pipelines to print per page | `VELA_PER_PAGE`, `HOOK_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get pipeline +``` + +#### Targeted Request + +```sh +$ vela get pipeline --org github --repo octocat +``` + +#### Response + +```sh +COMMIT REF TYPE VERSION STAGES STEPS +a49aaf4afae6431a79239c95247a2b169fd9f067 refs/heads/main yaml 1 f t +48afb5bdc41ad69bf22588491333f7cf71135163 refs/heads/main yaml 1 f t +``` diff --git a/docs/reference/cli/pipeline/pipeline.md b/docs/reference/cli/pipeline/pipeline.md new file mode 100644 index 0000000..d399759 --- /dev/null +++ b/docs/reference/cli/pipeline/pipeline.md @@ -0,0 +1,16 @@ +--- +title: "Pipeline" +linkTitle: "Pipeline" +description: > + Learn how to use CLI commands for the pipeline resource. +--- + +The below commands are available to operate on the `pipeline` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/pipeline/validate.md b/docs/reference/cli/pipeline/validate.md new file mode 100644 index 0000000..d609ce7 --- /dev/null +++ b/docs/reference/cli/pipeline/validate.md @@ -0,0 +1,83 @@ +--- +title: "Validate" +linkTitle: "Validate" +description: > + Learn how to validate a Vela pipeline. +--- + +## Command + +``` +$ vela validate pipeline +``` + +:::tip +For more information, please run `vela validate pipeline --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| `org` | name of organization for the builds | `VELA_ORG`, `BUILD_ORG` | +| `pipeline-type` | provide the repository pipeline type | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | +| `repo` | name of repository for the builds | `VELA_REPO`, `BUILD_REPO` | +| `compiler-starlark-exec-limit` | set the starlark execution step limit for compiling starlark pipelines (default 7500) | `VELA_COMPILER_STARLARK_EXEC_LIMIT`, `COMPILER_STARLARK_EXEC_LIMIT` | +| `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | +| `max-template-depth` | set the maximum depth for nested templates (default: 3) | `VELA_MAX_TEMPLATE_DEPTH`, `MAX_TEMPLATE_DEPTH` | +| `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | +| `ref` | repository reference for the pipeline | `VELA_REF`, `PIPELINE_REF` | +| `remote` | enables validating a pipeline on a remote server | `VELA_REMOTE`, `PIPELINE_REMOTE` | +| `template` | enables templates to be included in pipeline validation | `VELA_TEMPLATE`, `PIPELINE_TEMPLATE` | +| `template-file` | enables using a local template file for expansion | `VELA_TEMPLATE_FILE`, `PIPELINE_TEMPLATE_FILE` | +| `branch` | provide the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH`, `VELA_BUILD_BRANCH` | +| `comment` | provide the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT`, `VELA_BUILD_COMMENT` | +| `event` | provide the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT`, `VELA_BUILD_EVENT` | +| `file-changeset` | provide a list of files changed for ruleset matching | `VELA_FILE_CHANGESET`, `FILE_CHANGESET` | +| `status` | provide the expected build status for the local validation (default: "success") | `VELA_STATUS`, `PIPELINE_STATUS`, `VELA_BUILD_STATUS` | +| `tag` | provide the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG`, `VELA_BUILD_TAG` | +| `target` | provide the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET`, `VELA_BUILD_TARGET` | +| `clone-image` | the clone image to use for the injected clone step | `VELA_CLONE_IMAGE`, `COMPILER_CLONE_IMAGE` | +| `compiler.github.token` | github compiler token | `VELA_COMPILER_GITHUB_TOKEN`, `COMPILER_GITHUB_TOKEN` | +| `compiler.github.url` | github url, used by compiler, for pulling registry templates | `VELA_COMPILER_GITHUB_URL`, `COMPILER_GITHUB_URL` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Simple Request + +```sh +vela validate pipeline +``` + +#### Expanded Template Request (GitHub) + +```sh +vela validate pipeline --template --compiler.github.token --compiler.github.url https://git.example.com +``` + +#### Expanded Template Request (Local) + +```sh +vela validate pipeline --template --template-file name:/path/to/file +``` + +#### Response + +```sh +".vela.yml" is valid +``` + +Using a template in your pipeline? You can [validate templates also](/docs/templates/working_with/#cli-pipeline-validation). diff --git a/docs/reference/cli/repo/_category_.json b/docs/reference/cli/repo/_category_.json deleted file mode 100644 index da68eb5..0000000 --- a/docs/reference/cli/repo/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Repo", - "position": 1, - "link": {"type": "generated-index"}, -} diff --git a/docs/reference/cli/repo/add.md b/docs/reference/cli/repo/add.md index 5404cba..937b326 100644 --- a/docs/reference/cli/repo/add.md +++ b/docs/reference/cli/repo/add.md @@ -1,6 +1,8 @@ --- title: "Add" -sidebar_position: 1 +linkTitle: "Add" +description: > + Learn how to create a repo. --- ## Command @@ -9,7 +11,7 @@ sidebar_position: 1 $ vela add repo ``` -:::info +:::tip For more information, you can run `vela add repo --help`. ::: @@ -35,7 +37,7 @@ The following parameters are used to configure the command: | `pipeline-type` | type of base pipeline for the compiler to render | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | | `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | -:::info +:::tip This command also supports setting the following parameters via a configuration file: - `org` @@ -45,12 +47,16 @@ This command also supports setting the following parameters via a configuration For more information, please review the [CLI config documentation](/docs/reference/cli/config/). ::: +## Permissions + +COMING SOON! + ## Sample -:::info +:::warning This section assumes you have already installed and setup the CLI. -To install the CLI, please review the [installation documentation](/docs/reference/cli/install/). +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). ::: diff --git a/docs/reference/cli/repo/chown.md b/docs/reference/cli/repo/chown.md new file mode 100644 index 0000000..48eaa28 --- /dev/null +++ b/docs/reference/cli/repo/chown.md @@ -0,0 +1,72 @@ +--- +title: "Chown" +linkTitle: "Chown" +description: > + Learn how to change ownership of a repo. +--- + +## Command + +``` +$ vela chown repo +``` + +:::tip +For more information, you can run `vela chown repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------------- | ---------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela chown repo +``` + +#### Targeted Request + +```sh +$ pwd +~/github/octocat +$ vela chown repo --org github --repo octocat +``` + +#### Response + +```sh +repo "github/octocat" changed owner +``` diff --git a/docs/reference/cli/repo/get.md b/docs/reference/cli/repo/get.md new file mode 100644 index 0000000..4b4935a --- /dev/null +++ b/docs/reference/cli/repo/get.md @@ -0,0 +1,65 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list repos. +--- + +## Command + +``` +$ vela get repo +``` + +:::tip +For more information, you can run `vela get repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ----------------------------------------- | -------------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | +| `page` | prints a specific page of repositories | `VELA_PAGE`, `REPO_PAGE` | +| `per.page` | number of repositories to print per page | `VELA_PER_PAGE`, `REPO_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela get repos +``` + +#### Response + +```sh +ORG/REPO STATUS EVENTS VISIBILITY BRANCH +github/octocat true push,pull_request public main +``` diff --git a/docs/reference/cli/repo/remove.md b/docs/reference/cli/repo/remove.md new file mode 100644 index 0000000..5d001e1 --- /dev/null +++ b/docs/reference/cli/repo/remove.md @@ -0,0 +1,72 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a repo. +--- + +## Command + +``` +$ vela remove repo +``` + +:::tip +For more information, you can run `vela remove repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------------- | ---------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela remove repo +``` + +#### Targeted Request + +```sh +$ pwd +~/github/octocat +$ vela remove repo --org github --repo octocat +``` + +#### Response + +```sh +repo "github/octocat" was deleted +``` diff --git a/docs/reference/cli/repo/repair.md b/docs/reference/cli/repo/repair.md new file mode 100644 index 0000000..5acd246 --- /dev/null +++ b/docs/reference/cli/repo/repair.md @@ -0,0 +1,70 @@ +--- +title: "Repair" +linkTitle: "Repair" +description: > + Learn how to restore a repo. +--- + +## Command + +``` +$ vela repair repo +``` + +:::tip +For more information, you can run `vela repair repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------------- | ---------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela repair repo +``` + +#### Targeted Request + +```sh +$ vela repair repo --org github --repo octocat +``` + +#### Response + +```sh +repo "github/octocat" repaired +``` diff --git a/docs/reference/cli/repo/repo.md b/docs/reference/cli/repo/repo.md new file mode 100644 index 0000000..723d41f --- /dev/null +++ b/docs/reference/cli/repo/repo.md @@ -0,0 +1,16 @@ +--- +title: "Repo" +linkTitle: "Repo" +description: > + Learn how to use CLI commands for the repo resource. +--- + +The below commands are available to operate on the `repo` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/repo/sync.md b/docs/reference/cli/repo/sync.md new file mode 100644 index 0000000..f52988d --- /dev/null +++ b/docs/reference/cli/repo/sync.md @@ -0,0 +1,96 @@ +--- +title: "Sync" +linkTitle: "Sync" +description: > + Learn how to sync repos in database with GitHub. +--- + +## Command + +``` +$ vela sync repo +``` + +:::tip +For more information, you can run `vela sync repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------------- | ---------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `all` | bool flag to sync all repos in an org | `VELA_SYNC_ALL`, `SYNC_ALL` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Description + +The sync command allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. + +Further, as of `v0.19.0`, the sync command can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like + +```sh +"unable to process webhook: / does not have comment events enabled" +``` + +running the sync command should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to run this command again, even if the subscribed events are changed. + +## Samples + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela sync repo +``` + +#### Targeted Request + +```sh +$ vela sync repo --org github --repo octocat +``` + +#### Response + +```sh +repo "github/octocat" synced +``` + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela sync repo --all +``` + +#### Targeted Request + +```sh +$ vela sync repo --org github --all +``` + +#### Response + +```sh +org "github" synced \ No newline at end of file diff --git a/docs/reference/cli/repo/update.md b/docs/reference/cli/repo/update.md new file mode 100644 index 0000000..2c72805 --- /dev/null +++ b/docs/reference/cli/repo/update.md @@ -0,0 +1,113 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a repo. +--- + +## Command + +``` +$ vela update repo +``` + +:::tip +For more information, you can run `vela update repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | -------------------------------------------------- | -------------------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `branch` | default branch for the repository | `VELA_BRANCH`, `REPO_BRANCH` | +| `link` | full URL for the repository | `VELA_LINK`, `REPO_LINK` | +| `clone` | clone URL for the repository | `VELA_CLONE`, `REPO_CLONE` | +| `visibility` | access level required to view the repository | `VELA_VISIBILITY`, `REPO_VISIBILITY` | +| `build.limit` | limit of concurrent builds allowed for repository | `VELA_BUILD_LIMIT`, `REPO_BUILD_LIMIT` | +| `timeout` | max time allowed per build | `VELA_TIMEOUT`, `REPO_TIMEOUT` | +| `counter` | set a value for a new build number | `VELA_COUNTER`, `REPO_COUNTER` | +| `private` | disables public access to the repository | `VELA_PRIVATE`, `REPO_PRIVATE` | +| `trusted` | elevates permissions for builds for the repository | `VELA_TRUSTED`, `REPO_TRUSTED` | +| `active` | enables/disables the repository | `VELA_ACTIVE`, `REPO_ACTIVE` | +| `event` | events to trigger builds for the repository | `VELA_EVENTS`, `REPO_EVENTS` | +| `pipeline-type` | type of base pipeline for the compiler to render | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +:::warning +As of Vela `v0.23.0`, the `event` flag is an overwrite/clobber operation. + +```sh +$ vela update repo --org github --repo octocat --event tag +``` + +The above will set the allowed events to only `tag`. Be sure to specify _all_ events when updating a repo via the CLI. +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela update repo --event tag +``` + +#### Targeted Request + +```sh +$ vela update repo --org github --repo octocat --event tag +``` + +#### Response + +```sh +id: 1 +userid: 1 +org: github +name: octocat +fullname: github/octocat +link: https://github.com/github/octocat +clone: https://github.com/github/octocat.git +branch: main +buildlimit: 10 +timeout: 60 +counter: 0 +visibility: public +private: false +trusted: false +active: true +allowpull: true +allowpush: true +allowdeploy: false +allowtag: true +allowcomment: false +allowevents: [tag] +pipelinetype: yaml +``` diff --git a/docs/reference/cli/repo/view.md b/docs/reference/cli/repo/view.md new file mode 100644 index 0000000..440f660 --- /dev/null +++ b/docs/reference/cli/repo/view.md @@ -0,0 +1,90 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a repo. +--- + +## Command + +``` +$ vela view repo +``` + +:::tip +For more information, you can run `vela view repo --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------------- | ---------------------------- | +| `org` | name of organization for the repository | `VELA_ORG`, `REPO_ORG` | +| `repo` | name of repository | `VELA_REPO`, `REPO_NAME` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `REPO_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view repo +``` + +#### Targeted Request + +```sh +$ vela view repo --org github --repo octocat +``` + +#### Response + +```sh +id: 1 +userid: 1 +org: github +name: octocat +fullname: github/octocat +link: https://github.com/github/octocat +clone: https://github.com/github/octocat.git +branch: main +buildlimit: 10 +timeout: 60 +counter: 0 +visibility: public +private: false +trusted: false +active: true +allowpull: true +allowpush: true +allowdeploy: false +allowtag: false +allowcomment: false +pipelinetype: yaml +``` diff --git a/docs/reference/cli/schedule/add.md b/docs/reference/cli/schedule/add.md new file mode 100644 index 0000000..56ad364 --- /dev/null +++ b/docs/reference/cli/schedule/add.md @@ -0,0 +1,146 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a schedule. +--- + +## Command + +``` +$ vela add schedule +``` + +:::tip +For more information, you can run `vela add schedule --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +|------------|---------------------------------------|----------------------------------| +| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | +| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | +| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | +| `entry` | frequency for the schedule | `VELA_ENTRY`, `SCHEDULE_ENTRY` | +| `active` | enables/disables the schedule | `VELA_ACTIVE`, `SCHEDULE_ACTIVE` | +| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela add schedule --schedule hourly --entry '0 * * * *' +``` + +#### Targeted Request + +```sh +$ vela add schedule --org github --repo octocat --schedule hourly --entry '0 * * * *' --output json +``` + +#### Response +```sh +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` + +## Examples + +```sh +EXAMPLES: + 1. Add a schedule to a repository with active not enabled. + $ vela add schedule --org MyOrg --repo MyRepo --schedule hourly --entry '0 * * * *' --active false + 2. Add a schedule to a repository with a nightly entry. + $ vela add schedule --org MyOrg --repo MyRepo --schedule nightly --entry '0 0 * * *' + 3. Add a schedule to a repository with a weekly entry. + $ vela add schedule --org MyOrg --repo MyRepo --schedule weekly --entry '@weekly' + 4. Add a schedule to a repository when config or environment variables are set. + $ vela add schedule +``` \ No newline at end of file diff --git a/docs/reference/cli/schedule/get.md b/docs/reference/cli/schedule/get.md new file mode 100644 index 0000000..b86de87 --- /dev/null +++ b/docs/reference/cli/schedule/get.md @@ -0,0 +1,85 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list schedules. +--- + +## Command + +``` +$ vela get schedule +``` + +:::tip +For more information, you can run `vela get schedule --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +|------------|----------------------------------------|--------------------------------------| +| `org` | name of organization for the schedules | `VELA_ORG`, `SCHEDULE_ORG` | +| `repo` | name of repository for the schedules | `VELA_REPO`, `SCHEDULE_REPO` | +| `output` | format the output for the schedules | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | +| `page` | prints a specific page of schedules | `VELA_PAGE`, `SCHEDULE_PAGE` | +| `per.page` | number of schedules to print per page | `VELA_PER_PAGE`, `SCHEDULE_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get schedule +``` + +#### Targeted Request + +```sh +$ vela get schedule --org github --repo octocat +``` + +#### Response +```sh +NAME ENTRY ACTIVE SCHEDULED_AT BRANCH +nightly 0 0 * * * true a long while ago main +hourly 0 * * * * true a long while ago main +``` + +## Examples + +```sh +EXAMPLES: + 1. Get a list of schedules for a repository. + $ vela get schedule --org MyOrg --repo MyRepo + 2. Get a list of schedules for a repository with wide view output. + $ vela get schedule --org MyOrg --repo MyRepo --output wide + 3. Get a list of schedules for a repository with yaml output. + $ vela get schedule --org MyOrg --repo MyRepo --output yaml + 4. Get a list of schedules for a repository with json output. + $ vela get schedule --org MyOrg --repo MyRepo --output json + 5. Get a list of schedules for a repository when config or environment variables are set. + $ vela get schedule +``` \ No newline at end of file diff --git a/docs/reference/cli/schedule/remove.md b/docs/reference/cli/schedule/remove.md new file mode 100644 index 0000000..130321d --- /dev/null +++ b/docs/reference/cli/schedule/remove.md @@ -0,0 +1,85 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a schedule. +--- + +## Command + +``` +$ vela remove schedule +``` + +:::tip +For more information, you can run `vela remove schedule --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +|------------|---------------------------------------|----------------------------------| +| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | +| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | +| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | +| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela remove schedule --schedule hourly +``` + +#### Targeted Request + +```sh +$ pwd +~/github/octocat +$ vela remove schedule --org github --repo octocat --schedule hourly +``` + +#### Response + +```sh +schedule hourly deleted +``` + +## Examples + +```sh +EXAMPLES: + 1. Remove a schedule from a repository. + $ vela remove schedule --org MyOrg --repo MyRepo --schedule daily + 2. Remove a schedule from a repository with json output. + $ vela remove schedule --org MyOrg --repo MyRepo --schedule daily --output json + 3. Remove a schedule from a repository when config or environment variables are set. + $ vela remove schedule +``` \ No newline at end of file diff --git a/docs/reference/cli/schedule/schedule.md b/docs/reference/cli/schedule/schedule.md new file mode 100644 index 0000000..f0884eb --- /dev/null +++ b/docs/reference/cli/schedule/schedule.md @@ -0,0 +1,16 @@ +--- +title: "Schedule" +linkTitle: "Schedule" +description: > + Learn how to use CLI commands for the schedule resource. +--- + +The below commands are available to operate on the `schedule` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: \ No newline at end of file diff --git a/docs/reference/cli/schedule/update.md b/docs/reference/cli/schedule/update.md new file mode 100644 index 0000000..3fa70be --- /dev/null +++ b/docs/reference/cli/schedule/update.md @@ -0,0 +1,149 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a schedule. +--- + +## Command + +``` +$ vela update schedule +``` + +:::tip +For more information, you can run `vela update schedule --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +|------------|---------------------------------------|----------------------------------| +| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | +| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | +| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | +| `entry` | frequency for the schedule | `VELA_ENTRY`, `SCHEDULE_ENTRY` | +| `active` | enables/disables the schedule | `VELA_ACTIVE`, `SCHEDULE_ACTIVE` | +| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela update schedule --name hourly --active false +``` + +#### Targeted Request + +```sh +$ vela update schedule --org github --repo octocat --name hourly --active false --output json +``` + +#### Response + +```sh +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": false, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` + +## Examples + +```sh +EXAMPLES: + 1. Update a schedule for a repository with active disabled. + $ vela update schedule --org MyOrg --repo MyRepo --schedule hourly --active false + 2. Update a schedule for a repository with a new entry. + $ vela update schedule --org MyOrg --repo MyRepo --schedule nightly --entry '@nightly' + 3. Update a schedule for a repository when config or environment variables are set. + $ vela update schedule +``` \ No newline at end of file diff --git a/docs/reference/cli/schedule/view.md b/docs/reference/cli/schedule/view.md new file mode 100644 index 0000000..135084b --- /dev/null +++ b/docs/reference/cli/schedule/view.md @@ -0,0 +1,142 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a schedule. +--- + +## Command + +``` +$ vela view schedule +``` + +:::tip +For more information, you can run `vela view schedule --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +|------------|---------------------------------------|----------------------------------| +| `org` | name of organization for the schedule | `VELA_ORG`, `SCHEDULE_ORG` | +| `repo` | name of repository for the schedule | `VELA_REPO`, `SCHEDULE_REPO` | +| `schedule` | name of the schedule | `VELA_SCHEDULE`, `SCHEDULE_NAME` | +| `output` | format the output for the schedule | `VELA_OUTPUT`, `SCHEDULE_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view schedule --schedule hourly +``` + +#### Targeted Request + +```sh +$ vela view schedule --org github --repo octocat --schedule hourly --output json +``` + +#### Response +```sh +{ + "id": 1, + "repo": { + "id": 1, + "owner": { + "id": 1, + "name": "octokitty", + "active": true + }, + "org": "github", + "name": "octokitty", + "full_name": "github/octokitty", + "link": "https://github.com/github/octokitty", + "clone": "https://github.com/github/octokitty.git", + "branch": "main", + "topics": [], + "build_limit": 10, + "timeout": 30, + "counter": 0, + "visibility": "public", + "private": false, + "trusted": false, + "active": true, + "allow_events": { + "push": { + "branch": true, + "tag": false, + "delete_branch": false, + "delete_tag": false + }, + "pull_request": { + "opened": false, + "edited": false, + "synchronize": false, + "reopened": false, + "labeled": false, + "unlabeled": false + }, + "deployment": { + "created": false + }, + "comment": { + "created": false, + "edited": false + }, + "schedule": { + "run": false + } + }, + "pipeline_type": "yaml", + "previous_name": "", + "approve_build": "fork-always" + }, + "active": true, + "name": "hourly", + "entry": "0 * * * *", + "created_at": 1716495910, + "created_by": "octokitty", + "updated_at": 1716495910, + "updated_by": "octokitty", + "scheduled_at": 0, + "branch": "main", + "error": "", + "next_run": 1716499800 +} +``` + +## Examples + +```sh +EXAMPLES: + 1. View details of a schedule for a repository. + $ vela view schedule --org MyOrg --repo MyRepo --schedule hourly + 2. View details of a schedule for a repository with json output. + $ vela view schedule --org MyOrg --repo MyRepo --schedule hourly --output json + 3. View details of a schedule for a repository when config or environment variables are set. + $ vela view schedule +``` \ No newline at end of file diff --git a/docs/reference/cli/secret/add.md b/docs/reference/cli/secret/add.md new file mode 100644 index 0000000..4123b57 --- /dev/null +++ b/docs/reference/cli/secret/add.md @@ -0,0 +1,177 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a secret. +--- + +## Command + +``` +$ vela add secret +``` + +:::tip +For more information, you can run `vela add secret --help`. +::: + +:::warning +Note on special characters: + +Certain characters may require you to encapsulate your secret with `"` or `'`. +`\` characters have to be double escaped to be `\\\`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------------------ | ----------------------------------------- | +| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | +| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | +| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | +| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | +| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | +| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | +| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` | +| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` | +| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` | +| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` | +| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` | +| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` | +| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `secret.engine` +- `secret.type` +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela add secret --secret.engine native --secret.type repo --name foo --value bar +``` + +#### Targeted Request + +```sh +$ vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value bar +``` + +#### Response + +```sh +secret "foo" was added +``` + +## Advanced + +#### Input From File + +Vela supports creating a single-line or multi-line secret from a file using the `@` symbol. + +```sh +# Syntax +vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @/path/to/file + +# Example +vela add secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @$HOME/tmp/secret.txt +``` + +#### Secrets From File + +Vela supports creating multiple secrets from a file using the `filename` parameter. + +```sh +vela add secret -f secret.yml +``` + +##### Single YAML document + +```yaml +--- +metadata: + version: v1 + engine: native +secrets: + - org: octocat + repo: github + name: foo + value: bar + type: repo + images: + - golang:latest + events: + - push + - pull_request + - org: github + team: octokitties + name: foo1 + value: "@/path/to/file/bar1" + type: shared + images: + - golang:latest + events: + - push + - pull_request +``` + +##### Multiple YAML document + +```yaml +--- +metadata: + version: v1 + engine: native +secrets: + - org: github + repo: octocat + name: foo + value: bar + type: repo + images: + - golang:latest + events: + - push + - pull_request + +--- +metadata: + version: v1 + engine: vault +secrets: + - org: github + team: octokitties + name: foo1 + value: "@/path/to/file/bar1" + type: shared + images: + - golang:latest + events: + - push + - pull_request +``` diff --git a/docs/reference/cli/secret/get.md b/docs/reference/cli/secret/get.md new file mode 100644 index 0000000..2b92891 --- /dev/null +++ b/docs/reference/cli/secret/get.md @@ -0,0 +1,76 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list secrets. +--- + +## Command + +``` +$ vela get secret +``` + +:::tip +For more information, you can run `vela get secret --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | --------------------------------------------------- | ------------------------------ | +| `org` | name of organization for the secrets | `VELA_ORG`, `SECRET_ORG` | +| `repo` | name of repository for the secrets | `VELA_REPO`, `SECRET_REPO` | +| `secret.engine` | name of engine that stores the secrets | `VELA_ENGINE`. `SECRET_ENGINE` | +| `secret.type` | name of type of secrets being stored | `VELA_TYPE`, `SECRET_TYPE` | +| `team` | name of team for the secrets, or '\*' for all teams | `VELA_TEAM`, `SECRET_TEAM` | +| `output` | format the output for the secrets | `VELA_OUTPUT`, `SECRET_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `secret.engine` +- `secret.type` +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get secret --secret.engine native --secret.type repo +``` + +#### Targeted Request + +```sh +$ vela get secret --secret.engine native --secret.type repo --org github --repo octocat +``` + +#### Response + +```sh +NAME ORG TYPE EVENTS +foo github/octocat repo push,pull_request +``` diff --git a/docs/reference/cli/secret/remove.md b/docs/reference/cli/secret/remove.md new file mode 100644 index 0000000..3a56e99 --- /dev/null +++ b/docs/reference/cli/secret/remove.md @@ -0,0 +1,78 @@ +--- +title: "Remove" +linkTitle: "Remove" +description: > + Learn how to delete a secret. +--- + +## Command + +``` +$ vela remove secret +``` + +:::tip +For more information, you can run `vela remove secret --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------- | ------------------------------ | +| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | +| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | +| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | +| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | +| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | +| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | +| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `secret.engine` +- `secret.type` +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela remove secret --secret.engine native --secret.type repo --name foo +``` + +#### Targeted Request + +```sh +$ pwd +~/github/octocat +$ vela remove secret --secret.engine native --secret.type repo --org github --repo octocat --name foo +``` + +#### Response + +```sh +secret "foo" was deleted +``` diff --git a/docs/reference/cli/secret/secret.md b/docs/reference/cli/secret/secret.md new file mode 100644 index 0000000..237a0a4 --- /dev/null +++ b/docs/reference/cli/secret/secret.md @@ -0,0 +1,16 @@ +--- +title: "Secret" +linkTitle: "Secret" +description: > + Learn how to use CLI commands for the secret resource. +--- + +The below commands are available to operate on the `secret` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/secret/update.md b/docs/reference/cli/secret/update.md new file mode 100644 index 0000000..2e7e76f --- /dev/null +++ b/docs/reference/cli/secret/update.md @@ -0,0 +1,170 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a secret. +--- + +## Command + +``` +$ vela update secret +``` + +:::tip +For more information, you can run `vela update secret --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------------------ | ----------------------------------------- | +| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | +| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | +| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | +| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | +| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | +| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | +| `value` | value of the secret | `VELA_VALUE`, `SECRET_VALUE` | +| `image` | build image(s) that can access the secret | `VELA_IMAGES`, `SECRET_IMAGES` | +| `event` | build event(s) that can access the secret | `VELA_EVENTS`, `SECRET_EVENTS` | +| `commands` | allows a step with commands to access the secret | `VELA_COMMANDS`, `SECRET_COMMANDS` | +| `substitution` | allows substitution of secret using $\{KEY\} format | `VELA_SUBSTITUTION`, `SECRET_SUBSTITUTION` | +| `file` | name of file used to add the secret(s) | `VELA_FILE`, `SECRET_FILE` | +| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `secret.engine` +- `secret.type` +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela update secret --secret.engine native --secret.type repo --name foo --value bar +``` + +#### Targeted Request + +```sh +$ vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value bar +``` + +#### Response + +```sh +secret "foo" was updated +``` + +## Advanced + +#### Input From File + +Vela supports updating a single-line or multi-line secret from a file using the `@` symbol. + +```sh +# Syntax +vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @/path/to/file + +# Example +vela update secret --secret.engine native --secret.type repo --org github --repo octocat --name foo --value @$HOME/tmp/secret.txt +``` + +#### Secrets From File + +Vela supports updating multiple secrets from a file using the `filename` parameter. + +```sh +vela update secret -f secret.yml +``` + +##### Single YAML document + +```yaml +--- +metadata: + version: v1 + engine: native +secrets: + - org: octocat + repo: github + name: foo + value: bar + type: repo + images: + - golang:latest + events: + - push + - pull_request + - org: github + team: octokitties + name: foo1 + value: "@/path/to/file/bar1" + type: shared + images: + - golang:latest + events: + - push + - pull_request +``` + +##### Multiple YAML document + +```yaml +--- +metadata: + version: v1 + engine: native +secrets: + - org: github + repo: octocat + name: foo + value: bar + type: repo + images: + - golang:latest + events: + - push + - pull_request + +--- +metadata: + version: v1 + engine: vault +secrets: + - org: github + team: octokitties + name: foo1 + value: "@/path/to/file/bar1" + type: shared + images: + - golang:latest + events: + - push + - pull_request +``` diff --git a/docs/reference/cli/secret/view.md b/docs/reference/cli/secret/view.md new file mode 100644 index 0000000..4f33584 --- /dev/null +++ b/docs/reference/cli/secret/view.md @@ -0,0 +1,93 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a secret. +--- + +## Command + +``` +$ vela view secret +``` + +:::tip +For more information, you can run `vela view secret --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------- | ------------------------------ | +| `org` | name of organization for the secret | `VELA_ORG`, `SECRET_ORG` | +| `repo` | name of repository for the secret | `VELA_REPO`, `SECRET_REPO` | +| `secret.engine` | name of engine that stores the secret | `VELA_ENGINE`. `SECRET_ENGINE` | +| `secret.type` | name of type of secret being stored | `VELA_TYPE`, `SECRET_TYPE` | +| `team` | name of team for the secret | `VELA_TEAM`, `SECRET_TEAM` | +| `name` | name of the secret | `VELA_NAME`, `SECRET_NAME` | +| `output` | format the output for the secret | `VELA_OUTPUT`, `SECRET_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `secret.engine` +- `secret.type` +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view secret --secret.engine native --secret.type repo --name foo +``` + +#### Targeted Request + +```sh +$ pwd +~/github/octocat +$ vela view secret --secret.engine native --secret.type repo --org github --repo octocat --name foo +``` + +#### Response + +```sh +id: 1 +org: github +repo: octocat +team: "" +name: foo +value: "[secure]" +type: repo +images: null +events: + - push + - pull_request +allowcommand: true +createdat: 1641312765 +createdby: octokitty +updatedat: 1641312765 +updatedby: octokitty +``` diff --git a/docs/reference/cli/service/get.md b/docs/reference/cli/service/get.md new file mode 100644 index 0000000..81cf2df --- /dev/null +++ b/docs/reference/cli/service/get.md @@ -0,0 +1,77 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list services. +--- + +## Command + +``` +$ vela get service +``` + +:::tip +For more information, you can run `vela get service --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ------------------------------------- | ----------------------------------- | +| `org` | name of organization for the services | `VELA_ORG`, `SERVICE_ORG` | +| `repo` | name of repository for the services | `VELA_REPO`, `SERVICE_REPO` | +| `build` | number of build for the services | `VELA_BUILD`, `SERVICE_BUILD` | +| `output` | format the output for the services | `VELA_OUTPUT`, `SERVICE_OUTPUT` | +| `page` | prints a specific page of services | `VELA_PAGE`, `SERVICE_PAGE` | +| `per.page` | number of services to print per page | `VELA_PER_PAGE`, `SERVICE_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get service --build 1 +``` + +#### Targeted Request + +```sh +$ vela get service --org github --repo octocat --build 1 +``` + +#### Response + +```sh +NAME STATUS RUNTIME DURATION +publish failure 1s +build success 17s +test success 10s +clone success 2s +``` diff --git a/docs/reference/cli/service/service.md b/docs/reference/cli/service/service.md new file mode 100644 index 0000000..ecc9b03 --- /dev/null +++ b/docs/reference/cli/service/service.md @@ -0,0 +1,16 @@ +--- +title: "Service" +linkTitle: "Service" +description: > + Learn how to use CLI commands for the service resource. +--- + +The below commands are available to operate on the `service` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/service/view.md b/docs/reference/cli/service/view.md new file mode 100644 index 0000000..11ced9d --- /dev/null +++ b/docs/reference/cli/service/view.md @@ -0,0 +1,85 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a service. +--- + +## Command + +``` +$ vela view service +``` + +:::tip +For more information, you can run `vela view service --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------- | ------------------------------------ | -------------------------------- | +| `org` | name of organization for the service | `VELA_ORG`, `SERVICE_ORG` | +| `repo` | name of repository for the service | `VELA_REPO`, `SERVICE_REPO` | +| `build` | number of build for the service | `VELA_BUILD`, `SERVICE_BUILD` | +| `service` | number of the service | `VELA_SERVICE`, `SERVICE_NUMBER` | +| `output` | format the output for the service | `VELA_OUTPUT`, `SERVICE_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view service --build 1 --service 1 +``` + +#### Targeted Request + +```sh +$ vela get service --org github --repo octocat --build 1 --service 1 +``` + +#### Response + +```sh +id: 1 +build_id: 1 +repo_id: 1 +number: 1 +name: clone +status: success +error: "" +exitcode: 0 +created: 1561748980 +started: 1561748979 +finished: 1561748981 +host: "worker.host.com" +runtime: "docker" +distribution: "linux" +``` diff --git a/docs/reference/cli/settings/settings.md b/docs/reference/cli/settings/settings.md new file mode 100644 index 0000000..8ea4388 --- /dev/null +++ b/docs/reference/cli/settings/settings.md @@ -0,0 +1,16 @@ +--- +title: "Settings" +linkTitle: "Settings" +description: > + Learn how to use CLI commands for platform settings. +--- + +The below commands are available to operate on the `settings` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/settings/update.md b/docs/reference/cli/settings/update.md new file mode 100644 index 0000000..18ea922 --- /dev/null +++ b/docs/reference/cli/settings/update.md @@ -0,0 +1,110 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify platform settings. +--- + +## Command + +``` +$ vela update settings +``` + +:::tip +For more information, you can run `vela update settings --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ------------------------------ | ------------------------------------------------------- | ------------------------------------ | +| `compiler.clone-image` | image used by the compiler to clone repositories | `VELA_COMPILER_CLONE_IMAGE` | +| `compiler.template-depth` | maximum depth of nested templates | `VELA_COMPILER_TEMPLATE_DEPTH` | +| `compiler.starlark-exec-limit` | maximum execution limit for Starlark templates | `VELA_COMPILER_STARLARK_EXEC_LIMIT` | +| `queue.add-route` | add a route to the queue | `VELA_QUEUE_ADD_ROUTES` | +| `queue.drop-route` | drop a route from the queue | `VELA_QUEUE_DROP_ROUTES` | +| `add-repo` | name of repository to add to the global allowlist | `VELA_REPO_ALLOWLIST_ADD_REPOS` | +| `drop-repo` | name of repository to drop from the global allowlist | `VELA_REPO_ALLOWLIST_DROP_REPOS` | +| `add-schedule` | name of repository to add to the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_ADD_REPOS` | +| `drop-schedule` | name of repository to drop from the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_DROP_REPOS` | +| `file` | path to a json/yaml file containing settings updates | `VELA_FILE` | + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela update settings --compiler.clone-image target/vela-git:abc123 --queue.add-route large +``` + +#### Response + +```yaml +id: 1 +compiler: + clone_image: target/vela-git:latest + template_depth: 3 + starlark_exec_limit: 7500 +queue: + routes: + - vela +repo_allowlist: + - 'github/octocat' +schedule_allowlist: + - '*' +created_at: 0 +updated_at: 1715791151 +updated_by: octocat +``` + +## Advanced + +#### Input From File + +Vela supports updating a settings record from a file using the `@` symbol. + +```sh +# Syntax +vela update settings --file @/path/to/file + +# Example +vela update settings --file @$HOME/tmp/settings.yml +``` + +##### Single YAML document + +```yaml +--- +platform: + compiler: + clone_image: target/vela-git:latest + template_depth: 3 + starlark_exec_limit: 7500 + queue: + routes: + - vela + repo_allowlist: + - 'github/octocat' + schedule_allowlist: + - '*' + created_at: 0 + updated_at: 1715791151 + updated_by: octocat +``` diff --git a/docs/reference/cli/settings/view.md b/docs/reference/cli/settings/view.md new file mode 100644 index 0000000..23aaf36 --- /dev/null +++ b/docs/reference/cli/settings/view.md @@ -0,0 +1,58 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect platform settings. +--- + +## Command + +``` +$ vela view settings +``` + +:::tip +For more information, you can run `vela view settings --help`. +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view settings +``` + +#### Response + +```yaml +id: 1 +compiler: + clone_image: target/vela-git:latest + template_depth: 3 + starlark_exec_limit: 7500 +queue: + routes: + - vela +repo_allowlist: + - 'github/octocat' +schedule_allowlist: + - '*' +created_at: 0 +updated_at: 1715791151 +updated_by: octocat +``` diff --git a/docs/reference/cli/step/get.md b/docs/reference/cli/step/get.md new file mode 100644 index 0000000..7ae91b6 --- /dev/null +++ b/docs/reference/cli/step/get.md @@ -0,0 +1,77 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list steps. +--- + +## Command + +``` +$ vela get step +``` + +:::tip +For more information, you can run `vela get step --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ---------------------------------- | -------------------------------- | +| `org` | name of organization for the steps | `VELA_ORG`, `STEP_ORG` | +| `repo` | name of repository for the steps | `VELA_REPO`, `STEP_REPO` | +| `build` | number of build for the steps | `VELA_BUILD`, `STEP_BUILD` | +| `output` | format the output for the steps | `VELA_OUTPUT`, `STEP_OUTPUT` | +| `page` | prints a specific page of steps | `VELA_PAGE`, `STEP_PAGE` | +| `per.page` | number of steps to print per page | `VELA_PER_PAGE`, `STEP_PER_PAGE` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela get step --build 1 +``` + +#### Targeted Request + +```sh +$ vela get step --org github --repo octocat --build 1 +``` + +#### Response + +```sh +NAME STATUS RUNTIME DURATION +publish failure 1s +build success 17s +test success 10s +clone success 2s +``` diff --git a/docs/reference/cli/step/step.md b/docs/reference/cli/step/step.md new file mode 100644 index 0000000..c8b308e --- /dev/null +++ b/docs/reference/cli/step/step.md @@ -0,0 +1,16 @@ +--- +title: "Step" +linkTitle: "Step" +description: > + Learn how to use CLI commands for the step resource. +--- + +The below commands are available to operate on the `step` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/cli/step/view.md b/docs/reference/cli/step/view.md new file mode 100644 index 0000000..73509f0 --- /dev/null +++ b/docs/reference/cli/step/view.md @@ -0,0 +1,85 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a step. +--- + +## Command + +``` +$ vela view step +``` + +:::tip +For more information, you can run `vela view step --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| -------- | --------------------------------- | ---------------------------- | +| `org` | name of organization for the step | `VELA_ORG`, `STEP_ORG` | +| `repo` | name of repository for the step | `VELA_REPO`, `STEP_REPO` | +| `build` | number of build for the step | `VELA_BUILD`, `STEP_BUILD` | +| `step` | number of the step | `VELA_STEP`, `STEP_NUMBER` | +| `output` | format the output for the step | `VELA_OUTPUT`, `STEP_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `org` +- `repo` +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ pwd +~/github/octocat +$ vela view step --build 1 --step 1 +``` + +#### Targeted Request + +```sh +$ vela view step --org github --repo octocat --build 1 --step 1 +``` + +#### Response + +```sh +id: 1 +build_id: 1 +repo_id: 1 +number: 1 +name: clone +status: success +error: "" # Populates when the platform runs into an error with the build +exitcode: 0 +created: 1561748980 +started: 1561748979 +finished: 1561748981 +host: "worker.host.com" +runtime: "docker" +distribution: "linux" +``` diff --git a/docs/reference/cli/validate.md b/docs/reference/cli/validate.md new file mode 100644 index 0000000..292b539 --- /dev/null +++ b/docs/reference/cli/validate.md @@ -0,0 +1,10 @@ +--- +title: "Validate" +sidebar_position: 3 +--- + +:::tip +This command has been moved to `vela validate pipeline`. + +For more information, please see the [command documentation](/docs/reference/cli/pipeline/validate/) +::: diff --git a/docs/reference/cli/version.md b/docs/reference/cli/version.md new file mode 100644 index 0000000..3844b48 --- /dev/null +++ b/docs/reference/cli/version.md @@ -0,0 +1,44 @@ +--- +title: "Version" +sidebar_position: 4 +--- + +## Command + +``` +$ vela version +``` + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +vela version +``` + +#### Response + +```sh +{ + Canonical: v0.7.0, + Major: 0, + Minor: 7, + Patch: 0, + Metadata: { + Architecture: amd64, + BuildDate: 2021-02-01T15:40:21Z, + Compiler: gc, + GitCommit: 6225623858e09b7277f3d274d1ed75289a9eb549, + GoVersion: go1.15.7, + OperatingSystem: darwin, + } +} +``` diff --git a/docs/reference/cli/worker/add.md b/docs/reference/cli/worker/add.md new file mode 100644 index 0000000..8198d1a --- /dev/null +++ b/docs/reference/cli/worker/add.md @@ -0,0 +1,73 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to add a worker (Vela Platform Admins only). +--- + +## Command + +``` +$ vela add worker +``` + +:::tip +For more information, you can run `vela add worker --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ----------------- | -------------------------------- | ----------------------------------------- | +| `worker.address` | address of the worker | `VELA_WORKER_ADDRESS`, `WORKER_ADDRESS` | +| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | +| `output` | format the output for the worker | `VELA_OUTPUT`, `WORKER_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +Vela Platform Admin + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI and are authenticated as a Vela platform admin. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela add worker --worker.address myworker.example.com +``` + +:::tip +Not passing `--worker.hostname` will automatically use the hostname part of the passed in `--worker.address` as the hostname. +::: + +#### Response generated from successful CLI command +```sh +worker registered successfully +``` + +## Examples + +```sh +EXAMPLES: + 1. Add a worker reachable at the provided address. + $ vela add worker --worker.address myworker.example.com + 2. Add a worker with the provided hostname and reachable at the address given. + $ vela add worker --worker.hostname MyWorker --worker.address myworker.example.com +``` \ No newline at end of file diff --git a/docs/reference/cli/worker/get.md b/docs/reference/cli/worker/get.md new file mode 100644 index 0000000..29a5fc8 --- /dev/null +++ b/docs/reference/cli/worker/get.md @@ -0,0 +1,75 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list workers. +--- + +## Command + +``` +$ vela get workers +``` + +:::tip +For more information, you can run `vela get workers --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ---------- | ------------------------------------ | ---------------------------------- | +| `output` | format the output for the workers | `VELA_OUTPUT`, `WORKER_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela get workers +``` + +#### Response generated from successful CLI command +```sh +HOSTNAME ACTIVE ROUTES LAST_CHECKED_IN +MyWorker1 true [vela] 1681485812 +MyWorker2 true [vela] 1681485814 +``` + +## Examples + +```sh +EXAMPLES: + 1. Get a list of workers. + $ vela get worker + 2. Get a list of workers with wide view output. + $ vela get worker --output wide + 3. Get a list of workers with yaml output. + $ vela get worker --output yaml + 4. Get a list of workers with json output. + $ vela get worker --output json + 5. Get a list of workers when config or environment variables are set. + $ vela get worker +``` diff --git a/docs/reference/cli/worker/update.md b/docs/reference/cli/worker/update.md new file mode 100644 index 0000000..4871987 --- /dev/null +++ b/docs/reference/cli/worker/update.md @@ -0,0 +1,76 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a worker. +--- + +## Command + +``` +$ vela update worker +``` + +:::tip +For more information, you can run `vela update worker --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| ----------------- | ---------------------------------------- | ----------------------------------------------- | +| `worker.address` | address of the worker | `VELA_WORKER_ADDRESS`, `WORKER_ADDRESS` | +| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | +| `active` | current status of the worker (unused) | `VELA_WORKER_ACTIVE`, `WORKER_ACTIVE` | +| `build-limit` | build limit for the worker (ignored) | `VELA_WORKER_BUILD_LIMIT`, `WORKER_BUILD_LIMIT` | +| `routes` | route assignment for the worker (unused) | `VELA_WORKER_ROUTES`, `WORKER_ROUTES` | +| `output` | format the output for the worker | `VELA_OUTPUT`, `WORKER_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +Vela Platform Admin + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela update worker --worker.hostname MyWorker --worker.address newaddress.example.com +``` + +#### Response + +```sh +{ + ID: 1, + Hostname: MyWorker, + Address: newaddress.example.com, + Routes: [vela], + Active: true, + Status: busy, + LastStatusUpdateAt: 1681486769, + RunningBuildIDs: [123], + LastBuildStartedAt: 1681486769, + LastBuildFinishedAt: 1681486769, + LastCheckedIn: 1681486769, + BuildLimit: 1, +} +``` diff --git a/docs/reference/cli/worker/view.md b/docs/reference/cli/worker/view.md new file mode 100644 index 0000000..8930442 --- /dev/null +++ b/docs/reference/cli/worker/view.md @@ -0,0 +1,74 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a worker. +--- + +## Command + +``` +$ vela view worker +``` + +:::tip +For more information, you can run `vela view worker --help`. +::: + +## Parameters + +The following parameters are used to configure the command: + +| Name | Description | Environment Variables | +| --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- | +| `worker.hostname` | hostname of the worker | `VELA_WORKER_HOSTNAME`, `WORKER_HOSTNAME` | +| `worker.registration.token` | generate a registration token for the worker (requires Vela Platform Admin) | `VELA_WORKER_REGISTRATION_TOKEN`, `WORKER_REGISTRATION_TOKEN` | +| `output` | format the output for the repository | `VELA_OUTPUT`, `WORKER_OUTPUT` | + +:::tip +This command also supports setting the following parameters via a configuration file: + +- `output` + +For more information, please review the [CLI config documentation](/docs/reference/cli/config/). +::: + +## Permissions + +COMING SOON! + +## Sample + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: + +#### Request + +```sh +$ vela view worker --worker.hostname MyWorker +``` + +#### Response + +```sh +id: 1 +hostname: MyWorker +address: myworker.example.com +routes: +- vela +active: true +status: busy +laststatusupdatedat: 1681487969 +runningbuildids: +- 123 +lastbuildstartedat: 1681487969 +lastbuildfinishedat: 1681487969 +lastcheckedin: 1681487969 +buildlimit: 1 + +``` diff --git a/docs/reference/cli/worker/worker.md b/docs/reference/cli/worker/worker.md new file mode 100644 index 0000000..a264609 --- /dev/null +++ b/docs/reference/cli/worker/worker.md @@ -0,0 +1,16 @@ +--- +title: "Worker" +linkTitle: "Worker" +description: > + Learn how to use CLI commands for the worker resource. +--- + +The below commands are available to operate on the `worker` resource. + +:::warning +This section assumes you have already installed and setup the CLI. + +To install the CLI, please review the [installation documentation](/docs/reference/cli/install.md). + +To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +::: diff --git a/docs/reference/environment/environment.md b/docs/reference/environment/environment.md new file mode 100644 index 0000000..1307ac1 --- /dev/null +++ b/docs/reference/environment/environment.md @@ -0,0 +1,13 @@ +--- +title: "Environment" +linkTitle: "Environment" +layout: Environment +description: > + This section contains information on how to use the Vela pipeline environment. +--- + +Vela allows ways to set environment variables within the step, service, or secret container environment. This allows users to pass custom environment configurations to the container. Custom environment configuration can allow you to customize the build environment or simply add metadata for whatever the container image is running. + +:::tip +An example is available within the usage tab called ["Using the Environment"](/docs/usage/environment/) +::: diff --git a/docs/reference/environment/substitution.md b/docs/reference/environment/substitution.md new file mode 100644 index 0000000..280290f --- /dev/null +++ b/docs/reference/environment/substitution.md @@ -0,0 +1,54 @@ +--- +title: "Substitution" +linkTitle: "Substitution" +description: > + Learn how to use substitution on environment variables +--- + +Vela imports a substitution library to provide the ability to expand, or substitute, repository and build metadata to facilitate dynamic pipeline configurations. + +## String Operations + +| Syntax | Example with Output | Description | +| ------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `${VAR^}` | `VAR=example; echo ${VAR^}`► `Example` | Converts the first character of the variable to uppercase | +| `${VAR^^}` | `VAR=example; echo ${VAR^^}`► `EXAMPLE` | Converts all characters of the variable to uppercase | +| `${VAR,}` | `VAR=EXAMPLE; echo ${VAR,}`► `eXAMPLE` | Converts the first character of the variable to lowercase | +| `${VAR,,}` | `VAR=EXAMPLE; echo ${VAR,,}`► `example` | Converts all characters of the variable to lowercase | +| `${VAR:position}` | `VAR=example; echo ${VAR:1}`► `xample` | Extracts a substring from the variable starting at the position | +| `${VAR:position:length}` | `VAR=example; echo ${VAR:2:3}`► `amp` | Extracts a substring from the variable starting at the position with the specified length | +| `${VAR#substring}` | `VAR=exampleexample; echo ${VAR#exa}`► `mpleexample` | Removes the shortest match of substring from the start of the variable | +| `${VAR##substring}` | `VAR=exampleexample; echo ${VAR##*exa}`► `mple` | Removes the longest match of substring from the start of the variable | +| `${VAR%substring}` | `VAR=exampleexample; echo ${VAR%mple}`► `exampleexa` | Removes the shortest match of substring from the end of the variable | +| `${VAR%%substring}` | `VAR=exampleexample; echo ${VAR%%mple*}`► `exa` | Removes the longest match of substring from the end of the variable | +| `${VAR/substring/replacement}` | `VAR=exampleexample; echo ${VAR/exam/ap}`► `appleexample` | Replaces the first match of substring with replacement in the variable | +| `${VAR//substring/replacement}` | `VAR=exampleexample; echo ${VAR//exam/ap}`► `appleapple` | Replaces all matches of substring with replacement in the variable | +| `${VAR/#substring/replacement}` | `VAR=example; echo ${VAR/#exam/ap}`► `apple` | If the variable starts with substring, replace it with replacement | +| `${VAR/%substring/replacement}` | `VAR=example; echo ${VAR/%mple/ctly}`► `exactly` | If the variable ends with substring, replace it with replacement | +| `${#VAR}` | `VAR=example; echo ${#VAR}`► `7` | Returns the length of the variable | +| `${VAR=default}` | `unset VAR; echo ${VAR=default}`► `default` | If the variable is unset or null, it will be set to `default` | +| `${VAR:=default}` | `unset VAR; echo ${VAR:=default}`► `default` | If the variable is unset or null, it will be set to `default` and the assignment is exported | +| `${VAR:-default}` | `unset VAR; echo ${VAR:-default}`► `default` | If the variable is unset or null, it will be replaced with `default` without changing the value of `VAR` | + +:::tip +If you want to play with the examples above in a terminal, make sure you are in a `bash` shell. +::: + +### Escaping + +:::tip +var expressions are evaluated before the yaml is parsed. If you do not want the system to evaluate an expression it must be escaped. +::: + +This can come in handy particularly when dealing with [runtime build environment variables](/docs/reference/environment/variables/#using-substitution-for-platform-variables). + +```diff +version: "1" +steps: + - name: echo + commands: + # This expression does not escape the evaluation ++ - echo ${VELA_BUILD_COMMIT} + # This expression does escape the evaluation by adding the double '$$' ++ - echo $${VELA_BUILD_COMMIT} +``` diff --git a/docs/reference/environment/variables.md b/docs/reference/environment/variables.md new file mode 100644 index 0000000..a183ab7 --- /dev/null +++ b/docs/reference/environment/variables.md @@ -0,0 +1,203 @@ +--- +title: "Variables" +linkTitle: "Variables" +description: > + Learn what environment variables are injected into containers +--- + +## Container Defaults + +The following environment variables are injected into every step, service, or secret container. + +#### Build Environment Variables + +| Key | Value | Explanation | +| ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | +| `VELA_BUILD_APPROVED_AT` | `1556720958` | unix timestamp representing when build was approved | +| `VELA_BUILD_APPROVED_BY` | `RepoAdmin` | user who approved the build | +| `VELA_BUILD_AUTHOR` | `octocat` | author from the source commit | +| `VELA_BUILD_AUTHOR_EMAIL` | `octocat@github.com` | author email from the source commit, available only in `push` events | +| `VELA_BUILD_BASE_REF` | `refs/heads/dev` | reference from the base commit | +| `VELA_BUILD_BRANCH` | `main` | branch from the source commit | +| `VELA_BUILD_CHANNEL` | `vela` | queue channel the build was published to | +| `VELA_BUILD_CLONE` | `https://github.com/octocat/hello-world.git` | clone url for the repository the build was triggered from | +| `VELA_BUILD_COMMIT` | `7fd1a60b01f91b314f59955a4e4d4e80d8edf11d` | commit sha from the source commit | +| `VELA_BUILD_CREATED` | `1556720958` | unix timestamp representing build creation time | +| `VELA_BUILD_DISTRIBUTION` | `linux` | distribution where the build was executed | +| `VELA_BUILD_ENQUEUED` | `1556720958` | unix timestamp representing build enqueued time | +| `VELA_BUILD_EVENT` | `push` | webhook event that triggered the build | +| `VELA_BUILD_EVENT_ACTION` | `created` | webhook event action that triggered the build | +| `VELA_BUILD_HOST` | `vela-worker-1` | fully qualified domain name of the worker the build was executed on | +| `VELA_BUILD_LINK` | `https://vela.example.com/octocat/hello-world/1` | link to the build in the UI | +| `VELA_BUILD_MESSAGE` | `Merge pull request #6 from octocat/patch-1` | message from the source commit | +| `VELA_BUILD_NUMBER` | `1` | build number | +| `VELA_BUILD_PARENT` | `1` | previous build number | +| `VELA_BUILD_REF` | `refs/heads/main` | reference from the source commit | +| `VELA_BUILD_RUNTIME` | `docker` | runtime where the build was executed | +| `VELA_BUILD_SENDER` | `NealColeman` | user who triggered the build | +| `VELA_BUILD_STARTED` | `1556730001` | unix timestamp representing build start time | +| `VELA_BUILD_SOURCE` | `https://github.com/octocat/hello-world/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d` | full url for the source commit the build was triggered from | +| `VELA_BUILD_STATUS` | `success` | status of the build | +| `VELA_BUILD_TITLE` | `push received from https://github.com/octocat/hello-world` | title for the build | +| `VELA_BUILD_WORKSPACE` | `/vela/src/github.com/octocat/hello-world` | working directory the build is executed in | + +##### `comment` event only + +:::tip +The following table includes variables only available during the **comment** event. +::: + +| Key | Value | Explanation | +| ------------------------- | ----- | ---------------------------------------------------------- | +| `VELA_BUILD_PULL_REQUEST` | `1` | pull request number is populated from the source reference | +| `VELA_PULL_REQUEST` | `1` | pull request number is populated from the source reference | +| `VELA_PULL_REQUEST_SOURCE` | `dev` | pull request branch from the source reference | +| `VELA_PULL_REQUEST_TARGET` | `main` | pull request branch for the target reference | + +##### `deployment` event only + +:::tip +The following table includes variables only available during the **deployment** event. + +All custom parameters are passed to the deployment available with a `DEPLOYMENT_PARAMETER_` prefix of the key. +::: + +| Key | Value | Explanation | +| ------------------------ | ----------- | --------------------------------------------- | +| `VELA_BUILD_TARGET` | `production` | name of target environment for the deployment | +| `VELA_DEPLOYMENT` | `production` | name of target environment for the deployment | +| `VELA_DEPLOYMENT_NUMBER` | `12345` | ID of deployment from source | + +##### `pull_request` event only + +:::tip +The following table includes variables only available during the **pull_request** event. +::: + +| Key | Value | Explanation | +| -------------------------- | ------ | ---------------------------------------------------------- | +| `VELA_BUILD_PULL_REQUEST` | `1` | pull request number is populated from the source reference | +| `VELA_PULL_REQUEST` | `1` | pull request number is populated from the source reference | +| `VELA_PULL_REQUEST_SOURCE` | `dev` | pull request branch from the source reference | +| `VELA_PULL_REQUEST_TARGET` | `main` | pull request branch for the target reference | + +##### `tag` event only + +:::tip +The following table includes variables only available during the **tag** event. +::: + +| Key | Value | Explanation | +| ---------------- | -------- | ------------------------------------------ | +| `VELA_BUILD_TAG` | `v1.0.0` | tag is populated from the source reference | + +##### OpenID Connect only + +:::tip +The following table includes variables only available when the step `id_request` field has a value. +::: + +| Key | Value | Explanation | +| ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------- | +| `VELA_ID_TOKEN_REQUEST_URL` | `/api/v1/repos///builds//id_token` | URL to request an ID token | +| `VELA_ID_TOKEN_REQUEST_TOKEN` | `ey123abc...` | bearer token for requesting ID token | + + +#### Vela Environment Variables + +| Key | Value | Explanation | +| ---------------------- |---------------------------------------------------|---------------------------------------------------------------------| +| `VELA` | `true` | environment is Vela | +| `VELA_ADDR` | `vela.example.com` | fully qualified domain name of the Vela server | +| `VELA_CHANNEL` | `vela` | queue channel the build was published to | +| `VELA_DATABASE` | `postgres` | database Vela is connected to | +| `VELA_HOST` | `vela-worker-1` | fully qualified domain name of the worker the build was executed on | +| `VELA_QUEUE` | `redis` | queue build was published to | +| `VELA_RUNTIME` | `docker` | runtime environment build was executed in | +| `VELA_SOURCE` | `github` | queue channel the build was published to | +| `VELA_VERSION` | `v0.1.0` | Vela version | +| `VELA_WORKSPACE` | `/vela/src/github.com/github/octocat/hello-world` | working directory the build is executed in | +| `CI` | `true` | Indicates this is a CI environment | +| `VELA_OUTPUTS` | `/vela/outputs/.env` | file path for dynamic environment | +| `VELA_MASKED_OUTPUTS` | `/vela/outputs/masked.env` | file path for dynamic environment for sensitive values | + +#### Repository Environment Variables + +| Key | Value | Explanation | +| ------------------------- | -------------------------------------------- | --------------------------------------------- | +| `VELA_REPO_ACTIVE` | `true` | active setting for the repository | +| `VELA_REPO_ALLOW_COMMENT` | `false` | comment enabled setting for the repository | +| `VELA_REPO_ALLOW_DEPLOY` | `false` | deploy enabled setting for the repository | +| `VELA_REPO_ALLOW_PULL` | `true` | pull enabled setting for the repository | +| `VELA_REPO_ALLOW_PUSH` | `true` | push enabled setting for the repository | +| `VELA_REPO_ALLOW_TAG` | `false` | tag enabled setting for the repository | +| `VELA_REPO_BRANCH` | `main` | default branch of the repository | +| `VELA_REPO_BUILD_LIMIT` | `10` | limit of concurrent builds for the repository | +| `VELA_REPO_CLONE` | `https://github.com/octocat/hello-world.git` | clone url of the repository | +| `VELA_REPO_FULL_NAME` | `octocat/hello-world` | full name of the repository | +| `VELA_REPO_LINK` | `https://github.com/octocat/hello-world` | direct url of the repository | +| `VELA_REPO_NAME` | `hello-world` | name of the repository | +| `VELA_REPO_ORG` | `octocat` | org of the repository | +| `VELA_REPO_PRIVATE` | `false` | privacy setting for the repository | +| `VELA_REPO_TIMEOUT` | `30` | timeout setting for the repository | +| `VELA_REPO_TOPICS` | `cloud,security` | comma-separated list of repository topics | +| `VELA_REPO_TRUSTED` | `false` | trusted setting for the repository | +| `VELA_REPO_VISIBILITY` | `public` | visibility setting for the repository | + +#### User Environment Variables + +| Key | Value | Explanation | +| ---------------------- | --------------------------- | ---------------------------------- | +| `VELA_USER_ACTIVE` | `true` | active setting for the user | +| `VELA_USER_NAME` | `Octocat` | user handle setting for the user | + +## Step Only Defaults + +The following environment variables are **only** injected into every step container. + +| Key | Value | Explanation | +| ------------------------ | ------------------------ | ------------------------------------------------------------------- | +| `VELA_STEP_CREATED` | `1556720958` | unix timestamp representing step creation time | +| `VELA_STEP_DISTRIBUTION` | `linux` | distribution where the step was executed | +| `VELA_STEP_EXIT_CODE` | `0` | exit code of the step when container starts | +| `VELA_STEP_HOST` | `vela-worker-1` | fully qualified domain name of the worker the step was executed on | +| `VELA_STEP_IMAGE` | `target/vela-git:latest` | name of the image executed | +| `VELA_STEP_NAME` | `clone` | name of the step | +| `VELA_STEP_NUMBER` | `1` | number of the step executed within the pipeline | +| `VELA_STEP_REPORT_AS` | `cypress tests` | context to which to publish for the commit that reflects step status | +| `VELA_STEP_RUNTIME` | `docker` | runtime where the step was executed | +| `VELA_STEP_STAGE` | `clone` | name of the stage the step belongs to within the pipeline | +| `VELA_STEP_STARTED` | `1556730001` | unix timestamp representing step start time | +| `VELA_STEP_STATUS` | `success` | status of the step | + +## Service Only Defaults + +The following environment variables are **only** injected into every step container. + +| Key | Value | Explanation | +| --------------------------- | ------------------------ | --------------------------------------------------------------------- | +| `VELA_SERVICE_CREATED` | `1556720958` | unix timestamp representing service creation time | +| `VELA_SERVICE_DISTRIBUTION` | `linux` | distribution where the service was executed | +| `VELA_SERVICE_EXIT_CODE` | `0` | exit code of the service when container starts | +| `VELA_SERVICE_HOST` | `vela-worker-1` | fully qualified domain name of the worker the service was executed on | +| `VELA_SERVICE_IMAGE` | `target/vela-git:latest` | name of the image executed | +| `VELA_SERVICE_NAME` | `clone` | name of the service | +| `VELA_SERVICE_NUMBER` | `1` | number of the service executed within the pipeline | +| `VELA_SERVICE_RUNTIME` | `docker` | runtime where the service was executed | +| `VELA_SERVICE_STARTED` | `1556730001` | unix timestamp representing service start time | +| `VELA_SERVICE_STATUS` | `success` | status of the service | + +## Using Substitution For Platform Variables + +There are a few default environment variables that need to be [escaped](/docs/reference/environment/substitution/#escaping) when attempting to substitute, as they are not available or not accurate at compile time. + +| Key | Compile Time | Build Time Example | +| -------------------------- | ------------- | ------------------- | +| `VELA_BUILD_STARTED` | `0` | `1556730001` | +| `VELA_BUILD_STATUS` | `pending` | `running` | +| `VELA_BUILD_APPROVED_AT` | `0` | `1556730001` | +| `VELA_BUILD_APPROVED_BY` | `''` | `Octocat` | +| `VELA_BUILD_ENQUEUED` | `0` | `1556730001` | +| `VELA_BUILD_RUNTIME` | `''` | `docker` | +| `VELA_BUILD_DISTRIBUTION` | `''` | `linux` | +| `VELA_BUILD_HOST` | `''` | `vela-worker-42` | diff --git a/docs/reference/installation/_category_.json b/docs/reference/installation/_category_.json new file mode 100644 index 0000000..1daf919 --- /dev/null +++ b/docs/reference/installation/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Installation", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/docs/reference/installation/server/authentication_workflow.puml b/docs/reference/installation/server/authentication_workflow.puml new file mode 100644 index 0000000..48cfbdf --- /dev/null +++ b/docs/reference/installation/server/authentication_workflow.puml @@ -0,0 +1,23 @@ +@startuml + +title Vela Authentication Workflow + +skinparam actorStyle awesome +actor "Developer" as Developer + +participant "UI" as UI +participant "Server" as Server +participant "GitHub" as Github + +Developer -> UI : Connect to vela.example.com +UI -> Server : Redirect to vela-server.example.com/authenticate +Server -> Github : GET github.com/login/oauth/authorize for authorization code +Github -> Server : Return temporary code +Server -> Github : POST github.com/login/oauth/access_token for OAuth token +Github -> Server : Return OAuth token +Server -> Server : Store OAuth token in the database +Server -> Server : Generate short-lived token for user (automatically refreshes) +Server -> Developer : Redirect to vela.example.com with short-lived token +Developer -> UI : Successful completion of authentication workflow + +@enduml \ No newline at end of file diff --git a/docs/reference/installation/server/compiler.md b/docs/reference/installation/server/compiler.md new file mode 100644 index 0000000..6b8cfc9 --- /dev/null +++ b/docs/reference/installation/server/compiler.md @@ -0,0 +1,129 @@ +--- +title: "Compiler" +linkTitle: "Compiler" +weight: 2 +description: > + This section contains information on the compiler component for the Vela server. +--- + +:::note +The compiler is embedded directly in the server and can only be accessed through the server. +::: + +This component is responsible for transforming a [pipeline](/docs/tour/) into an executable representation for the [worker](/docs/installation/worker/). + +During the transformation, it will retrieve [templates](/docs/tour/templates/) from one or more registries depending on the pipeline configuration. + +By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates, but you can configure additional registries as well. + +However, to fetch templates from a private organization or repository on GitHub, you need to provide a token to the compiler. + +Additionally, the compiler can send pipelines to an external endpoint, to be modified, based off custom configuration. + +This modification endpoint can be used to perform any number of customizations to all workloads created by the system. + +Some examples of what the modification endpoint can do include, but are not limited to: + +* injecting or updating the configuration for [secrets](/docs/tour/secrets/) in the pipeline +* injecting or updating the configuration for [services](/docs/tour/services/) in the pipeline +* injecting or updating the configuration for [stages](/docs/tour/stages/) in the pipeline +* injecting or updating the configuration for [steps](/docs/tour/steps/) in the pipeline + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| ------------------------------ | ---------------------------------------------------------------------------- | -------- | --------------------- | --------------------------------------------------------------------- | +| `clone-image` | default clone image to use for Vela injected clone step | `true` | `target/vela-git` (1) | `VELA_CLONE_IMAGE` | +| `github-driver` | enables using Github or GitHub Enterprise Server as a registry for templates | `false` | `false` | `COMPILER_GITHUB`\`VELA_COMPILER_GITHUB` | +| `github-url` | fully qualified url to GitHub or GitHub Enterprise Server for templates | `false` | `N/A` | `COMPILER_GITHUB_URL`\`VELA_COMPILER_GITHUB_URL` | +| `github-token` | token used for authentication when fetching registry templates | `false` | `N/A` | `COMPILER_GITHUB_TOKEN`\`VELA_COMPILER_GITHUB_TOKEN` | +| `modification-addr` | fully qualified url to endpoint for modifying pipelines | `false` | `N/A` | `MODIFICATION_ADDR`\`VELA_MODIFICATION_ADDR` | +| `modification-retries` | number of times to resend failed requests to the modification endpoint | `false` | `5` | `MODIFICATION_RETRIES`\`VELA_MODIFICATION_RETRIES` | +| `modification-secret` | authenticates communication between compiler and the modification endpoint | `false` | `N/A` | `MODIFICATION_SECRET`\`VELA_MODIFICATION_SECRET` | +| `modification-timeout` | timeout for requests sent to the modification endpoint | `false` | `8s` | `MODIFICATION_TIMEOUT`\`VELA_MODIFICATION_TIMEOUT` | +| `max-template-depth` | max depth for calling nested templates during compilation | `true` | `3` | `MAX_TEMPLATE_DEPTH`\`VELA_MAX_TEMPLATE_DEPTH` | +| `compiler-starlark-exec-limit` | execution step limit for compiling starlark pipelines | `true` | `7500` | `COMPILER_STARLARK_EXEC_LIMIT`\`VELA_COMPILER_STARLARK_EXEC_LIMIT` | + +_(1) this will be the latest available, tagged release of `target/vela-git` at the time the server component is released_ + +:::note +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| -------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `github` | uses GitHub or GitHug Enterprise Server as a template registry | https://docs.github.com/en/enterprise-server/admin/overview/system-overview | + +### GitHub + +From the [GitHub official website](https://github.com/about/): + +> GitHub is where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world. + +The below configuration displays an example of starting the Vela server that will use a GitHub Server as a template registry: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ ++ --env=VELA_COMPILER_GITHUB=true \ ++ --env=VELA_COMPILER_TOKEN= \ ++ --env=VELA_COMPILER_URL=https://github.com \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_QUEUE_ADDR=redis://@:/ \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` + +:::note +This GitHub configuration is enabled by default and is not necessary to provide in order for Vela to operate. + +However, this configuration will enable you to fetch templates from a private organization or repository on GitHub. +::: + +### GitHub Enterprise Server + +From the [GitHub Enterprise official website](https://docs.github.com/en/enterprise-server/admin/overview/system-overview): + +> GitHub Enterprise Server is your organization's private copy of GitHub contained within a virtual appliance, hosted on premises or in the cloud, that you configure and control. + +The below configuration displays an example of starting the Vela server that will use a GitHub Enterprise Server as a template registry: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ ++ --env=VELA_COMPILER_GITHUB=true \ ++ --env=VELA_COMPILER_TOKEN= \ ++ --env=VELA_COMPILER_URL=https://git.example.com \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_QUEUE_ADDR=redis://@:/ \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` diff --git a/docs/reference/installation/server/database.md b/docs/reference/installation/server/database.md new file mode 100644 index 0000000..d9efdfe --- /dev/null +++ b/docs/reference/installation/server/database.md @@ -0,0 +1,113 @@ +--- +title: "Database" +linkTitle: "Database" +weight: 3 +description: > + This section contains information on the database component for the Vela server. +--- + +This component is responsible for integrating with a database system based off the configuration provided. + +The database system is used by Vela for storing application [data at rest](https://en.wikipedia.org/wiki/Data_at_rest). + +This data is an organized collection of information necessary for the platform to operate. + +:::note +Any sensitive data stored in the database will be encrypted using the [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). +::: + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| ----------------------------- | ---------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------- | +| `database.addr` | full connection string to the database | `true` | `sqlite3` | `DATABASE_ADDR`\`VELA_DATABASE_ADDR` | +| `database.driver` | type of client to control and operate the database | `true` | `vela.sqlite` | `DATABASE_DRIVER`\`VELA_DATABASE_DRIVER` | +| `database.compression.level` | level of compression for logs stored in the database | `true` | `3` | `DATABASE_COMPRESSION_LEVEL`\`VELA_DATABASE_COMPRESSION_LEVEL` | +| `database.connection.idle` | maximum number of idle connections to the database | `true` | `2` | `DATABASE_CONNECTION_IDLE`\`VELA_DATABASE_CONNECTION_IDLE` | +| `database.connection.life` | duration of time a connection is reusable | `true` | `30m` | `DATABASE_CONNECTION_LIFE`\`VELA_DATABASE_CONNECTION_LIFE` | +| `database.connection.open` | maximum number of open connections to the database | `true` | `0` | `DATABASE_CONNECTION_OPEN`\`VELA_DATABASE_CONNECTION_OPEN` | +| `database.encryption.key` | AES-256 key for encrypting/decrypting values in the database | `true` | `N/A` | `DATABASE_ENCRYPTION_KEY`\`VELA_DATABASE_ENCRYPTION_KEY` | +| `database.skip_creation` | skips the creation of tables and indexes in the database | `false` | `false` | `DATABASE_SKIP_CREATION`\`VELA_DATABASE_SKIP_CREATION` | +| `database.log.level` | log level for database | `false` | `warn` | `DATABASE_LOG_LEVEL` \ `VELA_DATABASE_LOG_LEVEL` | +| `database.log.show_sql` | show sql query in logs | `false` | `false` | `DATABASE_LOG_SHOW_SQL` \ `VELA_DATABASE_LOG_SHOW_SQL` | +| `database.log.skip_notfound` | skip logging not found errors | `false` | `true` | `DATABASE_LOG_SKIP_NOTFOUND` \ `VELA_DATABASE_LOG_SKIP_NOTFOUND` | +| `database.log.slow_threshold` | queries higher than this value are considered slow and logged | `false` | `200ms` | `DATABASE_LOG_SLOW_THRESHOLD` \ `VELA_DATABASE_LOG_SLOW_THRESHOLD` | + +:::note +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ---------- | --------------------------------------------------- | --------------------------- | +| `postgres` | uses a PostgreSQL database for storing data at rest | https://www.postgresql.org/ | +| `sqlite3` | uses a SQLite database for storing data at rest | https://www.sqlite.org/ | + +### Postgres + +From the [PostgreSQL official website](https://www.postgresql.org/): + +> PostgreSQL is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. + +The below configuration displays an example of starting the Vela server that will connect to a Postgres database: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ ++ --env=VELA_DATABASE_DRIVER=postgres \ ++ --env=VELA_DATABASE_ADDR=postgres://:@:/ \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_QUEUE_ADDR=redis://@:/ \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` + +### Sqlite3 + +From the [Sqlite official website](https://www.sqlite.org/): + +> SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. SQLite is the most used database engine in the world. SQLite is built into all mobile phones and most computers and comes bundled inside countless other applications that people use every day. + +The below configuration displays an example of starting the Vela server that will connect to a Sqlite database: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ ++ --env=VELA_DATABASE_DRIVER=sqlite3 \ ++ --env=VELA_DATABASE_ADDR=vela.sqlite \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_QUEUE_ADDR=redis://@:/ \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` + +:::note +This Sqlite configuration is enabled by default and is not necessary to provide in order for Vela to operate. +::: \ No newline at end of file diff --git a/docs/reference/installation/server/queue.md b/docs/reference/installation/server/queue.md new file mode 100644 index 0000000..57918e0 --- /dev/null +++ b/docs/reference/installation/server/queue.md @@ -0,0 +1,69 @@ +--- +title: "Queue" +linkTitle: "Queue" +weight: 4 +description: > + This section contains information on the queue component for the Vela server. +--- + +This component is responsible for integrating with a queue system based off the configuration provided. + +The queue system is used by the Vela server for pushing workloads that will be run by a [worker](/docs/installation/worker/). + +Workloads published to the queue are managed with a [first in, first out (FIFO)](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) strategy. + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| ------------------- | ------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------- | +| `queue.addr` | full connection string to the queue | `true` | `N/A` | `QUEUE_ADDR`\`VELA_QUEUE_ADDR` | +| `queue.cluster` | configures the client for a queue cluster | `false` | `false` | `QUEUE_CLUSTER`\`VELA_QUEUE_CLUSTER` | +| `queue.driver` | type of client to control and operate queue | `true` | `N/A` | `QUEUE_DRIVER`\`VELA_QUEUE_DRIVER` | +| `queue.pop.timeout` | timeout for requests that pop items off the queue | `true` | `60s` | `QUEUE_POP_TIMEOUT`\`VELA_QUEUE_POP_TIMEOUT` | +| `queue.routes` | unique channels or topics for pushing workloads | `true` | `[ vela ]` | `QUEUE_ROUTES`\`VELA_QUEUE_ROUTES` | +| `queue.private-key` | private key for signing items prior to push | `false` | `N/A` | `QUEUE_PRIVATE_KEY`\`VELA_QUEUE_PRIVATE_KEY` | +| `queue.public-key` | public key for opening items after popping them off the queue | `false` | `N/A` | `QUEUE_PUBLIC_KEY`\`VELA_QUEUE_PUBLIC_KEY` | + +:::note +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ------- | ----------------------------------------- | ----------------- | +| `redis` | uses a Redis queue for managing workloads | https://redis.io/ | + +### Redis + +From the [Redis official website](https://redis.io/): + +> Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster. + +The below configuration displays an example of starting the Vela server that will connect to a Redis queue: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ ++ --env=VELA_QUEUE_DRIVER=redis \ ++ --env=VELA_QUEUE_ADDR=redis://@:/ \ ++ --env=VELA_QUEUE_PRIVATE_KEY= \ ++ --env=VELA_QUEUE_PUBLIC_KEY= \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` \ No newline at end of file diff --git a/docs/reference/installation/server/scm.md b/docs/reference/installation/server/scm.md new file mode 100644 index 0000000..23b392d --- /dev/null +++ b/docs/reference/installation/server/scm.md @@ -0,0 +1,75 @@ +--- +title: "SCM" +linkTitle: "SCM" +weight: 6 +description: > + This section contains information on the scm component for the Vela server. +--- + +This component is responsible for integrating with a source control management (SCM) system based off the configuration provided. + +The SCM system is used by Vela for both authentication and authorization of interactions performed within the application. + +![Authentication Workflow](/img/reference/authentication_workflow.png) + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| ------------------ | --------------------------------------------------------------- | -------- | -------------------------------------------------------- | --------------------------------------------- | +| `scm.addr` | fully qualified url for the SCM | `true` | `https://github.com` | `SCM_ADDR`\`VELA_SCM_ADDR` | +| `scm.client` | client ID from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_CLIENT`\`VELA_SCM_CLIENT` | +| `scm.context` | message to set in commit status on the SCM | `true` | `continuous-integration/vela` | `SCM_CONTEXT`\`VELA_SCM_CONTEXT` | +| `scm.driver` | type of client to control and operate SCM | `true` | `github` | `SCM_DRIVER`\`VELA_SCM_DRIVER` | +| `scm.scopes` | permission scopes to apply for the OAuth credentials on the SCM | `true` | `[ repo, repo:status, user:email, read:user, read:org ]` | `SCM_SCOPES`\`VELA_SCM_SCOPES` | +| `scm.secret` | client secret from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_SECRET`\`VELA_SCM_SECRET` | +| `scm.webhook.addr` | url for webhooks on the SCM to send requests to | `false` | the address of the Vela server (`$VELA_ADDR`) | `SCM_WEBHOOK_ADDR`\`VELA_SCM_WEBHOOK_ADDR` | + +:::note +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| -------- | ----------------------------------------------------- | ------------------------- | +| `github` | uses a GitHub or GitHug Enterprise Server for the SCM | https://github.com/about/ | + +### GitHub + +From the [GitHub official website](https://github.com/about/): + +> GitHub is where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world. + +The below configuration displays an example of creating a [GitHub OAuth application](https://docs.github.com/developers/apps/building-oauth-apps/creating-an-oauth-app): + +![OAuth Application](/img/reference/github_oauth.png) + +:::warning +The `Homepage URL` should match [the `VELA_ADDR` environment variable](/docs/installation/server/reference/#vela_addr) provided to the server for clusters without a UI. + +Otherwise, the `Homepage URL` should match [the `VELA_WEBUI_ADDR` environment variable](/docs/installation/server/reference/#vela_webui_addr) provided to the server. + +The `Authorization callback URL` should contain [the `VELA_ADDR` environment variable](/docs/installation/server/reference/#vela_addr) with a `/authenticate` suffix. +::: + +### GitHub Enterprise Server + +From the [GitHub Enterprise official website](https://docs.github.com/en/enterprise-server/admin/overview/system-overview): + +> GitHub Enterprise Server is your organization's private copy of GitHub contained within a virtual appliance, hosted on premises or in the cloud, that you configure and control. + +The below configuration displays an example of creating a [GitHub Enterprise Server OAuth application](https://docs.github.com/enterprise-server@3.3/developers/apps/building-oauth-apps/creating-an-oauth-app): + +![OAuth Application](/img/reference/github_enterprise_oauth.png) + +:::warning +The `Homepage URL` should match [the `VELA_ADDR` environment variable](/docs/installation/server/reference/#vela_addr) provided to the server for clusters without a UI. + +Otherwise, the `Homepage URL` should match [the `VELA_WEBUI_ADDR` environment variable](/docs/installation/server/reference/#vela_webui_addr) provided to the server. + +The `Authorization callback URL` should contain [the `VELA_ADDR` environment variable](/docs/installation/server/reference/#vela_addr) with a `/authenticate` suffix. +::: \ No newline at end of file diff --git a/docs/reference/installation/server/secret.md b/docs/reference/installation/server/secret.md new file mode 100644 index 0000000..486298c --- /dev/null +++ b/docs/reference/installation/server/secret.md @@ -0,0 +1,75 @@ +--- +title: "Secret" +linkTitle: "Secret" +weight: 5 +description: > + This section contains information on the secret component for the Vela server. +--- + +This component is optional and is responsible for integrating with an external secret system based off the configuration provided. + +The secret system is used by Vela for storing sensitive application [data at rest](https://en.wikipedia.org/wiki/Data_at_rest). + +By default, Vela will use [the database](/docs/installation/server/database/) to store the sensitive data if no other secret system is configured. + +:::note +Any sensitive data stored in the database will be encrypted using the [Advanced Encryption Standard (AES)](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). +::: + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| -------------------------- | ---------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------- | +| `secret.vault.addr` | fully qualified url to the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_ADDR`\`VELA_SECRET_VAULT_ADDR` | +| `secret.vault.auth-method` | authentication method used to obtain token from the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_AUTH_METHOD`\`VELA_SECRET_VAULT_AUTH_METHOD` | +| `secret.vault.aws-role` | HashiCorp Vault role used to connect to the auth/aws/login endpoint | `false` | `N/A` | `SECRET_VAULT_AWS_ROLE`\`VELA_SECRET_VAULT_AWS_ROLE` | +| `secret.vault.driver` | enables HashiCorp Vault as a secret engine | `true` | `false` | `SECRET_VAULT`\`VELA_SECRET_VAULT` | +| `secret.vault.prefix` | prefix for k/v secrets in the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_PREFIX`\`VELA_SECRET_VAULT_PREFIX` | +| `secret.vault.renewal` | frequency to renew the token for the HashiCorp Vault instance | `false` | `30m` | `SECRET_VAULT_RENEWAL`\`VELA_SECRET_VAULT_RENEWAL` | +| `secret.vault.token` | token required to access the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_TOKEN`\`VELA_SECRET_VAULT_TOKEN` | +| `secret.vault.version` | version for the k/v backend for the HashiCorp Vault instance | `true` | `2` | `SECRET_VAULT_VERSION`\`VELA_SECRET_VAULT_VERSION` | + +:::note +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ------- | ------------------------------------------------------------------ | ---------------------------- | +| `vault` | uses a HashiCorp Vault instance for storing sensitive data at rest | https://www.vaultproject.io/ | + +### HashiCorp Vault + +From the [HashiCorp Vault official website](https://www.vaultproject.io/): + +> HashiCorp Vault enables you to secure, store and tightly control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API. + +The below configuration displays an example of starting the Vela server that will connect to a HashiCorp Vault instance: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ + --env=VELA_DATABASE_ENCRYPTION_KEY= \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_QUEUE_ADDR=redis://@:/ \ + --env=VELA_PORT=443 \ + --env=VELA_SECRET= \ + --env=VELA_SERVER_PRIVATE_KEY= \ ++ --env=VELA_SECRET_VAULT=true \ ++ --env=VELA_SECRET_VAULT_ADDR=https://vault.example.com \ ++ --env=VELA_SECRET_VAULT_TOKEN= + --env=VELA_SCM_CLIENT= \ + --env=VELA_SCM_SECRET= \ + --env=VELA_WEBUI_ADDR=https://vela.example.com \ + --name=server \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + target/vela-server:latest +``` \ No newline at end of file diff --git a/docs/reference/installation/server/server.md b/docs/reference/installation/server/server.md new file mode 100644 index 0000000..ad90808 --- /dev/null +++ b/docs/reference/installation/server/server.md @@ -0,0 +1,907 @@ +--- +no_list: true +title: "Reference" +linkTitle: "Reference" +weight: 4 +description: > + This section contains a reference of configuration options for the Vela server service. +--- + +## Components + +The server is made up of several components, responsible for specific tasks, necessary for the service to operate: + +| Name | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------------- | +| `settings` | keeps track of updated runtime properties for the [server](/docs/installation/server/) | +| `compiler` | transforms a [pipeline](/docs/tour/) into an executable workload for the [worker](/docs/installation/worker/) | +| `database` | integrates with a database provider for storing application data at rest | +| `queue` | integrates with a queue provider for pushing workloads that will be run by a [worker](/docs/installation/worker/) | +| `secret` | integrates with a secret provider for storing sensitive application data at rest | +| `source` | integrates with a source control management (SCM) provider for authentication and authorization | +| `tracing` | implements OpenTelemetry tracing instrumentation for the [server](/docs/installation/server/) | + +## Required + +This section contains a list of all variables that must be provided to the server. + +Some properties can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_ADDR + +This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/) address. + +The variable should be provided as a `string`. + +### VELA_DATABASE_ENCRYPTION_KEY + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the AES key for encrypting/decrypting values for data stored in the database. + +The variable should be provided as an `string`. + +### VELA_QUEUE_ADDR + +This configuration variable is used by the [queue component](/docs/installation/server/reference/queue/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a fully qualified URL to the queue instance for pushing workloads that will be run by a [worker](/docs/installation/worker/). + +The variable should be provided as a `string`. + +### VELA_QUEUE_DRIVER + +This configuration variable is used by the [queue component](/docs/installation/server/reference/queue/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the driver to use for the queue functionality for the server. + +The variable should be provided as a `string`. + +:::note +This variable should match [the `VELA_QUEUE_DRIVER` variable](/docs/installation/worker/reference/#vela_queue_driver) provided to the worker. + +The possible options to provide for this variable are: + +* `redis` +::: + +### VELA_SCM_CLIENT + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets the client ID from the OAuth application created on the SCM system. + +The variable should be provided as a `string`. + +### VELA_SCM_SECRET + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets the client secret from the OAuth application created on the SCM system. + +The variable should be provided as a `string`. + +### VELA_SERVER_PRIVATE_KEY + +This variable sets the private key that will be used to sign all JWT tokens within Vela. Please be sure to follow [guidelines](https://www.rfc-editor.org/rfc/rfc2104#section-3) related to generating a private key. + +The variable should be provided as a `string`. + +## Optional + +This section contains a list of all variables that can be provided to the server. + +Some properties can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_CLONE_IMAGE + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server. + +The clone image sets the clone image to use for the Vela injected clone step in a pipeline. + +By default, Vela will use the latest available release of the clone image at the time of a server release. + +This variable should be provided as a `string`. + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_COMPILER_GITHUB + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable enables using GitHub or GitHub Enterprise Server as a registry for fetching pipeline [templates](/docs/tour/templates/) from. + +By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. + +However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +### VELA_COMPILER_GITHUB_TOKEN + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for fetching pipeline [templates](/docs/tour/templates/) from GitHub or GitHub Enterprise Server. + +By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. + +However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. + +The variable can be provided as a `string`. + +### VELA_COMPILER_GITHUB_URL + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a fully qualified URL to GitHub or GitHub Enterprise Server used for fetching pipeline [templates](/docs/tour/templates/) from. + +By default, Vela will use [GitHub](https://github.com/) as a registry for fetching templates. + +However, to fetch templates from a private organization or repository on GitHub, you need to provide this configuration. + +The variable can be provided as a `string`. + +### VELA_DATABASE_ADDR + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a fully qualified URL to the database instance for storing data at rest. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `vela.sqlite`. +::: + +### VELA_DATABASE_COMPRESSION_LEVEL + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable sets the level of compression for workload logs, uploaded by the Vela [worker](/docs/installation/worker/), which are stored in the database. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `3`. + +The possible options to provide for this variable are: + +* `-1` +* `0` - produces no compression for the log data +* `1` - produces compression for the log data the fastest and with the largest size of data +* `2` +* `3` +* `4` +* `5` - produces compression for the log data with an even balance of speed and size of data +* `6` +* `7` +* `8` +* `9` - produces compression for the log data the slowest and with the smallest size of data +::: + +### VELA_DATABASE_CONNECTION_IDLE + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable sets the maximum number of [idle connections](https://pkg.go.dev/database/sql#DB.SetMaxIdleConns) allowed for the database client. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `2`. +::: + +### VELA_DATABASE_CONNECTION_LIFE + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable sets the maximum duration of time [a connection is reusable](https://pkg.go.dev/database/sql#DB.SetConnMaxLifetime) for the database client. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `30m`. +::: + +### VELA_DATABASE_CONNECTION_OPEN + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable sets the maximum number of [open connections](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns) allowed for the database client. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `0` (meaning no limit is set). +::: + +### VELA_DATABASE_DRIVER + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the driver to use for the database functionality for the server. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `sqlite3`. + +The possible options to provide for this variable are: + +* `postgres` +* `sqlite3` +::: + +### VELA_DATABASE_SKIP_CREATION + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable enables skipping the creation of tables and indexes in the database system. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +### VELA_DATABASE_LOG_LEVEL + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable controls the log level to use in the database system. This can be different than the log level for the rest of the application. + +The variable can be provided as a `string` (trace, debug, info, warn, error, fatal, panic). + +:::note +This variable has a default value of `warn`. +::: + +### VELA_DATABASE_LOG_SHOW_SQL + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable controls whether to show the SQL query in the logs for the database system. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +### VELA_DATABASE_LOG_SKIP_NOTFOUND + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable controls whether to skip showing record not found errors in the logs for the in the database system. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `true`. +::: + +### VELA_DATABASE_LOG_SLOW_THRESHOLD + +This configuration variable is used by the [database component](/docs/installation/server/reference/database/) for the server. + +This variable controls the threshold that determines which queries are considered slow and logged in the database system. + +The variable can be provided as a `duration`. + +:::note +This variable has a default value of `200ms`. +::: + +### VELA_DEFAULT_BUILD_LIMIT + +This variable sets the default amount of concurrent builds a repo is allowed to run. + +In this context, concurrent builds refers to any `pending` or `running` builds for that repo. + +If the amount of concurrent builds for a repo matches the limit, then any new builds will be blocked from being created. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `10`. +::: + +### VELA_DEFAULT_BUILD_TIMEOUT + +This variable sets the default duration of time a build is allowed to run on a worker. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `30`. +::: + +### VELA_DEFAULT_REPO_EVENTS + +This variable sets the default active events for newly activated repositories. + +The variable can be provided as a comma-separated `list` (i.e. `push,tag,deployment`). + +:::note +By default, the `push` event is enabled. Valid values are: `push`, `pull_request`, `tag`, `deployment`, and `comment`. +::: + +### VELA_DISABLE_WEBHOOK_VALIDATION + +This variable disables validation of webhooks sent by the SCM to the server. + +The variable can be provided as a `boolean`. + +:::note +This variable should only be used for local development. + +This variable has a default value of `false`. +::: + +### VELA_ENABLE_SECURE_COOKIE + +This enables using cookies with the secure flag set by the server. + +The variable can be provided as a `boolean`. + +:::note +This variable should only be used for local development. + +This variable has a default value of `true`. +::: + +### VELA_LOG_FORMATTER + +This variable sets whether the logging formatter used for structured server logs is a standard JSON logger, or a custom Elasticsearch Common Schema (ECS) compatible JSON formatter. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `json`. Valid values are: `json`, and `ecs`. +::: + +### VELA_MAX_BUILD_LIMIT + +This variable sets the maximum amount of concurrent builds a repo is allowed to run. + +In this context, concurrent builds refers to any `pending` or `running` builds for that repo. + +If the amount of concurrent builds for a repo matches the limit, then any new builds will be blocked from being created. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `30`. + +This variable should match [the `VELA_MAX_BUILD_LIMIT` variable](/docs/installation/ui/reference/#vela_max_build_limit) provided to the UI. +::: + +### VELA_MODIFICATION_ADDR + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +This variable sets a fully qualified URL to the modification endpoint used for the compiler. + +The variable can be provided as a `string`. + +### VELA_MODIFICATION_RETRIES + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +This variable sets the maximum number of times to resend failed requests to the modification endpoint for the compiler. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `5`. +::: + +### VELA_MODIFICATION_SECRET + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +This variable sets a shared secret for authenticating communication between the compiler and the modification endpoint. + +The variable can be provided as a `string`. + +### VELA_MODIFICATION_TIMEOUT + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server. + +This variable sets the maximum duration of time the compiler will wait before timing out requests sent to the modification endpoint. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `8s`. +::: + +### VELA_MAX_TEMPLATE_DEPTH + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server. + +This variable sets the maximum depth of nested templates that can be called during compilation. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `3`. +::: + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_COMPILER_STARLARK_EXEC_LIMIT + +This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server. + +This variable sets the starlark execution step limit for compiling starlark pipelines. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `7500`. +::: + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_PORT + +This variable sets the port the server API responds on for HTTP requests. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `8080`. +::: + +### VELA_QUEUE_CLUSTER + +This configuration variable is used by the [queue component](/docs/installation/server/reference/queue/) for the server. + +This variable enables the server to connect to a queue cluster rather than a standalone instance. + +The variable can be provided as a `boolean`. + +:::note +This variable should match [the `VELA_QUEUE_CLUSTER` variable](/docs/installation/worker/reference/#vela_queue_cluster) provided to the worker. +::: + +### VELA_QUEUE_POP_TIMEOUT + +This configuration variable is unused by the [queue component](/docs/installation/server/reference/queue/) for the server. + +This variable sets the maximum duration of time the worker will wait before timing out requests sent for pushing workloads. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `60s`. +::: + +### VELA_QUEUE_ROUTES + +This configuration variable is used by the [queue component](/docs/installation/server/reference/queue/) for the server. + +This variable sets the unique channels or topics to push workloads to. + +The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute2`). + +:::note +This variable has a default value of `vela`. +::: + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_QUEUE_PRIVATE_KEY + +This variable sets a private key secret for signing queue items that will be opened by the worker's \. + +The variable should be provided as a base64 encoded `string`. + +### VELA_QUEUE_PUBLIC_KEY + +This variable sets a public key secret for opening queue items that have been signed by the server's \. + +The variable should be provided as a base64 encoded `string`. + +### VELA_REPO_ALLOWLIST + +This variable sets a group of repositories, from the SCM, that can be enabled on the server. + +The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,myOrg1/myRepo2,myOrg2/*`). + +:::note +By default, no repositories are allowed to be enabled. To allow any repository to be enabled, provide a single value of `*`. +::: + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_SCHEDULE_ALLOWLIST + +This variable sets a group of repositories, from the SCM, that can create a schedule for a repo on the server. + +The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,myOrg1/myRepo2,myOrg2/*`). + +:::note +By default, no repositories are allowed to create a schedule. To allow any repository to create a schedule, provide a single value of `*`. +::: + +This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings). + +### VELA_SCHEDULE_MINIMUM_FREQUENCY + +This variable sets the minimum frequency allowed to be set for a schedule. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `1h`. +::: + +### VELA_SCM_ADDR + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets a fully qualified URL to the source control management (SCM) system. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `https://github.com`. +::: + +### VELA_SCM_CONTEXT + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets the message to set in the commit status on the SCM system. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `continuous-integration/vela`. +::: + +### VELA_SCM_DRIVER + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets the driver to use for the SCM functionality for the server. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `github`. + +The possible options to provide for this variable are: + +* `github` +::: + +### VELA_SCM_SCOPES + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets the permission scopes to apply for OAuth credentials captured from the SCM system. + +The variable can be provided as a comma-separated `list` (i.e. `myScope1,myScope2`). + +:::note +This variable has a default value of `read:org,read:user,repo,repo:status,user:email`. +::: + +### VELA_SCM_WEBHOOK_ADDR + +This configuration variable is used by the [SCM component](/docs/installation/server/reference/scm/) for the server. + +This variable sets a fully qualified URL on the SCM system to send webhooks to the server. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of [the `VELA_ADDR` variable](/docs/installation/server/reference/#vela_addr) provided to the server. +::: + +### VELA_SECRET + +This variable sets a shared secret with the Vela [worker](/docs/installation/worker/) for authenticating communication between workers and the server. + +Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/docs/installation/worker/docker/#worker-server-trusted-symmetric-token). + +The variable should be provided as a `string`. + +:::note +This variable should match [the `VELA_SERVER_SECRET` variable](/docs/installation/worker/reference/#vela_server_secret) provided to the worker. +::: + +### VELA_SECRET_VAULT + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable enables using HashiCorp Vault as a secret engine. + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `false`. +::: + +### VELA_SECRET_VAULT_ADDR + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a fully qualified URL to the HashiCorp Vault instance. + +The variable can be provided as a `string`. + +### VELA_SECRET_VAULT_AUTH_METHOD + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +This variable sets the authentication method to obtain a token from the HashiCorp Vault instance. + +The variable can be provided as a `string`. + +### VELA_SECRET_VAULT_AWS_ROLE + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +This variable sets the HashiCorp Vault role to connect to the `auth/aws/login` endpoint. + +The variable can be provided as a `string`. + +### VELA_SECRET_VAULT_PREFIX + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +This variable sets the prefix for k/v secrets in the HashiCorp Vault instance. + +The variable can be provided as a `string`. + +### VELA_SECRET_VAULT_RENEWAL + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +This variable sets the frequency to renew the token for the HashiCorp Vault instance. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `30m`. +::: + +### VELA_SECRET_VAULT_TOKEN + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the token for accessing the HashiCorp Vault instance. + +The variable can be provided as a `string`. + +### VELA_SECRET_VAULT_VERSION + +This configuration variable is used by the [secret component](/docs/installation/server/reference/secret/) for the server. + +This variable sets the version for the k/v backend for the HashiCorp Vault instance. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `2`. +::: + +### VELA_USER_ACCESS_TOKEN_DURATION + +This variable sets the maximum duration of time a Vela access token for a user is valid on the server. + +The access token is used for authenticating user's requests to the server. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `15m`. +::: + +### VELA_USER_REFRESH_TOKEN_DURATION + +This variable sets the maximum duration of time a Vela refresh token for a user is valid on the server. + +The refresh token is used for refreshing a user's access token on the server. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `8h`. +::: + +### VELA_BUILD_TOKEN_BUFFER_DURATION + +This variable sets the maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server. + +The build token is used for authenticating a worker's access to the server to update build resources. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `5m`. +::: + +### VELA_WEBUI_ADDR + +This variable sets a fully qualified URL to the Vela [UI](/docs/installation/ui/) address. + +The variable can be provided as a `string`. + +### VELA_WEBUI_OAUTH_CALLBACK_PATH + +This variable sets the endpoint to use for the OAuth callback path for the Vela [UI](/docs/installation/ui/). + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `/account/authenticate`. +::: + +### VELA_WORKER_AUTH_TOKEN_DURATION + +This variable sets the maximum duration of time a Vela auth token for a worker is valid on the server. + +The worker auth token is used for authenticating a worker's access to the server to check-in and request build tokens. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable should be _longer_ than the [VELA_CHECK_IN](/docs/installation/worker/reference/#vela_check_in) in order to be able to refresh the auth token. + +This variable has a default value of `20m`. +::: + +### VELA_WORKER_REGISTER_TOKEN_DURATION + +This variable sets the maximum duration of time a Vela registration token for a worker is valid on the server. + +The worker register token is used for onboarding a worker onto the server and beginning its auth refresh routine. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable should be relatively short-lived. There is a [CLI Command](/docs/reference/cli/worker/add) to quicken the registration process for admins. + +This variable has a default value of `1m`. +::: + +### VELA_WORKER_ACTIVE_INTERVAL + +This variable sets the interval of time the workers will be considered active. A worker is considered active if it has registered with the server inside the give duration. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `5m`.\ +\ +The value should coordinate with the [`VELA_CHECK_IN`](/docs/installation/worker/reference/#vela_check_in) setting provided to the [worker](/docs/installation/worker/). +::: + +### VELA_OTEL_TRACING_ENABLE + +This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. + +:::note +This variable has a default value of `false`. +::: + +### VELA_OTEL_TRACING_SERVICE_NAME + +This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). + +:::note +This variable has a default value of `vela-server`. +::: + +### VELA_OTEL_EXPORTER_OTLP_ENDPOINT + +This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). + +:::note +This variable has no default value.\ +\ +When tracing is enabled this variable is **required**. +::: + +### VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH + +This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided, will use insecure communication. + +:::note +This variable has no default value.\ +\ +Providing no value for this variable instructs the server to export traces insecurely (no SSL). +::: + +### VELA_OTEL_TRACING_TLS_MIN_VERSION + +This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). + +:::note +This variable has a default value of `1.2`. +::: + +### VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND + +This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. + +:::note +This variable has a default value of `100`, meaning the server can record a maximum of `100 traces per second`. +::: + +### VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH + +This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (endpoints, queries, etc) are sampled. + +A `task` is basically the "span name" based on the work being performed. A `task` can be an API endpoint interaction, a gorm query, etc. + +See: https://opentelemetry.io/docs/specs/OTel/trace/api/#span + +:::note +This variable has no default value.\ +\ +When no path is provided all tasks are recorded using provided shared parameters. +::: + +### VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES + +This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=value pairs. each one will be attached to each span as a 'process' attribute. + +:::note +This variable has no default value. +::: + +### VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES + +This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=env_variable_key pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. + +:::note +This variable has no default value. +::: + +### VELA_OTEL_TRACING_SPAN_ATTRIBUTES + +This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of key=value pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. + +:::note +This variable has no default value. +::: + +### VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES + +This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of key=value pairs. Each pair will be inserted into the tracestate for each sampled span. + +:::note +This variable has no default value. +::: diff --git a/docs/reference/installation/server/settings.md b/docs/reference/installation/server/settings.md new file mode 100644 index 0000000..c049d8c --- /dev/null +++ b/docs/reference/installation/server/settings.md @@ -0,0 +1,60 @@ +--- +title: "Settings" +linkTitle: "Settings" +weight: 1 +description: > + This section contains information on using dynamic platform settings for the Vela server. +--- + +Platform Administrators can update certain properties during runtime to change how the platform behaves in real time. + +The following properties are available to be updated: + +* [`VELA_REPO_ALLOWLIST`](/docs/installation/server/reference#vela_repo_allowlist) +* [`VELA_SCHEDULE_ALLOWLIST`](/docs/installation/server/reference#vela_schedule_allowlist) +* [`VELA_MAX_TEMPLATE_DEPTH`](/docs/installation/server/reference#vela_max_template_depth) +* [`VELA_COMPILER_STARLARK_EXEC_LIMIT`](/docs/installation/server/reference#vela_compiler_starlark_exec_limit) +* [`VELA_CLONE_IMAGE`](/docs/installation/server/reference#vela_clone_image) + + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | +| `settings-refresh-interval` | the interval at which the server syncs with the database | `true` | `5s` | `VELA_PLATFORM_SETTINGS_REFRESH_INTERVAL`, `VELA_SETTINGS_REFRESH_INTERVAL` | + +:::note +For more information on how the runtime properties are consumed, please see the [server reference](/docs/installation/server/reference/). +::: + +## Permissions + +This functionality only exists for [Platform Administrators](/docs/usage/roles/). + +## Usage + +### Initializing + +The server will ensure shared settings are first initialized using the variables provided in the environment. For more information on how the runtime properties are configured, please see the [server reference](/docs/installation/server/reference/). + +On subsequent server startups, the properties controlled by the `settings` component will be retrieved from the database. + +If the database settings record is deleted then the server will fail. On the next startup the server will re-initialize the settings record using the values provided in the environment. + +### Server Synchronization + +The server will keep its own `settings` in sync with the database according to the `settings-refresh-interval` set in the environment. + +### Viewing and Updating Properties + +To view or update settings via the user interface, log into your Vela instance and click the `site admin` link in the top right corner or navigate to `https://vela-server.example.com/admin/settings`. + +Check the [CLI docs](/docs/reference/cli/settings) for instructions on modifying runtime properties via the command line. + +Updated properties will propagate to all server instances depending on the `settings-refresh-interval` set in the environment on startup. + +### Restoring Default Properties + +The [`DELETE /api/v1/admin/settings`](/docs/reference/api/admin/settings/restore) API endpoint can be used to "restore" the server to its original environment-provided configurations. Acting as a way for platform admins to undo any current modifications to the platform without restarting or modifying the database. diff --git a/docs/reference/installation/server/token_manager.md b/docs/reference/installation/server/token_manager.md new file mode 100644 index 0000000..16d9c78 --- /dev/null +++ b/docs/reference/installation/server/token_manager.md @@ -0,0 +1,33 @@ +--- +title: "Token Manager" +linkTitle: "Token Manager" +weight: 6 +description: > + This section contains information on the token manager component for the Vela server. +--- + +This component is responsible for generating and validating JWT tokens shared between the Vela server, workers, and users based off the configuration provided. + +The token manager is designed to ensure secure interactions with the server and protect build resources. + + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------- | +| `vela-server-private-key` | private key used for signing and validating all JWT tokens | `true` | `N/A` | `VELA_SERVER_PRIVATE_KEY` | +| `user-access-token-duration` | maximum duration of time a Vela access token for a user is valid on the server | `true` | `15m` | `VELA_USER_ACCESS_TOKEN_DURATION`\`USER_ACCESS_TOKEN_DURATION` | +| `user-refresh-token-duration` | maximum duration of time a Vela refresh token for a user is valid on the server | `true` | `8h` | `VELA_USER_ACCESS_TOKEN_DURATION`\`USER_ACCESS_TOKEN_DURATION` | +| `build-token-buffer-duration` | maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server | `true` | `5m` | `VELA_BUILD_TOKEN_BUFFER_DURATION`\`BUILD_TOKEN_BUFFER_DURATION` | +| `worker-auth-token-duration` | maximum duration of time an auth token for a worker is valid on the server | `false`* | `20m` | `VELA_WORKER_AUTH_TOKEN_DURATION`\`WORKER_AUTH_TOKEN_DURATION` | +| `worker-register-token-duration` | maximum duration of time a registration token for a worker is valid on the server | `false`* | `1m` | `VELA_WORKER_REGISTER_TOKEN_DURATION`\`WORKER_REGISTER_TOKEN_DURATION` | + + + +:::note +\* `worker-auth-token-duration` and `worker-register-token-duration` are required if you intend to register workers. + +For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/). +::: diff --git a/docs/reference/installation/server/tracing.md b/docs/reference/installation/server/tracing.md new file mode 100644 index 0000000..52efee6 --- /dev/null +++ b/docs/reference/installation/server/tracing.md @@ -0,0 +1,145 @@ +--- +title: "Tracing" +linkTitle: "Tracing" +weight: 7 +description: > + This section contains information on configuring OpenTelemetry instrumentation for the Vela server. +--- + +This component is responsible for instrumenting [OpenTelemetry traces](https://opentelemetry.io/docs/concepts/signals/traces/) based off the configuration provided. + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | +| `tracing.enable` | This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. | `false` | `false` | `VELA_OTEL_TRACING_ENABLE` | +| `tracing.service.name` | This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). | `false` | `vela-server` | `VELA_OTEL_TRACING_SERVICE_NAME` | +| `tracing.exporter.endpoint` | This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). | `false` | `N/A` | `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` | +| `tracing.exporter.cert_path` | This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided the server will use insecure communication. | `false` | `N/A` | `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` | +| `tracing.exporter.tls-min-version` | This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). | `false` | `1.2` | `VELA_OTEL_TRACING_TLS_MIN_VERSION` | +| `tracing.sampler.persecond` | This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. | `false` | `100` | `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` | +| `tracing.sampler.tasks` | This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (API endpoints, queries, etc) are sampled. | `false` | `N/A` | `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` | +| `tracing.resource.attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. each one will be attached to each span as a 'process' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES` | +| `tracing.resource.env_attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=env_variable_key` pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES` | +| `tracing.span.attributes` | This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_SPAN_ATTRIBUTES` | +| `tracing.tracestate.attributes` | This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of `key=value` pairs. Each pair will be inserted into the tracestate for each sampled span. | `false` | `N/A` | `VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES` | + +:::note +For more information on how the runtime properties are consumed, please see the [server reference](/docs/installation/server/reference/). +::: + +## Exporter + +To start using tracing you first need to set `VELA_OTEL_TRACING_ENABLE=true` in the runtime environment. + +Enabling tracing requires that `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` be set to an [exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/) host that is reachable over HTTP. + +If the exporter requires SSL then `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` must be set to a filepath that contains valid certificates. If no certificate filepath is set, then the server will communicate with the exporter over HTTP (insecure). + +The Vela local stack is configured to export traces to Jaeger using their "all-in-one" Docker image, making it easy to view traces out of the box. + +```diff ++ jaeger: ++ image: jaegertracing/all-in-one:latest +... + +$ docker run \ + --detach=true \ + --env=VELA_ADDR=https://vela-server.example.com \ ++ --env=VELA_OTEL_TRACING_ENABLE: true \ ++ --env=VELA_OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4318 \ +... +``` + +From the [Jaeger official website](https://www.jaegertracing.io/docs/1.6/getting-started/): +> This image, designed for quick local testing, launches the Jaeger UI, collector, query, and agent, with an in memory storage component. + +## Sampling + +The server uses a combination of "shared" and "per-task" [head sampling](https://opentelemetry.io/docs/concepts/sampling/) to control how traces are recorded or dropped. + +### "Shared" Samplers + +The following samplers are utilized by all traces produced by the server. + +#### Global Rate-limiting + +All traces share a global rate limit controlled by `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND`. + +Use `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` to set a maximum threshold of "N traces per second". The default is `100` traces per second. + +### "Task" Samplers + +Set `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` to point to a JSON filepath to control sampler configurations on a per-task basis. + +```json +tracing.json +{ + "task-name": { + "active": bool + } +} +``` + +A `task` is basically the "span name" based on the work being performed. A `task` can be an API endpoint interaction, a [Gorm](https://gorm.io/docs/index.html) query, etc. See [OTel span docs](https://opentelemetry.io/docs/specs/otel/trace/api/#span) for more information. + +If a `task` is **not** represented in the configuration file then the task will be treated normally, **with tracing enabled** using the "shared" samplers. + +| Field | Type | Description | +| ----- | ----------- | ----------- | +| `active` | bool | Set to `false` to completely disable traces for a particular task. | + +Examples of trace tasks include API endpoints, gorm queries, etc. The list of tasks will change as functionality is added to the server. + +> See the configuration file examples below. + +#### Example - No Tasks + +```json +{} +``` + +Because tasks that do not exist in the configuration file will be treated as enabled, this file will **enable all tracing**. + +#### Example - Disable /health Endpoint + +```json +{ + "/health": { + "active": false + } +} +``` + +Because `active` can be used to disable tracing, this configuration file will enable tracing for all tasks **except for the `/health` endpoint**. + +#### Example - Mixed Tasks + +```json +{ + "/health": { + "active": false + }, + "/api/v1/deployments/:org/:repo": { + "active": false + }, + "/api/v1/:worker": { + "active": true + }, + "gorm.query": { + "active": false + } +} +``` + +The task `/health` with `active: false` will **disable** tracing on `/health`. + +`/api/v1/deployments/:org/:repo` with `active: false` will **disable** tracing on `/api/v1/deployments/:org/:repo` for **ALL** `:org` and `:repo` parameters. + +`/api/v1/:worker` with `active: true` **will do nothing** at this point, because any tasks that are not present in the configuration file will automatically be sampled normally. For now this is slightly confusing, but in the future there will be more configuration fields that will determine how an `active: true` task is sampled. + +The task `gorm.query` with `active: false` would disable tracing for raw gorm queries. This is meant to show that the config applies to **all trace tasks** and not just API endpoints. + +**All other tasks** will be sampled as normal using the global shared samplers (like rate limiting)! This includes all API endpoints and gorm queries. diff --git a/docs/reference/installation/worker/executor.md b/docs/reference/installation/worker/executor.md new file mode 100644 index 0000000..71ce9d5 --- /dev/null +++ b/docs/reference/installation/worker/executor.md @@ -0,0 +1,67 @@ +--- +title: "Executor" +linkTitle: "Executor" +description: > + This section contains information on the executor component for the worker. +--- + +This component is responsible for coordinating with [the runtime](/docs/installation/worker/runtime/) to manage workload resources. + +Throughout the lifecycle of these resources, this component will track and report results back to the [server](/docs/installation/server/). + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| -------------------------------- | -------------------------------------------------------------------------- | -------- | -------------- | ------------------------------------------------------------------------- | +| `executor.driver` | type of client to control and operate executor | `true` | `linux` | `EXECUTOR_DRIVER`\`VELA_EXECUTOR_DRIVER` | +| `executor.max_log_size` | maximum log size (in bytes) | `false` | `0` (no limit) | `EXECUTOR_MAX_LOG_SIZE`\`VELA_EXECUTOR_MAX_LOG_SIZE` | +| `executor.log_streaming_timeout` | maximum time to wait, after build completion, for logs to finish streaming | `false` | `5m` | `EXECUTOR_LOG_STREAMING_TIMEOUT`\`VELA_EXECUTOR_LOG_STREAMING_TIMEOUT` | + +:::note +For more information on these configuration options, please see the [worker reference](/docs/installation/worker/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ------- | ------------------------------------------------------ | ---------------------- | +| `linux` | uses a Linux executor for running workloads | https://www.linux.com/ | +| `local` | uses a Local executor for running workloads (CLI only) | `N/A` | + +### Linux + +From the [Linux official website](https://www.linux.com/what-is-linux/): + +> Linux has been around since the mid-1990s and has since reached a user-base that spans the globe. Just like Windows, iOS, and Mac OS, Linux is an operating system. In fact, one of the most popular platforms on the planet, Android, is powered by the Linux operating system. + +The below configuration displays an example of starting the Vela worker that will use a Linux executor: + +```diff +$ docker run \ + --detach=true \ ++ --env=VELA_EXECUTOR_DRIVER=linux \ + --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_SERVER_ADDR=https://vela-server.example.com \ + --env=VELA_SERVER_SECRET= \ + --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ + --name=worker \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + --volume=/var/run/docker.sock:/var/run/docker.sock \ + target/vela-worker:latest +``` + +:::note +This Linux configuration is enabled by default and is not necessary to provide in order for Vela to operate. +::: + +### Local + +The `local` executor driver is only intended for use with the [Vela CLI](/docs/reference/cli/). + +It's not recommended to run any workloads on a worker configured with this driver. diff --git a/docs/reference/installation/worker/queue.md b/docs/reference/installation/worker/queue.md new file mode 100644 index 0000000..d83ad0d --- /dev/null +++ b/docs/reference/installation/worker/queue.md @@ -0,0 +1,58 @@ +--- +title: "Queue" +linkTitle: "Queue" +description: > + This section contains information on the queue component for the worker. +--- + +This component is responsible for integrating with a queue system based off the configuration provided. + +The queue system is used by Vela for pulling workloads, provided by the [server](/docs/installation/server/), that will be run. + +Workloads fetched from the queue are managed with a [first in, first out (FIFO)](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) strategy. + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +| ------------------- | ------------------------------------------------- | -------- | ---------- | ----------------------------------------------- | +| `queue.cluster` | configures the client for a queue cluster | `false` | `false` | `QUEUE_CLUSTER`\`VELA_QUEUE_CLUSTER` | +| `queue.driver` | type of client to control and operate queue | `true` | `N/A` | `QUEUE_DRIVER`\`VELA_QUEUE_DRIVER` | +| `queue.pop.timeout` | timeout for requests that pop items off the queue | `true` | `60s` | `QUEUE_POP_TIMEOUT`\`VELA_QUEUE_POP_TIMEOUT` | +| `queue.routes` | unique channels or topics for pulling workloads | `true` | `[ vela ]` | `QUEUE_ROUTES`\`VELA_QUEUE_ROUTES` | + +:::note +For more information on these configuration options, please see the [worker reference](/docs/installation/worker/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ------- | ----------------------------------------- | ----------------- | +| `redis` | uses a Redis queue for managing workloads | https://redis.io/ | + +### Redis + +From the [Redis official website](https://redis.io/): + +> Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster. + +The below configuration displays an example of starting the Vela worker that will connect to a Redis queue: + +```diff +$ docker run \ + --detach=true \ ++ --env=VELA_QUEUE_DRIVER=redis \ + --env=VELA_SERVER_ADDR=https://vela-server.example.com \ + --env=VELA_SERVER_SECRET= \ + --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ + --name=worker \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + --volume=/var/run/docker.sock:/var/run/docker.sock \ + target/vela-worker:latest +``` \ No newline at end of file diff --git a/docs/reference/installation/worker/runtime.md b/docs/reference/installation/worker/runtime.md new file mode 100644 index 0000000..c92be74 --- /dev/null +++ b/docs/reference/installation/worker/runtime.md @@ -0,0 +1,93 @@ +--- +title: "Runtime" +linkTitle: "Runtime" +description: > + This section contains information on the runtime component for the worker. +--- + +This component is responsible for integrating with a runtime environment based off the configuration provided. + +The runtime environment is used by Vela for executing workload resources and managing their lifecycle. + +## Configuration + +The following options are used to configure the component: + +| Name | Description | Required | Default | Environment Variables | +|------------------------------|-------------------------------------------------------------------------------------------------|----------|--------------------------|-------------------------------------------------------------------| +| `runtime.config` | path to configuration file for the runtime | `false` | `N/A` | `RUNTIME_CONFIG`\`VELA_RUNTIME_CONFIG` | +| `runtime.driver` | type of client to control and operate runtime | `true` | `docker` | `RUNTIME_DRIVER`\`VELA_RUNTIME_DRIVER` | +| `runtime.namespace` | namespace to use for the runtime (only for kubernetes) | `false` | `N/A` | `RUNTIME_NAMESPACE`\`VELA_RUNTIME_NAMESPACE` | +| `runtime.pods-template-name` | name of the PipelinePodsTemplate to retrieve from the `runtime.namespace` (only for kubernetes) | `false` | `N/A` | `RUNTIME_PODS_TEMPLATE_NAME`\`VELA_RUNTIME_PODS_TEMPLATE_NAME` | +| `runtime.pods-template-file` | path to local fallback file containing a PipelinePodsTemplate in YAML (only for kubernetes) | `false` | `N/A` | `RUNTIME_PODS_TEMPLATE_FILE`\`VELA_RUNTIME_PODS_TEMPLATE_FILE` | +| `runtime.privileged-images` | images allowed to run in privileged mode for the runtime | `false` | `[ ]` | `RUNTIME_PRIVILEGED_IMAGES`\`VELA_RUNTIME_PRIVILEGED_IMAGES` | +| `runtime.drop-capabilities` | kernel capabilities to be dropped from each running container | `false` | `N/A` | `RUNTIME_DROP_CAPABILITIES`\`VELA_RUNTIME_DROP_CAPABILITIES` | +| `runtime.volumes` | path to host volumes to mount into resources for the runtime | `false` | `N/A` | `RUNTIME_VOLUMES`\`VELA_RUNTIME_VOLUMES` | + +:::note +For more information on these configuration options, please see the [worker reference](/docs/installation/worker/reference/). +::: + +## Drivers + +The following drivers are available to configure the component: + +| Name | Description | Documentation | +| ------------ | --------------------------------------------------------------------- | ---------------------- | +| `docker` | uses a Docker daemon for creating and managing runtime resources | https://docker.io/ | +| `kubernetes` | uses a Kubernetes cluster for creating and managing runtime resources | https://kubernetes.io/ | + +### Docker + +From the [Docker official website](https://docker.io/): + +> Docker takes away repetitive, mundane configuration tasks and is used throughout the development lifecycle for fast, easy and portable application development - desktop and cloud. Docker’s comprehensive end to end platform includes UIs, CLIs, APIs and security that are engineered to work together across the entire application delivery lifecycle. + +The below configuration displays an example of starting the Vela worker that will use a Docker runtime: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_QUEUE_DRIVER=redis \ ++ --env=VELA_RUNTIME_DRIVER=docker \ + --env=VELA_SERVER_ADDR=https://vela-server.example.com \ + --env=VELA_SERVER_SECRET= \ + --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ + --name=worker \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + --volume=/var/run/docker.sock:/var/run/docker.sock + target/vela-worker:latest +``` + +:::note +This Docker configuration is enabled by default and is not necessary to provide in order for Vela to operate. +::: + +### Kubernetes + +From the [Kubernetes official website](https://kubernetes.io/): + +> Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications. + +The below configuration displays an example of starting the Vela worker that will use a Kubernetes runtime: + +```diff +$ docker run \ + --detach=true \ + --env=VELA_QUEUE_DRIVER=redis \ ++ --env=VELA_RUNTIME_DRIVER=kubernetes \ ++ --env=VELA_RUNTIME_CONFIG=/root/.kube/config \ ++ --env=VELA_RUNTIME_NAMESPACE=vela \ + --env=VELA_SERVER_ADDR=https://vela-server.example.com \ + --env=VELA_SERVER_SECRET= \ + --env=VELA_WORKER_ADDR=https://vela-worker.example.com \ + --name=worker \ + --publish=80:80 \ + --publish=443:443 \ + --restart=always \ + --volume=/var/run/docker.sock:/var/run/docker.sock \ ++ --volume=/root/.kube/config:/root/.kube/config \ + target/vela-worker:latest +``` \ No newline at end of file diff --git a/docs/reference/installation/worker/worker.md b/docs/reference/installation/worker/worker.md new file mode 100644 index 0000000..188f218 --- /dev/null +++ b/docs/reference/installation/worker/worker.md @@ -0,0 +1,303 @@ +--- +no_list: true +title: "Worker" +--- + +## Components + +The worker is made up of several components, responsible for specific tasks, necessary for the service to operate: + +| Name | Description | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `executor` | coordinates with the runtime to manage workload resources and reports results back to the [server](/docs/installation/server/) | +| `queue` | integrates with a queue provider for pulling workloads, provided by the [server](/docs/installation/server/), that will be run | +| `runtime` | integrates with a runtime environment for executing workload resources | + +## Required + +This section contains a list of all variables that must be provided to the worker. + +### VELA_QUEUE_DRIVER + +This configuration variable is used by the [queue component](/docs/installation/worker/reference/queue/) for the worker. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the driver to use for the queue functionality for the worker. + +The variable should be provided as a `string`. + +:::note +This variable should match [the `VELA_QUEUE_DRIVER` variable](/docs/installation/server/reference/#vela_queue_driver) provided to the server. + +The possible options to provide for this variable are: + +* `redis` +::: + +### VELA_SERVER_ADDR + +This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/) address. + +The variable should be provided as a `string`. + +:::note +This variable should match [the `VELA_ADDR` variable](/docs/installation/server/reference/#vela_addr) provided to the server. +::: + +### VELA_WORKER_ADDR + +This variable sets a fully qualified URL to the Vela [worker](/docs/installation/worker/) address. + +The variable should be provided as a `string`. + +## Optional + +This section contains a list of all variables that can be provided to the worker. + +### VELA_SERVER_SECRET + +This variable sets a shared secret for authenticating communication between workers and the server. + +Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/docs/installation/worker/docker/#worker-server-trusted-symmetric-token). + +The variable should be provided as a `string`. + +:::note +This variable should match [the `VELA_SECRET` variable](/docs/installation/server/reference/#vela_secret) provided to the server. +::: + +### VELA_BUILD_LIMIT + +This variable sets a number to control the maximum amount of builds that are allowed to run concurrently on the worker. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `1`. +::: + +### VELA_BUILD_TIMEOUT + +This variable sets the maximum duration of time a build can run for on the worker before being terminated. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `30m`. +::: + +### VELA_CHECK_IN + +This variable sets the maximum duration of time a worker will wait before registering with the Vela [server](/docs/installation/server/). + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `15m`.\ +\ +The value should coordinate with the [`VELA_WORKER_ACTIVE_INTERVAL`](/docs/installation/server/reference/#vela_worker_active_interval) setting provided to the [server](/docs/installation/server/). +::: + +### VELA_EXECUTOR_DRIVER + +This configuration variable is used by the [executor component](/docs/installation/worker/reference/executor/) for the worker. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the driver to use for the executor functionality for the worker. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `linux`. + +The possible options to provide for this variable are: + +* `linux` +* `local` +::: + +### VELA_EXECUTOR_MAX_LOG_SIZE + +This configuration variable is used by the [executor component](/docs/installation/worker/reference/executor/) for the worker. + +This variable sets the maximum number of bytes for logs allowed to be uploaded per step. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `0`. No limit. +::: + +### VELA_EXECUTOR_ENFORCE_TRUSTED_REPOS + +This configuration variable is used by the [executor component](/docs/installation/worker/reference/executor/) for the worker. + +This variable sets whether or not the executor will verify a repository is `trusted` before executing a build that contains privileged images (see [runtime privileged images](/docs/installation/worker/reference/#vela_runtime_privileged_images)). + +The variable can be provided as a `boolean`. + +:::note +This variable has a default value of `true`. +::: + +### VELA_QUEUE_CLUSTER + +This configuration variable is used by the [queue component](/docs/installation/worker/reference/queue/) for the worker. + +This variable enables the worker to connect to a queue cluster rather than a standalone instance. + +The variable can be provided as a `boolean`. + +:::note +This variable should match [the `VELA_QUEUE_CLUSTER` variable](/docs/installation/server/reference/#vela_queue_cluster) provided to the server. +::: + +### VELA_QUEUE_POP_TIMEOUT + +This configuration variable is used by the [queue component](/docs/installation/worker/reference/queue/) for the worker. + +This variable sets the maximum duration of time the worker will wait before timing out requests sent for pulling workloads. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `60s`. +::: + +### VELA_QUEUE_ROUTES + +This configuration variable is used by the [queue component](/docs/installation/worker/reference/queue/) for the worker. + +This variable sets the unique channels or topics to pull workloads from. + +The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute2`). + +The worker will update its own database record using the provided queue routes. If you wish to control worker routes solely using API / Database, supply `""` or `"NONE"`. + +:::note +This variable has a default value of `vela`. +::: + +### VELA_RUNTIME_CONFIG + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a fully qualified system path to a configuration file for the worker. + +The variable can be provided as a `string`. + +### VELA_RUNTIME_DRIVER + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets the driver to use for the runtime functionality for the worker. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `docker`. + +The possible options to provide for this variable are: + +* `docker` +* `kubernetes` +::: + +### VELA_RUNTIME_NAMESPACE + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +Examples using this configuration variable are provided in the above reference documentation. + +This variable sets a namespace (for Kubernetes only) to use for runtime workloads. + +The variable can be provided as a `string`. + +### VELA_RUNTIME_PODS_TEMPLATE_NAME + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +Examples using this configuration variable are provided in the [kubernetes runtime documentation](/docs/installation/worker/kubernetes/). + +This variable sets a `PipelinePodsTemplate` name (for Kubernetes only) to use for runtime workloads. +The named template must be in the `VELA_RUNTIME_NAMESPACE`. + +The variable can be provided as a `string`. + +### VELA_RUNTIME_PODS_TEMPLATE_FILE + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +This variable sets the path to a `PipelinePodsTemplate` YAML file (for Kubernetes only) to use for runtime workloads. +This file is only used if `VELA_RUNTIME_PODS_TEMPLATE_NAME` is empty. + +An example file is provided in the [kubernetes runtime documentation](/docs/installation/worker/kubernetes/). + +This is useful for Kubernetes clusters that do not allow loading CRDs. It is also used for testing Vela. + +The variable can be provided as a `string`. + +### VELA_RUNTIME_PRIVILEGED_IMAGES + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +This variable sets the [Docker image(s)](https://docs.docker.com/get-started/overview/#images) that are allowed to have privileged access on the worker. + +The variable can be provided as a comma-separated `list` (i.e. `myImage1,myImage2`). + +:::note +Please use with caution. This setting essentially grants any defined image root access to the host machine. +::: + +### VELA_RUNTIME_DROP_CAPABILITIES + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +This variable leverages the [`--cap-drop` Docker run flag](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) to disable certain kernel capabilities given to the container by default. + +This variable can be provided as a comma-separated `list` (e.g. `CAP_CHOWN,CAP_DAC_OVERRIDE`). There is some validation in place to ensure accurate capabilities are provided. + +### VELA_RUNTIME_VOLUMES + +This configuration variable is used by the [runtime component](/docs/installation/worker/reference/runtime/) for the worker. + +This variable sets the fully qualified system path(s) to file(s) on the host machine that will be mounted into workloads executed on that worker. + +The variable can be provided as a comma-separated `list` (i.e. `myVolume1,myVolume2`). + +### VELA_SERVER_CERT + +This variable sets a fully qualified system path to the TLS certificate used for HTTPS for the worker. + +The variable can be provided as a `string`. + +### VELA_SERVER_CERT_KEY + +This variable sets a fully qualified system path to the TLS certificate key used for HTTPS for the worker. + +The variable can be provided as a `string`. + +### VELA_SERVER_TLS_MIN_VERSION + +This variable sets the minimum TLS version that the worker API will accept. + +The variable can be provided as a `string`. + +:::note +This variable has a default value of `1.2`. + +The possible options to provide for this variable are: + +* `1.0` +* `1.1` +* `1.2` +* `1.3` +::: + + diff --git a/docs/reference/sdk/go.md b/docs/reference/sdk/go.md new file mode 100644 index 0000000..0d5aee1 --- /dev/null +++ b/docs/reference/sdk/go.md @@ -0,0 +1,56 @@ +--- +title: "Go" +linkTitle: "Go" +description: > + Learn how the find the documentation for the Go sdk +--- + +## Overview + +Vela Go SDK is a client to perform operations on Vela objects or view content in a new way to integrate into applications. + +For a complete list of APIs and examples, please take a look at the [Godoc Reference documentation](https://pkg.go.dev/github.com/go-vela/sdk-go/vela). + +## Minimum requirements + +Go 1.13 or above + +## Get build info example + +Below is a sample Go program demonstrating how to authenticate and get a build with the Go SDK: + +```go +package main + +import ( + "fmt" + "github.com/go-vela/sdk-go/vela" +) + +func main() { + // full URI to the Vela server + url := "https://your-vela-server.example.com" + + token := "someToken" + accessToken := "someAccessToken" + refreshToken := "someRefreshToken" + + // instantiate a new Vela client + client, err := vela.NewClient(url, nil) + if err != nil { + fmt.Println(err) + } + + // set the Authentication mechanisms for the client + client.Authentication.SetTokenAuth(token) + client.Authentication.SetAccessAndRefreshAuth(accessToken, refreshToken) + + // Get a build from the server + build, resp, err := c.Build.Get("go-vela", "sdk-go", 1) + if err != nil { + fmt.Println(err) + } + + fmt.Printf("Received response code %d, for build %+v", resp.StatusCode, build) +} +``` \ No newline at end of file diff --git a/docs/reference/sdk/python.md b/docs/reference/sdk/python.md new file mode 100644 index 0000000..716edb6 --- /dev/null +++ b/docs/reference/sdk/python.md @@ -0,0 +1,45 @@ +--- +title: "Python" +linkTitle: "Python" +description: > + Learn how the find the documentation for the Python sdk +--- + +## Overview + +Vela Python SDK is a client to perform operations on Vela objects or view content in a new way to integrate into applications. + +For a complete list of APIs and examples, please take a look at the [Python Reference documentation](https://github.com/go-vela/sdk-python#documentation-for-api-endpoints). + +## Requirements. + +Python 2.7 and 3.4+ + +## Get build info example + +Below is a sample Go program demonstrating how to authenticate and get a build with the Python SDK: + +```python +from __future__ import print_function +import time +import vela +from vela.rest import ApiException +from pprint import pprint + +# Configure API key authorization: ApiKeyAuth +configuration = vela.Configuration() +configuration.api_key['Authorization'] = 'YOUR_API_KEY' +configuration.api_key_prefix['Authorization'] = 'Bearer' + +# Configure API endpoint +configuration.host = 'https://your-vela-server.example.com' + +# create an instance of the API class +api_instance = vela.BuildsApi(vela.ApiClient(configuration)) + +try: + api_response = api_instance.get_builds(org="go-vela",repo="sdk-python") + pprint(api_response) +except ApiException as e: + print("Exception when calling BuildsApi->get_builds: %s\n" % e) +``` diff --git a/docs/reference/sdk/sdk.md b/docs/reference/sdk/sdk.md new file mode 100644 index 0000000..abc6ed6 --- /dev/null +++ b/docs/reference/sdk/sdk.md @@ -0,0 +1,11 @@ +--- +title: "SDK" +linkTitle: "SDK" +layout: SDK +description: > + This section contains information on how to use the Vela SDKs. +--- + +:::tip +Sdk repos can be found in the Vela GitHub org with an [`sdk-` prefix](https://github.com/go-vela/?q=sdk&type=&language=) +::: diff --git a/docs/reference/yaml/environment.md b/docs/reference/yaml/environment.md index 95b944d..158469c 100644 --- a/docs/reference/yaml/environment.md +++ b/docs/reference/yaml/environment.md @@ -1,6 +1,9 @@ --- title: "Environment" linkTitle: "Environment" +weight: 1 +description: > + YAML keys for environment block --- The environment key is intended to be used to inject a global environment configuration into steps, services and secret containers. Control of which container types get the injected environment settings is available via the metadata block. diff --git a/docs/reference/yaml/metadata.md b/docs/reference/yaml/metadata.md new file mode 100644 index 0000000..4007667 --- /dev/null +++ b/docs/reference/yaml/metadata.md @@ -0,0 +1,111 @@ +--- +title: "Metadata" +linkTitle: "Metadata" +weight: 2 +description: > + YAML keys for metadata block +--- + +The metadata key is intended to be used during the compile phase to signal how to treat the YAML document. + +```yaml +--- +# This document is displaying all the available keys +# in their default state for the compile process. +metadata: + template: false + clone: true +``` + +## Keys + +| Key | Required | Type | Description | +| --------------- | -------- | ----------- | ----------------------------------------------------------------- | +| `template` | Y | bool | Enables compiling the pipeline as a template. | +| `clone` | N | bool | Enables injecting the default clone process. | +| `render_inline` | N | bool | Enables rendering without explicitly calling within the pipeline. | +| `auto_cancel` | N | (see below) | Auto canceling settings for pipelines. | + +### Usage + +#### The `template:` key + +:::tip +To learn how to write templates, see the [template documentation](/docs/templates). +::: + +```yaml +--- +metadata: + # Enables compiling the pipeline as a template. This value + # is defaulted during the compile phase to "false" if not + # explicitly provided by the user. + template: true +``` + +#### The `clone:` key + +```yaml +--- +metadata: + # Enables injecting the default clone process + clone: true +``` + +#### The `environment:` key + +```yaml +--- +metadata: + # By default, the below is populated into every pipeline with + # services, steps, and secrets. But, when the block exists the + # configuration specified is used during compile phase. + environment: [steps, services, secrets] +``` + +#### The `render_inline:` key + +```yaml +--- +metadata: + # By default, the below is populated into every pipeline with + # false. But, when set to "true" a user can render a template + # in the resulting pipeline without referencing it in stages + # or steps. + render_inline: false +``` + +#### The `auto_cancel` key + +| Key | Default | Type | Description | +| ---------------- | ------- | ---- | ------------------------------------------------------------------------------------------- | +| `pending` | True | bool | Pending builds will be auto canceled if qualifying build is triggered | +| `running` | False | bool | Currently running builds will be auto canceled if qualifying build is triggered | +| `default_branch` | False | bool | Pushes to the default branch will also be auto canceled if a qualifying build is triggered. | + +A **qualifying build** is defined as either: + +- a _push_ build with the same _branch_ as another running/pending _push_ build +- a _pull request_ build with the same _head ref_ as another running/pending _pull request_ build + +These builds most often happen when a user pushes a commit to a branch and quickly pushes another commit, both of which kick off new builds. Using the `auto_cancel` block can help free up build space and eliminate pointless builds. + +By default, auto canceling is disabled altogether. However, if `running` or `default_branch` are specified, `pending` has a default value of `true` unless specified otherwise. + +```yaml +--- +# pending & running will auto cancel, but not pushes to the default branch. +metadata: + auto_cancel: + running: true +``` + +```yaml +--- +# running builds will auto cancel even if they are targeting the default branch, but pending builds will not. +metadata: + auto_cancel: + pending: false + default_branch: true + running: true +``` diff --git a/docs/reference/yaml/secrets.md b/docs/reference/yaml/secrets.md new file mode 100644 index 0000000..709702d --- /dev/null +++ b/docs/reference/yaml/secrets.md @@ -0,0 +1,159 @@ +--- +title: "Secrets" +linkTitle: "Secrets" +weight: 8 +description: > + YAML keys for secret block +--- + +The secret key is intended to be used to pull secrets from the Vela server or execute plugins to write the external secrets to the build volume. + +```yaml +--- +# This document is displaying all the required keys +# to pull various secret types. +secrets: + # Below is displaying the declarative secret definitions. + - name: foo1 + key: go-vela/docs/foo1 + engine: native + type: repo + - name: foo2 + key: go-vela/foo2 + engine: native + type: org + - name: foo3 + key: go-vela/admins/foo3 + engine: native + type: shared + - name: vault_token + key: go-vela/vault_token + engine: native + type: org + + # Below is displaying executing a secret plugin. + - origin: + name: External Vault Secret + image: target/secret-vault:latest + secrets: [ vault_token ] + parameters: + addr: vault.company.com + auth_method: token + username: vela + token: sometoken + items: + - source: secret/vela + path: user +``` + +## Keys + +| Key | Required | Type | Description | +| -------- | -------- | ------ | --------------------------------------------------------------- | +| `name` | Y | string | Name of secret to reference in the pipeline. | +| `key` | N | string | Path to secret to fetch from storage backend. | +| `engine` | N | string | Name of storage backend to fetch secret from. | +| `type` | N | string | Type of secret to fetch from storage backend. | +| `pull` | N | string | When to pull in secrets from storage backend. | +| `origin` | N | struct | Declaration to pull secrets from non-internal secret providers. | + +#### The `name:` key + +```yaml +--- +secrets: + # Name of secret to reference in the pipeline. + - name: postgres +``` + +#### The `key:` key + +:::tip +The key is unique + # to the type of secret you need to pull and follows a pattern + # to ensure the repo has the proper authorization to use the secret. + # Pattern by type: + # repo - \/\/\ + # org - \/\ + # shared - \/\/\ +::: + +```yaml +--- +secrets: + # Path to secret to fetch from storage backend. Displaying a + # repo type secret. + - key: go-vela/docs/foo1 + + # Path to secret to fetch from storage backend. Displaying a + # org type secret. + - key: go-vela/foo1 + + # Path to secret to fetch from storage backend. Displaying a + # shared type secret. + - key: go-vela/admins/foo1 +``` + +#### The `engine:` key + +:::tip +To know what engines are available for your Vela installation, we recommend consulting your system administrators. +::: + +```yaml +--- +secrets: + # Name of storage backend to fetch secret from, "native" signifies + # the backend provider is the Vela database. + - engine: native +``` + +#### The `type:` key + +```yaml +--- +secrets: + # Type of secret to fetch from storage backend. + # By default, Vela can pull repo but type accepts the + # following values: repo, org, and shared + - type: repo +``` + +#### The `pull:` key + +```yaml +--- +secrets: + # When to pull in secrets from storage backend. + # By default, Vela will pull at the beginning of a build but + # accepts the following values: build_start, step_start + - pull: step_start +``` + +:::warning `step_start` or lazy loading secrets +is not currently available for the [Kubernetes-based workers](/docs/installation/worker/kubernetes/) and does not work with secrets +originating from plugins loaded via [`origin:`](/docs/reference/yaml/secrets/#the-pull-key) (see below). +::: + +#### The `origin:` key + +| Key | Required | Type | Description | +| ------------- | -------- | -------- | ---------------------------------------------------------------- | +| `name` | Y | string | Unique identifier for the container in the pipeline. | +| `image` | Y | []string | Docker image used to create an ephemeral container. | +| `pull` | N | string | Declaration to configure if and when the Docker image is pulled. | +| `secrets` | N | struct | Sensitive variables injected into the container environment. | +| `environment` | N | map | | +| `ruleset` | N | struct | Conditions to limit the execution of the container. | +| `parameters` | N | map | Extra configuration variables specific to a plugin. | + +:::tip The `pull:` option under `origin:` +allows for different values than the +[Secrets `pull:` key](/docs/reference/yaml/secrets/#the-pull-key). It mimics the +[Steps version of the `pull:` key](/docs/reference/yaml/steps/#the-pull-key). +::: + +:::tip In an effort to reduce duplicate +documentation, see the comparable +[step keys documentation](/docs/reference/yaml/steps/#keys) to learn how keys +can be set and details on behavior. ::: diff --git a/docs/reference/yaml/services.md b/docs/reference/yaml/services.md new file mode 100644 index 0000000..d588521 --- /dev/null +++ b/docs/reference/yaml/services.md @@ -0,0 +1,126 @@ +--- +title: "Services" +linkTitle: "Services" +weight: 5 +description: > + YAML keys for services block +--- + +The `services` key is intended to be used to run applications alongside the pipeline. + +```yaml +--- +# This document is displaying all the required keys +# to run a postgres database for the duration of a pipeline. +services: + - name: postgres + image: postgres:latest +``` + +## Keys + +| Key | Required | Type | Description | +|---------------|----------|-----------------|-----------------------------------------------------------------| +| `name` | Y | string | Unique identifier for the container in the pipeline | +| `image` | Y | string | Docker image used to create an ephemeral container | +| `pull` | N | string | Declaration to configure if and when the Docker image is pulled | +| `environment` | N | map || []string | Variables to inject into the container environment | +| `entrypoint` | N | []string | Commands to execute inside the container | +| `ports` | N | string | List of ports to map for the container in the pipeline | +| `ulimits` | N | []string | Set the user limits for the container | +| `user` | N | string | Set the user for the container. | + +### Usage + +#### The `name:` key + +```yaml +--- +services: + # Unique identifier for the container in the pipeline. + - name: postgres +``` + +#### The `image:` key + +```yaml +--- +services: + # Docker image used to create ephemeral container. + - image: postgres:latest +``` + +#### The `pull:` key + +```yaml +--- +services: + # Declaration to configure if and when the Docker image is pulled. + # By default, the compiler will inject pull but accepts the + # following values: always, never, no_present, on_start, + - pull: always +``` + +#### The `environment:` key + +```yaml +--- +services: + # Variables to injected into the container environment + # using a map style syntax. + - environment: + DB_NAME: vela +``` + +```yaml +--- +services: + # Variables to injected into the container environment + # using an array style syntax. + - environment: + - DB_NAME=vela +``` + +#### The `entrypoint:` key + +```yaml +--- +services: + # Commands to execute inside the container. + - entrypoint: + - some/path/sql-init.sql + - /some/binary/postgres +``` + +#### The `ports:` key + +```yaml +--- +services: + # List of ports to map for the container in the pipeline. + - ports: + - "8080:5432" +``` + +#### The `ulimits:` key + +```yaml +--- +services: + # Set the user limits for the container. + - ulimits: + - name: foo + soft: 1024 + - name: bar + soft: 1024 + hard: 2048 +``` + +#### The `user:` key + +```yaml +--- +services: + # Run the container with the foo user. + - user: foo +``` diff --git a/docs/reference/yaml/stages.md b/docs/reference/yaml/stages.md new file mode 100644 index 0000000..ba12133 --- /dev/null +++ b/docs/reference/yaml/stages.md @@ -0,0 +1,90 @@ +--- +title: "Stages" +linkTitle: "Stages" +weight: 7 +description: > + YAML keys for stages block +--- + +The `stages` key is intended to be used to parallelize one-to-many sets of step tasks. + +```yaml +--- +# This document is displaying all the required keys +# to run two stages with one step task in parallel. +stages: + hello: + steps: + - name: Hello World + image: alpine:latest + commands: + - echo "Hello, Vela User" + + welcome: + steps: + - name: Welcome to Vela + image: alpine:latest + commands: + - echo "Welcome to Vela!" +``` + +## Keys + +| Key | Required | Type | Description | +|---------------|----------|----------|---------------------------------------------------------------------------| +| `name` | Y | string | Unique identifier for the stage in the pipeline | +| `steps` | Y | []string | Sequential execution instructions for the stage | +| `needs` | N | []string | Stages that must complete before starting the current one | +| `independent` | N | bool | Stage will execute its steps and ignore failures from other stages' steps | + +### Usage + +#### The `name:` key + +```yaml +--- +stages: + # Unique identifier for the stage in the pipeline. + welcome: +``` + +#### The `steps:` key + +```yaml +--- +stages: + # Unique identifier for the stage in the pipeline. + welcome: + # Sequential execution instructions for the stage. + steps: +``` + +:::tip +For more details on steps keys, see the [step keys documentation](/docs/reference/yaml/steps/#keys) +::: + +#### The `needs:` key + +```yaml +--- +stages: + greeting: + + # Unique identifier for the stage in the pipeline. + welcome: + # Stages that must complete before starting the current one. + needs: [ greeting ] +``` + +#### The `independent:` key + +```yaml +--- +stages: + greeting: + + # Unique identifier for the stage in the pipeline. + welcome: + # If the greeting stage fails at any point, the welcome stage will continue its execution. + independent: true +``` diff --git a/docs/reference/yaml/steps.md b/docs/reference/yaml/steps.md new file mode 100644 index 0000000..931eebd --- /dev/null +++ b/docs/reference/yaml/steps.md @@ -0,0 +1,454 @@ +--- +title: "Steps" +linkTitle: "Steps" +weight: 6 +description: > + YAML keys for steps block +--- + +The steps key is intended to be used to run sequential tasks in a pipeline. + +```yaml +--- +# This document is displaying all the required keys +# to run a postgres database for the duration of a pipeline. +steps: + - name: Hello World + image: alpine:latest + commands: + - echo "Hello, Vela User" +``` + +## Keys + +| Key | Required | Type | Description | +|---------------|----------|-----------------|------------------------------------------------------------------| +| `name` | Y | string | Unique identifier for the container in the pipeline. | +| `image` | Y | string | Docker image used to create ephemeral container. | +| `pull` | N | string | Declaration to configure if and when the Docker image is pulled. | +| `secrets` | N | struct | Sensitive variables injected into the container environment. | +| `environment` | N | map OR []string | Variables to inject into the container environment. | +| `ruleset` | N | struct | Conditions to limit the execution of the container. | +| `parameters` | N | map | Extra configuration variables specific to a plugin. | +| `commands` | N | []string | Execution instructions to run inside the container. | +| `template` | N | struct | Name of a template to expand in the pipeline. | +| `id_request` | N | string | Injects `VELA_ID_TOKEN_REQUEST_TOKEN` into step environment. | +| `entrypoint` | N | []string | Commands to execute inside the container. | +| `detach` | N | []string | Run the container in a detached (headless) state. | +| `ulimits` | N | string | Set the user limits for the container. | +| `user` | N | string | Set the user for the container. | + +### Usage + +#### The `name:` key + +```yaml +--- +steps: + # Unique identifier for the container in the pipeline. + - name: Hello World +``` + +#### The `image:` key + +```yaml +--- +steps: + # Docker image used to create ephemeral container. + - image: alpine:latest +``` + +#### The `pull:` key + +```yaml +--- +steps: + # Declaration to configure if and when the Docker image is pulled. + # By default, the compiler will inject pull with value not_present but + # accepts the following values: always, never, not_present, on_start + - pull: always +``` + +#### The `secrets:` key + +```yaml +--- +steps: + # Sensitive variables to injected into the container + # environment as upper case env. i.e. GIT_USERNAME=vela + - secrets: [ git_username ] +``` + +```yaml +--- +steps: + # Sensitive variables to injected into the container + # environment as upper case env. i.e. GIT_USERNAME= + - secrets: + # The source is the "name:" of a secret within the + # parent "secrets:" yaml key + - source: username + # The target is the desired environment key accessible during + # the container runtime. + target: git_username +``` + +#### The `environment:` key + +```yaml +--- +steps: + # Variables to injected into the container environment + # using a map style syntax. + - environment: + DB_NAME: vela +``` + +```yaml +--- +steps: + # Variables to injected into the container environment + # using an array style syntax. + - environment: + - DB_NAME=vela +``` + +#### The `ruleset:` key + +The following rules can be used to configure a ruleset: + +| Name | Description | +|------------|----------------------------------------------------| +| `branch` | name of branch for a build. | +| `comment` | pull request comment body. | +| `event` | name of an event for a build. | +| `instance` | FQDN of backend server instance. | +| `label` | pull request label. | +| `path` | path to workspace files for a build. | +| `repo` | name of the repo for a build. | +| `status` | name of status for a build. | +| `tag` | name of reference for a build. | +| `target` | name of deployment or schedule target for a build. | + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if the build + # branch is stage or main. + branch: [ stage, main ] +``` + +```yaml +--- +steps: + - ruleset: + # This extends the ability to start new builds through interactions + # within a pull request. As shown below this will run a step if a “run build” + # comment is added to the bottom of a pull request. + comment: [ "run build" ] +``` + +```yaml +--- +steps: + - name: Event Ruleset + ruleset: + # As shown below this step will execute if the build + # event is push or pull_request. The available events are: + # comment, push, pull_request, tag, and deployment. + event: [ push, pull_request ] + - name: Scope Events + ruleset: + # For pull_request and comment events, specifying an action will + # further scope when the step is executed. These actions include + # opened, synchronized, and edited for pull_request; created and + # edited for comment. To specify an action, use a ":" as shown below. + event: [pull_request:opened, comment:created] + + # Note: specifying pull_request is the same as + # [pull_request:opened, pull_request:synchronized, pull_request:reopened]. + # Specifying comment is the same as [comment:created, comment:edited]. +``` + +:::tip +Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following: + +- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ] +- `comment` -> [ `comment:created`, `comment:edited` ] +- `deployment` -> [ `deployment:created` ] + +If you wish to include _all_ event types from an event, you can specify a wildcard at the end: + +```yaml + ruleset: + event: pull_request* # will run on opened, reopened, synchronize, edited, labeled, and unlabeled +``` + +::: + +```yaml +--- +steps: + - name: Limiting execution to an instance + ruleset: + # This step will execute if the FQDN of the + # server backend instance matches the supplied value. + instance: https://vela-server.example.com +``` + +:::tip +Ensure you are supplying the address of the configured backend server and not the web UI. +::: + +```yaml +--- +steps: + - name: Labeling a pull request + ruleset: + # This step will execute if a pull request has been labeled enhancement. + event: [ 'pull_request:labeled' ] + label: [ 'enhancement' ] + - name: Editing a pull request with labels + ruleset: + # This step will execute if a pull request has been edited AND + # has the labels enhancement or documentation. + event: [ 'pull_request:edited' ] + label: [ 'enhancement', 'documentation' ] +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if file README.md, any file of type *.md + # in the root directory or any file in the test/* directory has changed. + path: [ README.md, "*.md", "test/*" ] +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if repo exists within the target GitHub + # organization or the repo is the go-vela/docs repository. + repo: [ "target/*", "go-vela/docs" ] +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if the build status is failure or success. + status: [ failure, success ] +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if the build ref is dev/* or test/*. + tag: [ dev/*, test/* ] +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this step will execute if the build target is stage or production. + # This key is only compatible with deployment and schedule events. + target: [ dev/*, test/* ] +``` + +The following controls can be used to modify the behavior of the ruleset evaluation: + +| Name | Description | Options | +|------------|----------------------------------------------------| ----------------------------------------------------------------------- | +| `continue` | enables continuing the build if the step fails. | `true`, `false` | +| `matcher` | matcher to use when evaluating the ruleset. | `filepath`, `regexp` | +| `operator` | operator to use when evaluating the ruleset. | `and`, `or` | +| `if` | limits the step execution to all rules must match. | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` | +| `unless` | limits the step execution to no rules can match. | `branch`, `comment`, `event`, `path`, `repo`, `status`, `tag`, `target` | + +```yaml +--- +steps: + - ruleset: + # As shown below this will overwrite Vela's default behavior to + # allow the build to continue the sequential step pipeline when this step fails. + continue: true +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this will overwrite Vela's default behavior to use a + # filepath matcher and instead evaluate all rules with regex. The available + # matchers are: filepath, and regexp. + # Note: The regexp matcher uses Go's regexp package. You can find documentation + # at https://golang.org/pkg/regexp/syntax/ + matcher: regexp + branch: foo-\\d +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this will overwrite Vela's default behavior to use an + # "or" behavior when comparing all ruleset rules. + # The available operators are: and, and or. + operator: or +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this will tell the ruleset to only execute + # this step when the branch is main and event is push. + if: + branch: main + event: push +``` + +```yaml +--- +steps: + - ruleset: + # As shown below this will overwrite Vela's default behavior to tell the ruleset + # to only execute this step when the branch is not main and event is not push. + unless: + branch: main + event: push +``` + +#### The `parameters:` key + +```yaml +--- +steps: + # Extra configuration variables specific to a plugin. All keys within the + # parameters key are injected environment variables into the + # container as PARAMETER_. + # As shown below this step will execute a plugin that needs two fields: + # PARAMETER_REGISTRY=index.docker.io + # PARAMETER_REPO=octocat/hello-world,go-vela/docs + - parameters: + registry: index.docker.io + repo: [ go-vela/hello-world, go-vela/docs ] +``` + +#### The `commands:` key + +```yaml +--- +steps: + # Execution instructions to run inside the container. + - entrypoint: + - echo "Hello, World" +``` + +#### The `template:` key + +The following keys can be used to configure a template injection: + +| Name | Description | +|--------| ---------------------------------------| +| `name` | Name of template to inject in the step | +| `vars` | Variables injected into the template | + +```yaml +--- +steps: + - template: + # Name of template to inject in the step. The name must map + # to an existing template in the parent "template" key. + name: example +``` + +```yaml +--- +steps: + - template: + # Variables injected into the template. Variables can be any + # primitive or complex YAML types but the corresponding template + # needs to understand how those templates are to be used. + vars: + tags: [ latest, "1.14", "1.15" ] + pull_policy: always + commands: + test: "go test ./..." + build: "go build ./..." +``` + +#### The `report_as` key + +```yaml +--- +steps: + # publish custom status for commit with `test suite` as the context + - report_as: test suite +``` + +:::tip +A pipeline can have up to 10 steps that report their own status. +::: + +#### The `id_request` key + +```yaml +steps: + # inject $VELA_ID_TOKEN_REQUEST_TOKEN into step environment. Value of `id_request` becomes one of the claims in the token. + - name: OIDC + id_request: write +``` + +More info can be found in the [OpenID Connect usage docs](usage/open_id_connect/). + +#### The `entrypoint:` key + +```yaml +--- +steps: + # Commands to execute inside the container. + - entrypoint: + - /bin/pwd + - /bin/ls +``` + +#### The `detach:` key + +```yaml +--- +steps: + # Run the container in a detached (headless) state. Similar to the + # "services:" key this will create a container that can be used throughout + # the duration of the pipeline. + - detach: true +``` + +#### The `ulimits:` key + +```yaml +--- +steps: + # Set the user limits for the container. + - ulimits: + - name: foo + soft: 1024 + - name: bar + soft: 1024 + hard: 2048 +``` + +#### The `user:` key + +```yaml +--- +steps: + # Run the container with the foo user. + - user: foo +``` + diff --git a/docs/reference/yaml/templates.md b/docs/reference/yaml/templates.md new file mode 100644 index 0000000..fb59aee --- /dev/null +++ b/docs/reference/yaml/templates.md @@ -0,0 +1,89 @@ +--- +title: "Templates" +linkTitle: "Templates" +weight: 4 +description: > + YAML keys for templates block +--- + +The template key is intended to be used to identify where to retrieve templates during the compiler phase of the pipeline. + +```yaml +--- +# This document is displaying all the required keys +# to pull a template from a remote system. +templates: + - name: example + source: github.com/go-vela/templates/example.yml + type: github +``` + +## Keys + +| Key | Required | Type | Description | +|----------|----------|--------|-------------------------------------------------------| +| `name` | Y | string | indicates a unique identifier for the template. | +| `source` | Y | string | indicates a path to a template in remote system. | +| `type` | Y | string | indicates to the compiler which version to use. | +| `format` | N | string | indicates the language used within the template file. | + +### Usage + +:::tip +To learn how to write templates, see the [template documentation](/docs/templates) +::: + +#### The `name:` key + +```yaml +templates: + # Indicates a unique identifier for the template. This identifier + # then can be used within a step to expand the template. + - name: example +``` + +#### The `source:` key + +```yaml +templates: + # Indicates a path to a template in remote system. This path + # should always be the raw path within a repository. By default + # the template is pulled from the default branch on the repository. + # It can be overwritten by adding a suffix of `@branch`, `@tag`, or + # `@commit`. + source: github.com/go-vela/templates/example.yml@testbranch +``` + +```yaml +templates: + # As an alternative, if the template is within the same repository, + # the source can be the path to the template in the Vela workspace. + # This is used in conjunction with `type: file`. + source: path/to/template.yml +``` + +#### The `type:` key + +```yaml +templates: + # Indicates to the compiler which version to use. + type: github +``` + +```yaml +templates: + # The 'file' type will grab a template from the repository on a commit. + type: file +``` + +#### The `format:` key + +```yaml +templates: + - name: example + source: github.com/go-vela/templates/example.yml + type: github + # Indicates the language used within the template file. By default + # the template will be "go" but accepts the following values: go, golang, starlark + format: starlark +``` diff --git a/docs/reference/yaml/version.md b/docs/reference/yaml/version.md new file mode 100644 index 0000000..d9c1367 --- /dev/null +++ b/docs/reference/yaml/version.md @@ -0,0 +1,16 @@ +--- +title: "Version" +linkTitle: "Version" +weight: 1 +description: > + YAML keys for version block +--- + +The version key is intended to be used in order to issue warnings for deprecated features or breaking changes within the YAML document. + +```yaml +--- +# This document is displaying using the version key within a yaml file. +version: "1" +``` + diff --git a/docs/reference/yaml/worker.md b/docs/reference/yaml/worker.md new file mode 100644 index 0000000..6e50fe7 --- /dev/null +++ b/docs/reference/yaml/worker.md @@ -0,0 +1,56 @@ +--- +title: "Worker" +linkTitle: "Worker" +weight: 3 +description: > + YAML keys for worker block +--- + +The worker key is intended to be used to route a build to a specific worker pool of workers available with the Vela queue. + +```yaml +--- +# This document is displaying all the available keys +# and routing the build to a specific worker "sm:docker". +worker: + flavor: sm + platform: docker +``` + +:::warning +Routes are defined by the Vela system administrators during installation. To know what routes are available for your Vela installation, we recommend consulting your system administrators. +::: + +## Keys + +| Key | Required | Type | Description | +|------------|----------|--------|------------------------------------------------------| +| `flavor` | N | string | Indicates what flavor of a worker. (i.e. sm, m, lg) | +| `platform` | N | string | Indicates the platform of a worker. (i.e. docker, k8s) | + +### Usage + +:::tip +See an [example](/docs/usage/examples/route/) on how to route a build. +::: + +#### The `flavor:` key + +```yaml +--- +worker: + # indicates what flavor of worker (i.e. sm, m, lg). If not specified + # will be scheduled in the generic "vela" queue. + flavor: sm +``` + +#### The `platform:` key + +```yaml +--- +worker: + # Indicates the platform of worker (i.e. docker, k8s). If not specified + # will be scheduled in the generic "vela" queue. + platform: docker +``` + diff --git a/docs/reference/yaml/yaml.md b/docs/reference/yaml/yaml.md index c69e36c..199c9fc 100644 --- a/docs/reference/yaml/yaml.md +++ b/docs/reference/yaml/yaml.md @@ -1,11 +1,14 @@ --- title: "YAML" linkTitle: "YAML" +layout: reference +description: > + reference information for creating Vela pipelines --- Steps and Stages Pipeline use "YAML Ain’t Markup Language" (YAML) which is a data serialization language designed to be human friendly. Vela accepts YAML files with either a `.yml` or `.yaml` extension. If you'd like to learn more about the YAML language, we recommend you see, "[Learn YAML in five minutes.](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes)". -:::info +:::tip The design goals for YAML are, in decreasing priority: 1. YAML is easily readable by humans. @@ -23,8 +26,8 @@ See YAML [design goals](https://yaml.org/spec/1.2/spec.html#Introduction) from s Whether you are a YAML expert or a novice, here is some quick terminology that you should be aware of: -:::info -You can get feedback directly on your `.vela.yml` or `.vela.yaml` pipelines in your IDE with the available [JSON Schema](/docs/usage/json-schema-support). +:::tip +You can get feedback directly on your `.vela.yml` or `.vela.yaml` pipelines in your IDE with the available [JSON Schema](/docs/usage/schema/). ::: ### Document @@ -59,4 +62,3 @@ canonical: "Hello, World" canonical: true ``` - diff --git a/docs/usage/_category_.json b/docs/usage/_category_.json index bb1bdb8..621c21d 100644 --- a/docs/usage/_category_.json +++ b/docs/usage/_category_.json @@ -1,7 +1,7 @@ { "label": "Usage", - "position": 2, + "position": 1, "link": { - "type": "generated-index", + "type": "generated-index" } } diff --git a/docs/usage/authenticate.md b/docs/usage/authenticate.md new file mode 100644 index 0000000..2b5f2ff --- /dev/null +++ b/docs/usage/authenticate.md @@ -0,0 +1,25 @@ +--- +title: "Authenticate" +--- + +:::warning +These docs assume you have Vela running. +::: + +## UI + +Navigate to your deployed instance and follow the OAuth workflow presented on the web interface. + +## CLI + +Please see authentication in the [CLI reference](/docs/reference/cli/authentication/). + +_If you have not yet installed the CLI, see [CLI install reference](/docs/reference/cli/install.md) first._ + +## API + +Please see authentication in the [API reference](/docs/reference/api/authentication/). + +## SDK + +Please see authentication in the [sdk reference](/docs/reference/sdk/go/). diff --git a/docs/usage/badge.md b/docs/usage/badge.md new file mode 100644 index 0000000..cd48f4e --- /dev/null +++ b/docs/usage/badge.md @@ -0,0 +1,43 @@ +--- +title: "Badges" +description: > + Show off your build status. +--- + +:::note +These docs assume you have Vela running. +::: + +### How to get your badge + +The server has an endpoint that will return an SVG badge for the default branch of your repo. The badge represents the current status for the most recent build for that branch. The most recent build refers to any build produced by the repo that is attached to that branch, which includes any event (push, pull request, etc). + +```sh +# Syntax +https:///badge///status.svg + +# Example +https://vela.example.com/badge/octocat/Hello-World/status.svg +``` + +In addition you can specify which branch you want to get a badge for by supplying a `?branch=` query parameter in the URL. + +```sh +# Syntax +https:///badge///status.svg?branch= + +# Example +https://vela.example.com/badge/octocat/Hello-World/status.svg?branch=not_default +``` + +### Embedding in Markdown + +To embed your badge in your markdown formatted file, follow this example: + +```sh +# Syntax +[![Build Status](https:///badge///status.svg)](https:////) + +# Example +[![Build Status](https://vela.example.com/badge/octocat/Hello-World/status.svg)](https://vela.example.com/octocat/Hello-World) +``` diff --git a/docs/usage/docker.md b/docs/usage/docker.md new file mode 100644 index 0000000..19f1797 --- /dev/null +++ b/docs/usage/docker.md @@ -0,0 +1,65 @@ +--- +title: "Building Docker Images" +--- + +We assume you understand how to build and run Docker images. If you need assistance on how to get started with Docker; we recommend you see their documentation for [getting set up](https://docs.docker.com/get-started/). + +Vela runs all workloads within Docker containers. Which essentially gives us two core different ways to build Docker images: + +* Without elevated daemon access +* With elevated daemon access + +Both options have disadvantages and advantages, so we encourage all Vela administrators to weigh the pros/cons of how they want to build Docker images for their cluster. Here are some resources you can use while researching available tools: + +* [What is Docker BuildKit and What can I use it for?](https://brianchristner.io/what-is-docker-buildkit/) +* [Kaniko tools comparison](https://github.com/GoogleContainerTools/kaniko#comparison-with-other-tools) + +## Without elevated daemon access + +Building an image without elevated access gives administrators the most secure pattern for not allowing any elevated access to the workers within the cluster. There are two plugin options for building those images: + +* [vela-kaniko](/docs/plugins/registry/pipeline/kaniko/) + +We recommend customers read the [tool comparisons](/docs/usage/docker/#additional-resources) before picking a technology for building their images. In-depth examples for building with either utility are available within their respective plugin documentation pages. A simple example is provided below: + +```yaml +version: "1" +steps: + - name: build and publish with kaniko + image: target/vela-kaniko:latest + pull: always + parameters: + registry: index.docker.io + repo: index.docker.io/octocat/hello-world +``` + +## With elevated daemon access + +Building an image with elevated access is a allowed pattern as long as the administrators have set the required allow list of images on the worker. It's *important to work with your administrator* to understand stand which pattern you instances was deployed to support. The supported plugin for building those images: + +* [vela-docker](/docs/plugins/registry/pipeline/docker/) + +```yaml +version: "1" +steps: + - name: build and publish with Docker's BuildKit + image: target/vela-docker:latest + pull: always + parameters: + registry: index.docker.io + tags: [ index.docker.io/octocat/hello-world ] + + - name: build and publish without Docker's BuildKit + image: target/vela-docker:latest + environment: + DOCKER_BUILDKIT=0 + pull: always + parameters: + registry: index.docker.io + tags: [ index.docker.io/octocat/hello-world ] +``` + +## Additional Resources + +* [Building Container Images Securely on Kubernetes](https://blog.jessfraz.com/post/building-container-images-securely-on-kubernetes/) +* [Why is building rootless so hard?](https://github.com/opencontainers/runc/pull/1692) diff --git a/docs/usage/enable_repo.md b/docs/usage/enable_repo.md new file mode 100644 index 0000000..6445519 --- /dev/null +++ b/docs/usage/enable_repo.md @@ -0,0 +1,25 @@ +--- +title: "Enable a Repo" +--- + +:::note +You will need **Admin** access to the repo to be able to activate it in Vela. This is because you need **Admin** access to be able to add webhooks +to the repo. +::: + +### Via the UI + +For this example, we'll go over using the UI to add the repo. You can always head over to the [CLI docs](/docs/reference/cli/repo/add/) for docs on how to add a repo via CLI. + +1. Log into your Vela instance. +1. Click "Add Repositories". +1. Select the Org from the available list. +1. Click "Add" next to the repo you would like to add. + 1. Alternatively you can "Add All" repos in an org. + 1. If your repo doesn't exist, try clicking "Refresh List" in the top right. + +Your repo now has the necessary web hook to Vela. + +:::tip +If you're coming from another CI platform you can set a starting build number by updating the counter field on the repo via the UI, [CLI](/docs/reference/cli/repo/), or [API](/docs/reference/api/repo/). +::: diff --git a/docs/usage/environment.md b/docs/usage/environment.md new file mode 100644 index 0000000..cd49cce --- /dev/null +++ b/docs/usage/environment.md @@ -0,0 +1,135 @@ +--- +title: "Using the Environment" +toc: true +description: > + Learn about how to leverage the environment within your builds. +--- + +Vela provides the ability to define environment variables scoped to individual steps, services and secrets. Additionally, if you need global environment variables you can set it at the parent and have it injected to all containers. + +Please note the environment is designed to be unique per container. Vela does inject a variety of default values from build, repo and user information. + +Defaults: + +* [Container](/docs/reference/environment/variables/#container-defaults) +* [Steps only](/docs/reference/environment/variables/#step-only-defaults) +* [Services only](/docs/reference/environment/variables/#service-only-defaults) + +## Usage + +The following [pipeline concepts](/docs/tour) are being used in the pipeline below: + +* [Services](/docs/tour/services/) + * [Environment](/docs/tour/environment/) +* [Stages](/docs/tour/stages/) + * [Environment](/docs/tour/environment/) +* [Steps](/docs/tour/steps/) + * [Environment](/docs/tour/environment/) +* [Secrets](/docs/tour/secrets/) + * [Origin](/docs/tour/secrets/) + +:::note +Please be warned that `${variable}` expressions are subject to pre-processing. + +If you do not want the pre-processor to evaluate your expression it must be escaped. +::: + +```diff +version: "1" ++ environment: ++ GLOBAL_EXAMPLE: Hello, World Globally! + +services: + - name: redis ++ environment: ++ LOCAL_EXAMPLE: Hello, World! + image: redis:latest + +stages: + first_stage: ++ environment: ++ STAGE_EXAMPLE: "All the World's a Stage!" + steps: + - name: check status + image: redis:latest ++ environment: ++ LOCAL_EXAMPLE: Hello, World! + commands: + # you can use bash commands in-line to set or override variables + - export EXAMPLE="Hello World From Vela Team" + - echo ${EXAMPLE} + - echo ${STAGE_EXAMPLE} + - echo ${GLOBAL_EXAMPLE} + +secrets: + - origin: + name: private vault + image: target/secret-vault:latest ++ environment: ++ EXAMPLE: Hello, World! + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + username: octocat + items: + - source: secret/docker + path: docker +``` + +## Global Usage + +By default global injection affects all containers ran within the pipeline. However, if you only want some container types to receive the configuration you can limit which types get them by adding the `environment` declaration into the metadata. + +:::note +Valid values for metadata `environment:` YAML key are `steps`, `services` and `secrets`. +::: + +```diff +version: "1" + environment: + GLOBAL_EXAMPLE: Hello, World Globally! + ++ metadata: ++ environment: [ steps, services ] + +services: + # Global configuration is no longer available in services + - name: redis + environment: + LOCAL_EXAMPLE: Hello, World! + image: redis:latest + +stages: + first_stage: + environment: + STAGE_EXAMPLE: "All the World's a Stage!" + steps: + - name: check status + image: redis:latest + environment: + LOCAL_EXAMPLE: Hello, World! + commands: + # you can use bash commands in-line to set or override variables + - export EXAMPLE="Hello World From Vela Team" + - echo ${EXAMPLE} + - echo ${STAGE_EXAMPLE} + - echo ${GLOBAL_EXAMPLE} + +secrets: ++ # Global configuration is no longer available in secrets since "secrets" ++ # was removed as a value in the metadata.environment block. + - origin: + name: private vault + image: target/secret-vault:latest + environment: + EXAMPLE: Hello, World! + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + username: octocat + items: + - source: secret/docker + path: docker +``` \ No newline at end of file diff --git a/docs/usage/examples/_category_.json b/docs/usage/examples/_category_.json new file mode 100644 index 0000000..37ad9f3 --- /dev/null +++ b/docs/usage/examples/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Examples", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/docs/usage/examples/file_list.txt b/docs/usage/examples/file_list.txt new file mode 100644 index 0000000..7131b53 --- /dev/null +++ b/docs/usage/examples/file_list.txt @@ -0,0 +1,13 @@ +_index.md +file_list.txt +go_modules.md +java_gradle.md +java_maven.md +mongo.md +node.md +postgres.md +redis.md +route.md +rust_cargo.md +secrets_external.md +secrets_internal.md diff --git a/docs/usage/examples/go_modules.md b/docs/usage/examples/go_modules.md new file mode 100644 index 0000000..cf1327d --- /dev/null +++ b/docs/usage/examples/go_modules.md @@ -0,0 +1,119 @@ +--- +title: "Go (With Modules)" +toc: true +weight: 1 +description: > + Example Go (With Modules) Pipeline +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Go](https://golang.org/) binary with [Go modules](https://github.com/golang/go/wiki/Modules). + +## Scenario + +User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: install + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go get ./... + + - name: test + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go test ./... + + - name: build + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go build +``` + +### Stages + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Needs](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +stages: + install: + steps: + - name: install + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go get ./... + + test: + needs: [ install ] + steps: + - name: test + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go test ./... + + build: + needs: [ install ] + steps: + - name: build + image: golang:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go build +``` \ No newline at end of file diff --git a/docs/usage/examples/java_gradle.md b/docs/usage/examples/java_gradle.md new file mode 100644 index 0000000..1af1c3c --- /dev/null +++ b/docs/usage/examples/java_gradle.md @@ -0,0 +1,117 @@ +--- +title: "Java (With Gradle)" +toc: true +weight: 2 +description: > + Example Java (With Gradle) Pipeline +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Java](https://docs.oracle.com/en/java/) application with [Gradle](https://docs.gradle.org/current/userguide/userguide.html). + +## Scenario + +User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: install + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle downloadDependencies + + - name: test + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle test + + - name: build + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle build +``` + +### Stages + +The following [pipeline concepts](/docs/tour) are being used in the pipeline below: + +* [Stages](/docs/tour/stages) + * [Needs](/docs/tour/stages) + * [Steps](/docs/tour/steps) + * [image](/docs/tour/image) + * [Environment](/docs/tour/environment) + * [Pull](/docs/tour/image) + * [Commands](/docs/tour/steps) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" +stages: + install: + steps: + - name: install + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle downloadDependencies + test: + needs: [ install ] + steps: + - name: test + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle test + + build: + needs: [ install ] + steps: + - name: build + image: gradle:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - gradle build +``` \ No newline at end of file diff --git a/docs/usage/examples/java_maven.md b/docs/usage/examples/java_maven.md new file mode 100644 index 0000000..84e5d60 --- /dev/null +++ b/docs/usage/examples/java_maven.md @@ -0,0 +1,105 @@ +--- +title: "Java (With Maven)" +toc: true +weight: 2 +description: > + Example Java (With Maven) Pipeline +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Java](https://docs.oracle.com/en/java/) application with [Maven](https://maven.apache.org/guides/index.html). + +## Scenario + +User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: install + image: maven:latest + pull: always + commands: + - mvn install + + - name: test + image: maven:latest + pull: always + commands: + - mvn test + + - name: build + image: maven:latest + pull: always + commands: + - mvn package +``` + +### Stages + +The following [pipeline concepts](/docs/tour) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Needs](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" +stages: + install: + steps: + - name: install + image: maven:latest + pull: always + commands: + - mvn install + test: + needs: [ install ] + steps: + - name: test + image: maven:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - mvn test + + build: + needs: [ install ] + steps: + - name: build + image: maven:latest + pull: always + environment: + GRADLE_USER_HOME: .gradle + GRADLE_OPTS: -Dorg.gradle.daemon=false -Dorg.gradle.workers.max=1 -Dorg.gradle.parallel=false + commands: + - mvn package +``` \ No newline at end of file diff --git a/docs/usage/examples/mongo.md b/docs/usage/examples/mongo.md new file mode 100644 index 0000000..acba050 --- /dev/null +++ b/docs/usage/examples/mongo.md @@ -0,0 +1,82 @@ +--- +title: "Mongo" +toc: true +weight: 1 +description: > + Example Pipeline with Mongo +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Mongo](https://www.mongodb.com/) as a pipeline dependency. + +## Scenario + +User is looking to create a pipeline that can integrate with an ephemeral Mongo instance. + +### Services + +Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Services](/docs/tour/services/) + * [Image](/docs/tour/image/) +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" +services: + - name: mongo + image: mongo:latest + pull: always + +steps: + - name: check status + image: mongo:latest + pull: always + commands: + # sleeping can help ensure the service adequate time to start ++ - sleep 15 + - /bin/mongosh --host mongo --eval 'db.runCommand("ping")' +``` + +### Detach + +If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" + +steps: + - name: mongo + image: mongo:latest + detach: true + + - name: check status + image: mongo:latest + commands: + # sleeping can help ensure the service adequate time to start ++ - sleep 15 + - /bin/mongosh --host mongo --eval 'db.runCommand("ping")' +``` diff --git a/docs/usage/examples/node.md b/docs/usage/examples/node.md new file mode 100644 index 0000000..d016d56 --- /dev/null +++ b/docs/usage/examples/node.md @@ -0,0 +1,99 @@ +--- +title: "Node" +toc: true +weight: 3 +description: > + Example Node Pipeline +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Node](https://nodejs.org/en/docs/) application. + +## Scenario + +User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: install + image: node:latest + pull: always + commands: + - node install + + - name: lint + image: node:latest + pull: always + commands: + - node test + + - name: build + image: node:latest + pull: always + commands: + - node build +``` + +### Stages + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Needs](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +stages: + install: + steps: + - name: install + image: node:latest + pull: always + commands: + - node install + + test: + needs: [ install ] + steps: + - name: test + image: node:latest + pull: always + commands: + - node test + + build: + needs: [ install ] + steps: + - name: build + image: node:latest + pull: always + commands: + - node build +``` \ No newline at end of file diff --git a/docs/usage/examples/postgres.md b/docs/usage/examples/postgres.md new file mode 100644 index 0000000..331f927 --- /dev/null +++ b/docs/usage/examples/postgres.md @@ -0,0 +1,96 @@ +--- +title: "Postgres" +toc: true +weight: 1 +description: > + Example Pipeline with Postgres +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Postgres](https://www.postgresql.org/) as a pipeline dependency. + +## Scenario + +User is looking to create a pipeline that can integrate with an ephemeral Postgres instance. + +### Services + +Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Services](/docs/tour/services/) + * [Image](/docs/tour/image/) +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" +services: + - name: postgres + image: postgres:latest + pull: always + environment: + POSTGRES_USER: admin + POSTGRES_PASSWORD: password + POSTGRES_DB: vela + +steps: + - name: check status + image: postgres:latest + pull: always + environment: + PGPASSWORD=password + commands: + # sleeping can help ensure the service adequate time to start + - sleep 15 + - psql -U admin -d vela -h postgres -p 5432 +``` + +### Detach + +If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" + +steps: + - name: postgres + image: postgres:latest + pull: always + environment: + POSTGRES_USER: admin + POSTGRES_PASSWORD: password + POSTGRES_DB: vela + detach: true + + - name: check status + image: postgres:latest + pull: always + environment: + PGPASSWORD=password + commands: + # sleeping can help ensure the service adequate time to start + - sleep 15 + - psql -U admin -d vela -h postgres -p 5432 +``` diff --git a/docs/usage/examples/redis.md b/docs/usage/examples/redis.md new file mode 100644 index 0000000..7b1e4c4 --- /dev/null +++ b/docs/usage/examples/redis.md @@ -0,0 +1,84 @@ +--- +title: "Redis" +toc: true +weight: 1 +description: > + Example Pipeline with Redis +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a [Redis](https://redis.io/) as a pipeline dependency. + +## Scenario + +User is looking to create a pipeline that can integrate with an ephemeral Redis instance. + +### Services + +Services Yaml block can be used with stages and steps pipelines. This example uses a basic steps configuration. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Services](/docs/tour/services/) + * [Image](/docs/tour/image/) +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" +services: + - name: redis + image: redis:latest + pull: always + +steps: + - name: check status + image: redis:latest + pull: always + commands: + # sleeping can help ensure the service adequate time to start ++ - sleep 15 + - redis-cli -h redis ping +``` + +### Detach + +If you're looking for more granular start time for the container you can add a detach flag within stages and steps pipelines. + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```diff +version: "1" + +steps: + - name: redis + image: redis:latest + pull: always + detach: true + + - name: check status + image: redis:latest + pull: always + commands: + # sleeping can help ensure the service adequate time to start ++ - sleep 15 + - redis-cli -h redis ping +``` \ No newline at end of file diff --git a/docs/usage/examples/route.md b/docs/usage/examples/route.md new file mode 100644 index 0000000..a85851a --- /dev/null +++ b/docs/usage/examples/route.md @@ -0,0 +1,83 @@ +--- +title: "Route" +toc: true +weight: 1 +description: > + Example Pipeline with build routing +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a specific runtime or platform. + +## Scenario + +User is looking to create a pipeline that can only run within a Docker runtime. + +:::tip +Work with your server administer to understand what routes are available for your installation +::: + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* *Worker* + * *Platform* +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +worker: + platform: docker + +steps: + - name: view worker name + image: alpine:latest + pull: always + commands: + - echo "Hello ${BUILD_HOST} Worker!!" +``` + +### Stages + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* *Worker* + * *Platform* +* [Stages](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Environment](/docs/tour/environment/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +worker: + platform: docker + +stages: + docker: + steps: + - name: view worker name + image: alpine:latest + pull: always + commands: + - echo "Hello ${BUILD_HOST} Worker!!" +``` diff --git a/docs/usage/examples/rust_cargo.md b/docs/usage/examples/rust_cargo.md new file mode 100644 index 0000000..20115c2 --- /dev/null +++ b/docs/usage/examples/rust_cargo.md @@ -0,0 +1,105 @@ +--- +title: "Rust (With Cargo)" +toc: true +weight: 1 +description: > + Example Rust (With Cargo) Pipeline +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project building a [Rust](https://www.rust-lang.org/) binary with [Cargo](https://doc.rust-lang.org/cargo/commands/cargo-doc.html). + +## Scenario + +User is looking to create a pipeline that builds an artifact on any event or branch pushed to source control. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: fetch + image: rust:latest + pull: always + commands: + - cargo fetch --verbose --all + + - name: test + image: rust:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - cargo test --verbose --all + + - name: build + image: rust:latest + pull: always + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - cargo build --verbose --all +``` + +### Stages + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Needs](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Commands](/docs/tour/steps/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +stages: + fetch: + steps: + - name: fetch + image: rust:latest + pull: always + commands: + - cargo fetch --verbose --all + + test: + needs: [ fetch ] + steps: + - name: test + image: rust:latest + pull: always + commands: + - cargo test --verbose --all + + build: + needs: [ fetch ] + steps: + - name: build + image: rust:latest + pull: always + commands: + - cargo build --verbose --all +``` \ No newline at end of file diff --git a/docs/usage/examples/secrets_external.md b/docs/usage/examples/secrets_external.md new file mode 100644 index 0000000..b1b6ab8 --- /dev/null +++ b/docs/usage/examples/secrets_external.md @@ -0,0 +1,134 @@ +--- +title: "External Secrets" +toc: true +weight: 1 +description: > + Example pipeline with external secrets +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a secrets to be used within a step + +## Scenario + +User is looking to create a pipeline that can integrate with a private Vault to inject secrets that can not be used with pushing a Docker image to a registry. + +:::tip +It is assumed you have created secret `vault_token` in the web interface or [CLI](/docs/reference/cli/). +::: + +The examples show a pipeline using repository secrets. Vela contains three secret types: repository, organization, and shared. For examples on organization and shared, please see the [secret concepts](/docs/tour/secrets/) documentation. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Secrets](/docs/tour/secrets/) + * [Parameters](/docs/tour/plugins/) +* [Secrets](/docs/tour/secrets/) + +The following [Vela plugins](/docs/tour/) are being used in the pipeline below: + +* [Docker](/docs/plugins/registry/pipeline/docker/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: publish hello world + image: target/vela-docker:latest + pull: always + parameters: + registry: index.docker.io + repo: index.docker.io/vela/hello-world + + +secrets: + # Note here how this pipeline uses an internal secret vault_token + # in the origin secret below to get additional secrets from an + # external service. + - name: vault_token + key: go-vela/vault_token + engine: native + type: org + + - origin: + name: private vault + image: target/secret-vault:latest + pull: always + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + username: octocat + items: + - source: secret/docker + path: docker +``` + +### Stages + +The following [pipeline concepts](/docs/tour) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Secrets](/docs/tour/secrets/) + * [Parameters](/docs/tour/plugins/) +* [Secrets](/docs/tour/secrets/) + +The following [Vela plugins](/docs/tour/) are being used in the pipeline below: + +* [Docker](/docs/plugins/registry/pipeline/docker/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +worker: + runtime: docker + +stages: + docker: + steps: + - name: publish hello world + image: target/vela-docker:latest + pull: always + secrets: [ docker_username, docker_password ] + parameters: + registry: index.docker.io + repo: index.docker.io/vela/hello-world + +secrets: + - name: vault_token + key: go-vela/vault_token + engine: native + type: org + + - origin: + name: private vault + image: target/secret-vault:latest + pull: always + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + username: octocat + items: + - source: secret/docker + path: docker +``` diff --git a/docs/usage/examples/secrets_internal.md b/docs/usage/examples/secrets_internal.md new file mode 100644 index 0000000..7314a63 --- /dev/null +++ b/docs/usage/examples/secrets_internal.md @@ -0,0 +1,117 @@ +--- +title: "Internal Secrets" +toc: true +weight: 1 +description: > + Example Pipeline with internal secrets +--- + +Example [Yaml](https://yaml.org/spec/) configuration for a project requiring a secrets to be used within a step + +## Scenario + +User is looking to create a pipeline that can inject configuration that can not be placed into a Yaml file. A simple example would be producing a Docker image with username and password. + +:::tip +It is assumed you have created secrets `docker_username` and `docker_password` in the web interface or [CLI](/docs/reference/cli/). +::: + +:::warning +Internal secrets do NOT have the `pull_request` event enabled by default. This is intentional to help mitigate exposure via a pull request against the repo. You can override this behavior, at your own risk, for each secret. +::: + +The examples show a pipeline using repo secrets. Vela contains three secret types: repo, org, and shared. Please see the [secret concepts](/docs/tour/secrets/) documentation. + +### Steps + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Secrets](/docs/tour/secrets/) + * [Parameters](/docs/tour/plugins/) +* [Secrets](/docs/tour/secrets/) + +The following [Vela plugins](/docs/tour/) are being used in the pipeline below: + +* [Docker](/docs/plugins/registry/pipeline/docker/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +steps: + - name: publish hello world + image: target/vela-docker:latest + pull: always + secrets: [ docker_username, docker_password ] + parameters: + registry: index.docker.io + repo: index.docker.io/vela/hello-world + + +secrets: + - name: docker_username + key: vela/hello-world/docker_username + engine: native + type: repo + + - name: docker_password + key: vela/hello-world/docker_password + engine: native + type: repo +``` + +### Stages + +The following [pipeline concepts](/docs/tour/) are being used in the pipeline below: + +* [Stages](/docs/tour/stages/) + * [Steps](/docs/tour/steps/) + * [Image](/docs/tour/image/) + * [Pull](/docs/tour/image/) + * [Secrets](/docs/tour/secrets/) + * [Parameters](/docs/tour/plugins/) +* [Secrets](/docs/tour/secrets/) + +The following [Vela plugins](/docs/tour/) are being used in the pipeline below: + +* [Docker](/docs/plugins/registry/pipeline/docker/) + +:::tip +Pipeline must be stored in base of repository as `.vela.yml` or `.vela.yaml` + +It is recommended to pin `image:` versions for production pipelines +::: + +```yaml +version: "1" + +stages: + docker: + steps: + - name: publish hello world + image: target/vela-docker:latest + pull: always + secrets: [ docker_username, docker_password ] + parameters: + registry: index.docker.io + repo: index.docker.io/vela/hello-world + +secrets: + - name: docker_username + key: vela/hello-world/docker_username + engine: native + type: repo + + - name: docker_password + key: vela/hello-world/docker_password + engine: native + type: repo +``` diff --git a/docs/usage/json-schema-support.md b/docs/usage/json-schema-support.md index 2f730cb..06fde76 100644 --- a/docs/usage/json-schema-support.md +++ b/docs/usage/json-schema-support.md @@ -1,6 +1,5 @@ --- title: "JSON Schema Support" -sidebar_position: 3 --- The schema gets published and updated via https://github.com/go-vela/types where it ends up as a release artifact. The latest schema is available for download from https://github.com/go-vela/types/releases/latest/download/schema.json. diff --git a/docs/usage/managing-deployments.md b/docs/usage/managing-deployments.md index 0c55f91..ada2581 100644 --- a/docs/usage/managing-deployments.md +++ b/docs/usage/managing-deployments.md @@ -1,6 +1,4 @@ ---- -sidebar_position: 4 ---- + # Managing Deployments Pipelines can be written with your specific branching methodology in mind but when it comes to deployments you often want to be very intentional with triggering a change. For this reason, Vela has deployments, a unique build event that is triggered directly via Vela on a specific ref (branch, SHA, tag). diff --git a/docs/usage/open_id_connect.md b/docs/usage/open_id_connect.md new file mode 100644 index 0000000..05cd745 --- /dev/null +++ b/docs/usage/open_id_connect.md @@ -0,0 +1,105 @@ +--- +title: "OpenID Connect" +toc: true +description: > + Learn how to leverage OpenID Connect for cloud services. +--- + +### OpenID in Vela + +Oftentimes, Vela builds interact with cloud providers to deploy software, update configurations, or more generally use the cloud's services. In order for this process to work securely, users create or retrieve credentials from the cloud provider and duplicate their values into Vela as secrets, which are injected into build steps. As an example, below is a pipeline which uploads a docker image to Artifactory: + +```yaml +version: "1" + +secrets: + # password for user Vela-Arti-User + - name: docker_password + key: VelaOrg/vela-repo + type: repo + engine: native + +steps: + - name: build & publish + image: target/vela-kaniko:latest + secrets: [ docker_password ] + parameters: + username: Vela-Arti-User + registry: my-arti-registry.com + repo: my-arti-registry.com/VelaOrg/vela-repo + tags: + - latest +``` + +The above pipeline will work and be suitable for many cloud-related CI builds. However, there are potential issues with this method. As stricter rotation policies for credentials becomes more common place, developing processes wherein Vela secrets are updated in tandem with these rotations is introducing unneccessary tech debt and is antithetical to continuous integration. + +In comes [OpenID Connect](https://openid.net/developers/how-connect-works/). + +With OpenID Connect (OIDC), you can configure your pipeline to request a short-lived access token directly from the cloud provider. This requires that the cloud provider supports OIDC processing for Vela ID tokens and properly validates the token using Vela's OpenID configuration and JWKs. + +Let's take a look at the same pipeline but using OpenID Connect. + +```yaml +version: "1" + +steps: + - name: get credentials + image: alpine + id_request: yes + commands: + - > + AUTH_TOKEN=$(curl -H "Authorization: Bearer $VELA_ID_TOKEN_REQUEST_TOKEN" + "$VELA_ID_TOKEN_REQUEST_URL?audience=artifactory" | + jq -r '.value') + - > + REQ=$(curl -s -X POST -H "Token: $AUTH_TOKEN" + "https://cloud-service-open-id-validator.com/get-token") + - echo "${REQ}" | jq -r .username > /vela/secrets/kaniko/username + - echo "${REQ}" | jq -r .token > /vela/secrets/kaniko/password + + - name: build & publish + image: target/vela-kaniko:latest + parameters: + registry: my-arti-registry.com + repo: my-arti-registry.com/VelaOrg/vela-repo + tags: + - latest +``` + +In this example, the `get credentials` step is using the Vela environment values of `VELA_ID_TOKEN_REQUEST_TOKEN` and `VELA_ID_TOKEN_REQUEST_URL` to retrieve a short-lived ID token that can be used to authenticate with the cloud service, so long as that service has an OpenID processing layer. + +The `id_request` key being set to _anything_ will result in the injection of the request environment variables. The value of `id_request` becomes a claim in the eventual ID token. + +### ID Token Claims + +```json +{ + "build_number": 42, + "build_id": 100, + "actor": "Octocat", + "actor_scm_id": "1", + "repo": "Octocat/vela-testing", + "token_type": "ID", + "image": "golang:1.22.4", + "request": "yes", + "commands": true, + "event": "pull_request:opened", + "ref": "refs/heads/main", + "sha": "15b17a5751dd2fd04a7b4ca056063dc876984073", + "iss": "https://vela-server.com/_services/token", + "sub": "repo:Octocat/vela-testing:ref:refs/heads/main:event:pull_request", + "aud": [ + "artifactory" + ], + "exp": 1717699924, + "iat": 1717699624 +} +``` + +### Validating an ID Token + +There are many resources on validating OpenID tokens. Some of the high level requirements: + +- Can the token be validated using the JWKs located at the well-known path of the issuer? +- Do the claims of the ID token match the cloud service expectations? +- Are the claims all members of the `supported_claims` field located at the well-known OpenID configuration? \ No newline at end of file diff --git a/docs/usage/outputs.md b/docs/usage/outputs.md new file mode 100644 index 0000000..6d83340 --- /dev/null +++ b/docs/usage/outputs.md @@ -0,0 +1,88 @@ +--- +title: "Outputs" +toc: true +description: > + Learn how to configure outputs for steps. +--- + +:::tip +Outputs functionality is only available in the Docker runtime. +::: + +### What are outputs and why are they useful? + +While the workspace [is shared](/docs/usage/workspace) for all steps in a build, the environment is not. This is because changes to a container environment are not exported after the completion of a step. + +For example, take the following pipeline: + +```yaml +version: "1" + +steps: + - name: parse image for testing + image: alpine:latest + commands: + # image to use is the first part of the source branch (inventory-updates -> my-organization/inventory:latest) + - image=$(echo ${VELA_PULL_REQUEST_SOURCE} | sed 's/[_.-].*//') + + - name: test + image: my-organization/${image}:latest + pull: on_start + commands: + - go test ./... + +``` + +This is not a valid pipeline configuration because `image` will not persist from the first step to the second. However, being able to dynamically update environment variables for substitution or for plugin parameters can be an important part of a CI build. + +This is where `outputs` can improve your pipeline configurations. + +Let's take the same pipeline but make it valid using outputs: + +```yaml +version: "1" + +steps: + - name: parse image for testing + image: alpine:latest + commands: + # image to use is the first part of the source branch (inventory-updates -> my-organization/inventory:latest) + - echo "image=$(echo ${VELA_PULL_REQUEST_SOURCE} | sed 's/[_.-].*//')" > $VELA_OUTPUTS + + - name: test + image: my-organization/${image}:latest + pull: on_start + commands: + - go test ./... +``` + +Writing to `$VELA_OUTPUTS` in environment file format ensures that those key-value pairs persist for the entirety of the build. + +Not only is this more convenient than storing information in the shared workspace, it can also be safer. Vela secrets are masked in logs, but any sensitive value captured during a build has the potential to be leaked in logs if steps or plugins are not configured correctly. + +This can be remedied with masked outputs: + +```yaml +version: "1" + +steps: + - name: capture API key for testing + image: alpine:latest + commands: + - apk add jq + - echo "API_KEY=$(curl http://my-test-endpoint/token | jq .token)" > $VELA_MASKED_OUTPUTS + + - name: test + image: golang:latest + commands: + - echo $API_KEY # will print *** + - go test ./... +``` + +After the first step is complete, the logs will mask any mention of the `$API_KEY`. + +### Limitations + +- Outputs can only be used as environment variables (`$VAR`) or substitution variables (`${VAR}`). Inline Go templating (`{{ .VAR }}`) is done at compile time and will not dynamically be evaluated. + +- Masking will only be applied to variables in `$VELA_MASKED_OUTPUTS` in steps that run _after_ the variable has been written. In other words, if `Step A` writes a token to `$VELA_MASKED_OUTPUTS`, `Step A` logs will _not_ mask the value. Only subsequent steps will have the masking applied. \ No newline at end of file diff --git a/docs/usage/plugin.md b/docs/usage/plugin.md new file mode 100644 index 0000000..b3a3c0f --- /dev/null +++ b/docs/usage/plugin.md @@ -0,0 +1,90 @@ +--- +title: "Working with plugins" +toc: true +description: > + Walkthrough of an example using pipeline and secret plugins working together +--- + +:::note +The following plugins are used within the example + +* [Kaniko](/docs/plugins/registry/pipeline/kaniko/) +* [Vault](/docs/plugins/registry/secret/vault/) +::: + +Typically, plugins are configured as a step in a pipeline and should accept their configuration via environment variables. The below example shows a pipeline and secret plugin working together to publish an image to a registry: + +```yaml +version: "1" + +steps: + - name: plugin + image: target/vela-kaniko + pull: always + parameters: + registry: index.docker.io + repo: index.docker.io/octocat/hello-world + +secrets: + - name: vault_token + key: go-vela/vault_token + engine: native + type: org + + - origin: + name: plugin + image: target/secret-vault + pull: always + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + items: + - source: secret/docker + path: docker +``` + +We pass these variables in Vela using the `parameters` block. Any variable passed to this block, will be injected into the step as `PARAMETER_`: + +```diff +version: "1" + +steps: + - name: docker + image: target/vela-kaniko + pull: always ++ parameters: ++ registry: index.docker.io ++ repo: index.docker.io/octocat/hello-world + +secrets: + - name: vault_token + key: go-vela/vault_token + engine: native + type: org + + - origin: + name: vault + image: target/secret-vault + pull: always + secrets: [ vault_token ] ++ parameters: ++ addr: vault.example.com ++ auth_method: token ++ items: ++ - source: secret/docker ++ path: docker +``` + +From the above example, the following environment variables would be added to the containers: + +**Docker:** + +* `PARAMETER_REGISTRY=index.docker.io` +* `PARAMETER_REPO=index.docker.io/octocat/hello-world` + +**Vault:** + +* `PARAMETER_ADDR=index.docker.io` +* `PARAMETER_AUTH_METHOD=index.docker.io/octocat/hello-world` +* `PARAMETER_ITEMS={"items": [{"source": "secret/docker"}],"path": "docker"}` diff --git a/docs/usage/plugins/tutorials/bash.md b/docs/usage/plugins/tutorials/bash.md index 940486c..6bb6bdb 100644 --- a/docs/usage/plugins/tutorials/bash.md +++ b/docs/usage/plugins/tutorials/bash.md @@ -1,8 +1,6 @@ --- title: "Bash" -linkTitle: "Bash" -description: > - Learn how to write a Vela plugin with Bash. +sidebar_position: 1 --- :::warning diff --git a/docs/usage/pull_policies.md b/docs/usage/pull_policies.md new file mode 100644 index 0000000..ccc6f5b --- /dev/null +++ b/docs/usage/pull_policies.md @@ -0,0 +1,80 @@ +--- +title: "Pull Policies" +toc: true +description: > + Learn how to control pulling images in your pipeline. +--- + +Vela provides the ability to define how and when the images for secrets, steps, and services will be retrieved at runtime. + +## Usage + +Below are the options for pull policies for container images + +| Policy | Description | +|--------------- |-----------------------------------------------------------------| +| `always` | Always attempt to pull image from registry, even if it exists locally. Best used when leveraging a mutable tag, such as `latest` | +| `not_present` | Only attempt to pull image from registry if it does not already exist locally. This is the default behavior and is recommended for immutably tagged images. | +| `on_start` | Pull image from registry right before the step is to be executed. Can speed up build times if the step or service does not run on every build (e.g. failed build notifying plugins), can be leveraged when dealing with password rotation mid-build (e.g. Vault plugin), or can be used to pull an image that was created and published earlier in the build. | +| `never` | Only use images that exist locally. | + +:::note +The `pull` declaration is **not required**. + +If you do not provide the `pull` declaration, a default value of `not_present` will be used. +::: + +## Example + +```diff +version: "1" +services: + - name: redis + image: redis:latest ++ pull: always + +steps: + - name: check status + image: alpine:latest ++ pull: not_present + commands: + # you can use bash commands in-line to set or override variables + - export EXAMPLE="Hello World From Vela Team" + - echo ${EXAMPLE} + +secrets: + - origin: + name: private vault + image: target/secret-vault:latest ++ pull: on_start + secrets: [ vault_token ] + parameters: + addr: vault.example.com + auth_method: token + username: octocat + items: + - source: secret/docker + path: docker +``` + +:::note +This pipeline will: + +* always attempt to pull the `redis:latest` image, even if it exists locally +* only pull the `alpine:latest` image if it doesn't already exist locally +* wait to pull the `target/secret-vault:latest` image until right before starting the container +::: + +## References + +The following [pipeline concepts](/docs/tour) are being used in the pipeline below: + +* [Services](/docs/tour/services/) + * [Pull](/docs/tour/image/) +* [Steps](/docs/tour/steps/) + * [Pull](/docs/tour/image/) +* [Secrets](/docs/tour/secrets/) + * [Origin](/docs/tour/secrets/) + +* [`Pull` YAML Key](/docs/reference/yaml/steps/#the-pull-key) + diff --git a/docs/usage/repo_settings.md b/docs/usage/repo_settings.md new file mode 100644 index 0000000..4ea187b --- /dev/null +++ b/docs/usage/repo_settings.md @@ -0,0 +1,148 @@ +--- +title: "Repository Settings" +linkTitle: "Repository Settings" +description: > + Learn about Vela repository settings. +--- + +## Permissions + +Before going through all the Vela repository settings, it's important to cover Vela permissions and how they apply to various parts of the Vela application. + +An overview of permissions can be found [here](/docs/usage/roles/). + +## General Repository Settings + +Below are all settings for repositories that can be changed in the Vela UI / CLI / API. + +### Webhook Events + +Vela can subscribe to any of the following webhook events: + +| Event | Description | +|------------------------------ |--------------------------------------------------------------------------- | +| `push` | a commit pushed to a repository branch | +| `tag` | a commit pushed to a repository branch | +| `pull_request:opened` | a pull request is opened | +| `pull_request:reopened` | a pull request is reopened | +| `pull_request:synchronize` | a pull request source branch has been updated with a new commit | +| `pull_request:edited` | a pull request has been edited (title, description, target branch, etc) | +| `pull_request:labeled` | a pull request has been labeled | +| `pull_request:unlabeled` | a pull request has been unlabeled | +| `deployment:created` | a deployment is created for the repository | +| `comment:created` | a comment has been made on a pull request | +| `comment:edited` | a comment has been edited on a pull request | +| `delete:branch` | a repository branch has been deleted | +| `delete:tag` | a repository tag has been deleted | + +Pipelines can be written to behave differently based on which event triggered the build (see [rulesets](/docs/tour/rulesets)). + +:::note +Event scoping (`event:action`) was included in Vela release `v0.23.0`. As such, general `event` rulesets in pipelines are mapped as following: + +- `pull_request` -> [ `pull_request:opened`, `pull_request:synchronize`, `pull_request:reopened` ] +- `comment` -> [ `comment:created`, `comment:edited` ] +- `deployment` -> [ `deployment:created` ] + +::: + +Updating webhook events for a Vela repository _must_ be done through Vela (API/CLI/UI) in order to preserve the signature integrity of the webhook. Otherwise, users will experience a [webhook signature error](/docs/faq/usage/#payload-signature-check-failed). + +### Access + +Vela supports two options for visibility: **private** or **any**. This determines who can view the Vela builds. + +By default, a newly enabled repository will inherit the visibility setting it has with the source control manager. However, if a user wishes for the visbility to differ between the source code repository and the CI repository, they can do so by changing this setting. + +### Outside Contributor Permissions + +This setting allows repository admins to further safeguard their repositories by requiring approval for builds, specifically pull requests from forks. + +The four settings are: + +- **Always Require Approval**: regardless of user, if the webhook event is a pull request from a fork, the build will need to be approved by a repository admin. +- **Require Approval For Read-Only**: some teams prefer the fork contribution workflow even if users have write permission to the repo. This setting allows those users to not need approval, but read-only users will. +- **Require Admin Approval for First Time Contributors**: users that have contributed to the repository before will be able to run pull request builds without admin approval. Note: it may take a few hours for a user to be marked as a prior contributor after they have contributed to the repository. +- **Never Require Approval**: any user will be able to run pull request builds by opening a PR against the repository. + +When a build is awaiting approval, the SCM will be updated with the status `pending` with the description `build needs approval from repo admin to run`. + +Repository admins can approve a build in the UI or by using the [CLI](/docs/reference/cli/build/approve). + +PR builds that are marked as `pending approval` will auto cancel any previous PR build from the same source (if one exists). This is to prevent a build up of builds pending approval from the same source. + +### Build Limit + +The default and max build limit is determined by the platform administrators. These values determine how many builds can be run concurrently for any given repository. These limits exist to prevent any single repository from occupying a large amount of worker resources. + +Builds that are triggered from a webhook event that result in exceeding the build limit will have to be re-launched by redelivering the webhook once the concurrent build total dips below the limit. + +### Build Timeout + +The Build Timeout setting determines the time limit for any given build for a repository. If a build lasts longer than the set timeout, the build will [error out](/docs/faq/usage/#context-deadline-exceeded). + +### Build Counter + +This number is a tally of all builds that have ran for the repository. This number can be adjusted to be larger but _NOT_ smaller. + +Occasionally, due to various compilation errors, this counter can fall behind resulting in a SQL collision error found in the audit page for new builds. To fix this, ensure the counter matches the actual build count. + +### Status Badge + +Check out the [usage documentation](/docs/usage/badge/) for more details on customizing status badges for Vela repositories. + +### Repository Actions + +**Chown** — every Vela repository requires an owner. This owner is typically the user that first enabled the repository. The owner must have _write_ permissions for the repository at the minimum. The "Chown" button (or [command](/docs/reference/cli/repo/chown/)) will transfer the ownership to the user making the request. + +**Repair** — whenever the connection between Vela and the webhook configured with the source control manager has been invalidated, the Vela repository must be repaired. This involves the deletion and re-creation of the webhook with the source repository. The build history will be preserved, but the ability to redeliver old webhooks will not. + +### Pipeline Type + +The following are the options for the formatting of the base pipeline: + +| Type | Description | +|-------------|---------------------------------------------------------------------------------------------------------| +| `YAML` | Default pipeline syntax ([Reference Documentation](/docs/reference/yaml/)) | +| `Go` | Standard YAML with Go inline functionality ([Reference Documentation](/docs/templates/tutorials/go/)) | +| `Starlark` | YAML generation using Starlark ([Reference Documentation](/docs/templates/tutorials/starlark/)) | + +Note: by default, templates are treated with `Go` syntax. In order to match that behavior for the base pipeline, this setting must be changed to `Go`. + +## Pipeline Settings + +Below are high-level pipeline settings that are pulled directly from the `metadata` key. + +### Auto Cancel + +```yaml +metadata: + auto_cancel: + running: true + default_branch: true +``` + +Auto canceling builds is a build strategy that will prioritize the most recent status of the source code by canceling obsolete running/pending builds. More information can be found [here](/docs/reference/yaml/metadata/#the-auto_cancel-key). + +### Render Inline + +```yaml +metadata: + render_inline: true + +templates: + - name: example + source: github.com/go-vela/templates/inline.yml + type: github +``` + +Render Inline is a template compilation strategy that appends templates to the end of the base pipeline in the order in which they are declared. This is the only viable method of calling templates with `stages` at the top level. More information can be found [here](/docs/templates/#rendering-inline-directly-in-velayml). + +### Clone + +```yaml +metadata: + clone: false +``` + +Setting the `clone` key to `false` will override Vela's default behavior of cloning the repository at the start of the build. More information can be found [here](/docs/tour/cloning/). diff --git a/docs/usage/roles.md b/docs/usage/roles.md new file mode 100644 index 0000000..5482c49 --- /dev/null +++ b/docs/usage/roles.md @@ -0,0 +1,57 @@ +--- +title: "Roles" +linkTitle: "Roles" +description: > + Learn about the authorization roles. +--- + +:::warning +At this time the only Source Control Provider is GitHub. So this documentation is tailored for those users. +::: + +Vela does not maintain any authentication (AuthN) or authorization (AuthZ) internally, but instead inherits its access from the source (version control) provider. More information on GitHub's access model can be found in their [documentation](https://help.github.com/en/github/getting-started-with-github/access-permissions-on-github). + +Platform Roles: + +- Admin + +Source Provider Roles: + +- Admin +- Write +- Read + +### Platform Roles + +Platform admins have full control when interacting with the CLI, UI, and API. + +### Source Provider Roles: + +Admins within the GitHub organization have the option to use GitHub orgs to allow users to have permissions on all repositories in the org, or to use fine-grained access of adding access for users directly to individual repositories. + +#### Admin + +The **admin** role enables full access to the repository, which grants the following access levels for resources: + +| Access | Repo | Build | Step | Service | Log | Secret | +| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | +| Write | Y | N | N | N | N | Y | +| Read | Y | Y | Y | Y | Y | Y | + +#### Write + +The **write** role enables read and write access to the repository, which grants the following access levels for resources: + +| Access | Repo | Build | Step | Service | Log | Secret | +| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | +| Write | Y | N | N | N | N | N | +| Read | Y | Y | Y | Y | Y | N | + +#### Read + +The **read** role enables read access to the repository, which grants the following access levels for resources: + +| Access | Repo | Build | Step | Service | Log | Secret | +| :----: | :--: | :---: | :--: | :-----: | :-: | :----: | +| Write | N | N | N | N | N | N | +| Read | Y | Y | Y | Y | Y | N | diff --git a/docs/usage/schedule_build.md b/docs/usage/schedule_build.md new file mode 100644 index 0000000..83e3245 --- /dev/null +++ b/docs/usage/schedule_build.md @@ -0,0 +1,90 @@ +--- +title: "Scheduling a Build" +linkTitle: "Scheduling a Build" +description: > + Schedule builds for your repo. +--- + +:::note +Please ensure you've already [started a build](/docs/usage/start_build/) for your repo before attempting to setup a schedule. +::: + +Vela supports the ability to periodically trigger builds for a repo known as a "schedule". + +Outside of the Vela ecosystem, this is more commonly known as a [cron expression](https://en.wikipedia.org/wiki/Cron). + +Users will be able to manage schedules for a repo via the UI, [API](/docs/reference/api/schedule/) and [CLI](/docs/reference/cli/schedule/). + +Only users with `admin` access to a repo will be able to manage schedules for that repo. + +:::warning +We make best efforts to support feature parity with `cron` but we may not support every capability. +::: + +## Entry + +Users will be able to customize the cadence or frequency for how often the schedule should trigger a build via the `entry` field. + +By default, Vela sets a frequency limit of `1h` which controls the smallest amount of time a schedule can wait before running. + +i.e. A schedule can't trigger a build more often than every hour but this may be different for the Vela installation you use. + +Here's a small list of examples to demonstrate valid values for this field: + +* `0 * * * *` - setup a schedule to run every hour +* `0 0 * * *` - setup a schedule to run every day at midnight +* `0 0 * * 0` - setup a schedule to run every week on Sunday at midnight + +Vela currently uses [github.com/adhocore/gronx](https://github.com/adhocore/gronx) to parse and validate this field. + +This library also supports a number of "common cron expressions" (a.k.a. "tags") i.e. `@hourly`, `@daily`, `@weekly` etc. + +For more information, please see that library's [official docs for these tags](https://github.com/adhocore/gronx#tags). + +:::tip +We recommend leveraging an official cron expression generator like [Crontab Guru](https://crontab.guru/) to build the `entry` for your schedule. +::: + +## Pipeline + +Uses will be able to customize what [stages](/docs/tour/stages/) or [steps](/docs/tour/steps/) will run in a build for a schedule using a [ruleset](/docs/tour/rulesets/): + +```yaml +version: "1" + +steps: + - name: unit-test + ruleset: + event: [ deployment, schedule ] + target: [ unit_test, integration_test, nightly ] + commands: + - echo "I run when a schedule with the name 'unit_test', 'integration_test' or 'nightly' is executed" + + - name: integration-test + ruleset: + event: [ deployment, schedule ] + target: [ integration_test, nightly ] + commands: + - echo "I run when a schedule with the name 'integration_test' or 'nightly' is executed" + + - name: publish + ruleset: + event: [ deployment, schedule ] + target: [ nightly ] + commands: + - echo "I run when a schedule with the name 'nightly' is executed" + + - name: notification + ruleset: + event: [ deployment, schedule ] + commands: + - echo "I run when any schedule is executed" +``` + +:::tip +We recommend adding the `deployment` event to your `ruleset` for processes that you want to run on a schedule. + +This will enable you to manually trigger a build that replicates the configuration you want to run on a schedule. + +This is especially useful when attempting to initially test and debug your pipeline for a schedule. +::: \ No newline at end of file diff --git a/docs/usage/secrets.md b/docs/usage/secrets.md new file mode 100644 index 0000000..7611837 --- /dev/null +++ b/docs/usage/secrets.md @@ -0,0 +1,265 @@ +--- +title: "Secrets" +linkTitle: "Secrets" +description: > + Learn about internal Vela secrets. +--- + +This page will primarily focus on `internal secrets`. If you would like to learn more about `external secrets`, check out the [external secrets examples page](/docs/usage/examples/secrets_external/). For a broader view of secrets and how to use `internal` or `external` secrets in your pipeline, check out the [secrets tour page](/docs/tour/secrets/). + +:::warning +Internal secrets do NOT have the `pull_request` event enabled by default. This is intentional to help mitigate exposure via a pull request against the repo. You can override this behavior, at your own risk, for each secret. +::: + +## Internal Secrets +Internal secrets are generally managed via the UI or the [CLI](/docs/reference/cli/secret/). They can also be managed via the [API](/docs/reference/api/secret/). + +A full pipeline example is available [here](/docs/usage/examples/secrets_internal/) + +_Example pipeline yaml block for internal secrets_ + +```yaml +secrets: + - name: foo1 + key: github/ocotocat/foo + engine: native + type: repo +``` + +### Name + +The name of your secret. + +### Key + +The key is autogenerated based on the other secret components, following this convention (see [Type](/docs/usage/secrets/#type)). + +* Repository: `//` +* Organization: `/` +* Shared: `//` + +### Engine + +The native secret engine is designed to store secrets in the database. This component exists for configuration future-proofing; allowing easier expansion for additional options in the future. + +### Type + +There are three types of internal secrets, with equivalent example paths for the UI: + +* Repository - `https://vela.example.com/-/secrets/native/repo//` +* Organization - `https://vela.example.com/-/secrets/native/org/` +* Shared - `https://vela.example.com/-/secrets/native/shared//` + +#### Repository + +Repository secrets are scoped to only a single repository. In order to create/modify these secrets you must be a repository admin within the source code manager. + +_Example yaml block for repository secret type_ + +```yaml +secrets: + - name: foo1 + key: github/ocotocat/foo1 + engine: native + type: repo +``` + +#### Organization + +Organization secrets are scoped to any repository in the organization. In order to create/modify these secrets you must be an organization admin within the source code manager. + +_Example yaml block for organization secret type_ + +```yaml +secrets: + - name: foo + key: github/foo + engine: native + type: org +``` + +#### Shared + +Shared secrets are scoped to any repository in the source code manager (SCM). Shared secrets are unique in the case they require a team to exist in your SCM org. In order to create/modify these secrets you must be a member of the SCM team. + +_Example yaml block for shared secret type_ + +```yaml +secrets: + - name: foo + key: github/ocotokitties/foo + engine: native + type: shared +``` + +### Protecting Secrets + +Learn the best practices for keeping your Vela secrets safe. + +#### Log Exposure + +Vela implements a masking routine that obfuscates any printing of an internal secret value in step / service logs. For example: + +```yaml +secrets: + - name: foo1 + key: github/ocotocat/foo + engine: native + type: repo + +steps: + - name: example + image: alpine + secrets: foo1 + commands: + - echo $FOO1 # will print *** +``` +:::warning +The masking routine simply looks for logs that exactly match the content of a step secret. It is important to consider this as protection against accidental logging and an opportunity for more verbose logging, NOT protection against bad actors. Those protections are described below. +::: + +#### Pull Request Event + Build Approval + +Secrets by default do not have the `pull request` event enabled, as this event can be triggered by users without `write` access to the repository. Therefore, if users do require secrets for `pull request` events, it is best practice to adopt a [build approval policy](/docs/usage/repo_settings/#outside-contributor-permissions), which will allow repository admins to validate the safety of the pipeline. + +#### Other Secret Settings + +Defaults for various secret types + +| Setting | Repo | Org | Shared | +|--------------------- |----------------------- |----------------------- |----------------------- | +| `Allow Command` | Yes | Yes | No | +| `Allow Substitution` | Yes | Yes | No | +| `Images` | Any | Any | Any | +| `Allow Events` | Push, Tag, Deployment | Push, Tag, Deployment | Push, Tag, Deployment | + +**Allow Command**: + +This setting prevents secrets from being injected into the container environment whenever a `commands` block or custom `entrypoint` is specified. For example: + +```yaml +secrets: + - name: no_commands # 'allow command' set to false + key: vela/no_commands + type: org + engine: native + + - name: yes_commands # 'allow command' set to true + key: vela/yes_commands + type: org + engine: native + +steps: + - name: print secret mask + image: alpine:latest + secrets: [ no_commands, yes_commands ] + commands: + - echo $NO_COMMANDS # will print nothing (not injected) + - echo $YES_COMMANDS # will print secret mask *** +``` + +**Allow Substitution**: + +This setting prevents secrets from being substituted in the pipeline configuration by referencing its key in `${KEY}` format. This setting, in tandem with disallowing commands, prevents users from attempting to bypass Vela's secret masking in logs. Example: + +```yaml +secrets: + - name: no_substitution # 'allow substitution' set to false + key: vela/no_substitution + type: org + engine: native + + - name: yes_substitution # 'allow substitution' set to true + key: vela/yes_substitution + type: org + engine: native + +steps: + - name: docker build + image: target/vela-kaniko + secrets: [ no_substitution, yes_substitution ] + parameters: + build_args: + - FOO=${NO_SUBSTITUTION} # FOO will be empty + - BAR=${YES_SUBSTITUTION} # BAR will be the value of YES_SUBSTITUTION + + - name: command substitution + image: alpine + secrets: [ no_substitution, yes_substitution ] + commands: + # As a caveat to this setting, both the following commands will in fact pull in the secret values. + # This is because Vela converts all commands to a shell script, and these ${KEY} substitutions are + # actually shell environment substitutions rather than Vela runtime substitutions. + - wget --header="X-Auth-Token: ${NO_SUBSTITUTION}" https://www.example.com + - wget --header="X-Auth-Token: ${YES_SUBSTITUTION}" https://www.example.com +``` + +:::note +If you have a secret which a plugin expects as a specific environment variable, you can leverage `target` rather than substitution: + +```diff +steps: + - name: custom plugin + image: docker.company.com/my-org/my-plugin + secrets: +- - github_token ++ - source: github_token ++ target: PARAMETER_API_TOKEN + parameters: +- api_token: ${GITHUB_TOKEN} +``` + +This is a much safer practice. +::: + +**Images**: + +You can further protect a secret by limiting its usage to certain images. This ensures that every time a secret is injected into a container environment, it will be used in an expected way. + +You can specify tag-specific images or base images. + +```yaml +secrets: + - name: any_image # `images` set to "any" + key: vela/any_image + type: org + engine: native + + - name: kaniko_only # `images` set to "target/vela-kaniko" + key: vela/kaniko_only + type: org + engine: native + +steps: + - name: docker build + image: target/vela-kaniko + secrets: + - source: any_image + target: KANIKO_USERNAME # injected as KANIKO_USERNAME + - source: kaniko_only + target: KANIKO_PASSWORD # injected as KANIKO_PASSWORD + parameters: + registry: docker.company.com + repo: docker.company.com/some/repo + tags: + - ${VELA_BUILD_COMMIT:0:8} + + - name: alpine use + image: alpine:latest + secrets: [ any_image, kaniko_only ] + commands: + - echo $ANY_IMAGE # will print ***, signaling its injection to the environment + - echo $KANIKO_ONLY # will print nothing, not injected +``` + +**Allow Events**: + +Secrets can be restricted to only be injected into container environments on certain webhook events. This can be useful to limiting potential exposure opportunities and only using a secret when necessary. + + +:::note +To update any of these settings, you can edit the secret in the UI. + +You may also use the [CLI](/docs/reference/cli/secret) or [API](/docs/reference/api/secret) +::: + diff --git a/docs/usage/skipping_build.md b/docs/usage/skipping_build.md new file mode 100644 index 0000000..1492fa8 --- /dev/null +++ b/docs/usage/skipping_build.md @@ -0,0 +1,20 @@ +--- +title: "Skipping a Build" +linkTitle: "Skipping a Build" +description: > + Skip builds for certain commits. +--- + +To prevent Vela from running a build for a commit, add one of the following to your commit title or message: + +- `[skip ci]` +- `[ci skip]` +- `[skip vela]` +- `[vela skip]` +- `***no_ci***` + +:::note +You can use upper or lower case. +::: + +Vela will receive the payload from the source control provider and return a 200 response with a reason for why a build was not triggered. \ No newline at end of file diff --git a/docs/usage/stage_orchestration.md b/docs/usage/stage_orchestration.md new file mode 100644 index 0000000..9d9c9cf --- /dev/null +++ b/docs/usage/stage_orchestration.md @@ -0,0 +1,267 @@ +--- +title: "Stage Orchestration" +linkTitle: "Stage Orchestration" +description: > + Learn how to orchestrate pipelines with stages. +--- + +This page will focus on [`stages`](/docs/tour/stages) and how to effectively leverage the orchestration options given to users. These options are: the [`ruleset`](/docs/tour/rulesets) key, the [`needs`](/docs/reference/yaml/stages/#the-needs-key) key, and the [`independent`](/docs/reference/yaml/stages/#the-independent-key) key. + +### Step Rulesets in Stages + +To begin, let's focus on the `ruleset` key. While this is not a key at the stages level, each stage has a collection of steps, which can all be given rulesets. There are two kinds of rules within Vela: compile-time rules (path, event, branch, comment, tag, target, and repo) and a runtime rule (status). When Vela compiles a pipeline, it will purge any steps that do not meet the compile-time rules. + +For example, let's consider a pipeline written as such: + +```yaml +version: "1" + +stages: + build: + steps: + - name: Build My Code + image: golang:latest + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go build + + deploy: + steps: + - name: Publish My Docker Image + image: target/vela-kaniko:latest + ruleset: + event: push + branch: main + parameters: + registry: index.docker.io + repo: index.docker.io/octocat/hello-world + dry-run: false + notify: + needs: [ build, deploy ] + steps: + - name: Report Failure + image: target/vela-slack:latest + ruleset: + status: failure + parameters: + text: "Failure!" +``` + +If a Vela build is triggered on a `push` to a branch named `issue-123`, the pipeline will be compiled like this: + +```yaml +version: "1" + +stages: + build: + steps: + - name: Build My Docker Image + image: target/vela-kaniko:latest + parameters: + registry: index.docker.io + repo: index.docker.io/octocat/hello-world + dry-run: true + notify: + needs: [ build ] + steps: + - name: Report Failure + image: target/vela-slack:latest + ruleset: + status: failure + parameters: + text: "Failure!" +``` + +Notice how the `deploy` stage has been pruned completely, rather than being a stage with empty steps. Further, since the `notify` stage normally waits on both `build` and `deploy`, in this situation, it only waits on `build`. The `notify` stage is still part of the build since its ruleset consists of only a runtime rule. + +### Understanding the `needs` key + +While there isn't a sure-fire way of running stages in order, the `needs` key introduces a level of dependency that can be used to order stages. However the `needs` key can become tricky when combined with pruning, as shown in the example above. Let's take a look at a theoretical pipeline: + +```yaml +version: "1" + +stages: + run-first: + steps: + - name: sleep for 10 + image: alpine:latest + commands: + - sleep 10 + - echo "done"" + + runtime-ruleset-stage: + needs: [ run-first ] + steps: + - name: fail + image: alpine:latest + ruleset: + status: failure + commands: + - echo "runtime rule" + + compile-time-ruleset-stage: + needs: [ run-first ] + steps: + - name: pruned + image: alpine:latest + ruleset: + branch: not-main + commands: + - echo "never ran" + + x-stage: + needs: [ runtime-ruleset-stage, compile-time-ruleset-stage ] + steps: + - name: who ran the build + image: alpine:latest + commands: + - sleep 20 + - echo $VELA_BUILD_AUTHOR + + y-stage: + needs: [ compile-time-ruleset-stage ] + steps: + - name: what repo is this + image: alpine:latest + commands: + - sleep 20 + - echo $VELA_REPO_FULL_NAME +``` + +:::tip +Be aware that `needs:` references stages by their name, which can be overridden by the `name` key in the stage definition. +::: + +Consider a Vela build triggered by a `push` to `main`. We know that `run-first` will indeed run first, followed by `runtime-ruleset-stage` since it cannot be pruned due to its runtime rule. However, if we recall from our first example, when the _entirety_ of a stage's step collection is pruned at compile-time, the stage disappears completely: + +```yaml +version: "1" + +stages: + run-first: + steps: + - name: sleep for 10 + image: alpine:latest + commands: + - sleep 10 + - echo "done"" + + runtime-ruleset-stage: + needs: [ run-first ] + steps: + - name: fail + image: alpine:latest + ruleset: + status: failure + commands: + - echo "runtime rule" + + x-stage: + needs: [ runtime-ruleset-stage ] + steps: + - name: who ran the build + image: alpine:latest + commands: + - sleep 20 + - echo $VELA_BUILD_AUTHOR + + y-stage: + needs: [ ] + steps: + - name: what repo is this + image: alpine:latest + commands: + - sleep 20 + - echo $VELA_REPO_FULL_NAME +``` + +So in fact, in this scenario, the `run-first` stage and the `y-stage` begin simultaneously, even though `y-stage` "needed" `compile-time-ruleset-stage` which "needed" `run-first` in the original pipeline. + +### Leveraging Stage independence + +With the increasing popularity of monorepos, some Vela pipelines may want to simultaneously execute very different build flows based on modules within the repository. Since by nature Vela stages will skip the remainder of the build if a single stage fails its pipeline, this could potentially cause issues, such as half-done deployments. + +For example, say we have a repo that has back-end _and_ front-end code written together. Let's assume all the back-end code is in `org/repo/back-end` and the front-end code is in `org/repo/front-end`. We can leverage the [`path`](/docs/reference/yaml/steps/#the-ruleset-key) ruleset with the [`independent`](/docs/reference/yaml/stages/#the-independent-key) stage key to compartmentalize Vela builds: + +```yaml +version: "1" + +stages: + test-and-build-backend: + independent: true + steps: + - name: install go + image: golang:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/back-end/* + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go get ./... + + - name: test go + image: golang:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/back-end/* + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go test ./... + + - name: build go + image: golang:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/back-end/* + environment: + CGO_ENABLED: '0' + GOOS: linux + commands: + - go build + + test-and-build-frontend: + independent: true + steps: + - name: install node + image: node:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/front-end/* + commands: + - node install + + - name: lint node + image: node:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/front-end/* + commands: + - node test + + - name: build node + image: node:latest + pull: always + ruleset: + matcher: regexp + path: org/repo/front-end/* + commands: + - node build +``` + +We can extend this example to deployments, and it's easy to see where a team may want one module to complete its build flow even if there's a failure in another module. + +### In Summary + +Stages are an advanced tool to help with writing powerful and sensible pipelines with parallel execution. While these orchestration tools are helpful, consider just using `steps` to simplify pipelines that don't need the, sometimes surprising, complexity. diff --git a/docs/usage/start_build.md b/docs/usage/start_build.md new file mode 100644 index 0000000..eb5582f --- /dev/null +++ b/docs/usage/start_build.md @@ -0,0 +1,10 @@ +--- +title: "Start a Build" +linkTitle: "Start a Build" +description: > + Start a build for the first time. +--- + +If you've followed the documentation for [enabling a repo](/docs/usage/enable_repo/) and wrote a pipeline ([here are some example pipelines](/docs/usage/examples/)), all that should be left is to push your pipeline to your repo. + +If a build does not trigger when your push a change to your repo, check the webhook response to see if there is an error. diff --git a/docs/reference/_category_.json b/docs/usage/templates/go/_category_.json similarity index 55% rename from docs/reference/_category_.json rename to docs/usage/templates/go/_category_.json index 6a91167..55cadad 100644 --- a/docs/reference/_category_.json +++ b/docs/usage/templates/go/_category_.json @@ -1,6 +1,6 @@ { - "label": "Reference", - "position": 3, + "label": "Go", + "position": 1, "link": { "type": "generated-index", } diff --git a/docs/usage/templates/go/conditional.md b/docs/usage/templates/go/conditional.md new file mode 100644 index 0000000..6a5d833 --- /dev/null +++ b/docs/usage/templates/go/conditional.md @@ -0,0 +1,106 @@ +--- +title: "Conditionals" +linkTitle: "Conditionals" +description: > + Example Go template with conditionals. +--- + +:::tip +We recommend reviewing [Go Templates documentation](https://golang.org/pkg/text/template/) before attempting to create a template. + +If you're new to YAML we also recommend reviewing the [YAML 1.2 spec](https://yaml.org/spec/1.2/spec.html) for validation on syntax. +::: + +## Overview + +From [Go template Conditional](https://golang.org/pkg/text/template/#hdr-Actions): + +```text +{{if pipeline}} + T1 +{{end}} +``` + +> If the value of the pipeline is empty, no output is generated; +> otherwise, T1 is executed. The empty values are false, 0, any +> nil pointer or interface value, and any array, slice, map, or +> string of length zero. +> Dot is unaffected. + +:::tip +For information on if/else statements see [conditional docs](https://golang.org/pkg/text/template/#hdr-Actions) +::: + +## Sample + +Let's take a look at using a conditional with a variable in a template: + +```yaml +metadata: + template: true + +{{$br := vela "BUILD_BRANCH"}} + +steps: + + - name: test + commands: + - go test ./... + image: {{ .image }} + {{ .pull_policy }} + ruleset: + event: [ push, pull_request ] + + # if branch equals main add this step to the final pipeline + {{ if (eq $br "main") }} + + - name: build + commands: + - go build + image: {{ .image }} + {{ .pull_policy }} + ruleset: + event: [ push, pull_request ] + + {{ end }} +``` + +The caller of this template could look like: + +```yaml +version: "1" +templates: + - name: sample + source: github.com///path/to/file/