diff --git a/content/reference/api/admin/settings/_index.md b/content/reference/api/admin/settings/_index.md new file mode 100644 index 00000000..2064f7e2 --- /dev/null +++ b/content/reference/api/admin/settings/_index.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. + +{{% alert color="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/). +{{% /alert %}} diff --git a/content/reference/api/admin/settings/restore.md b/content/reference/api/admin/settings/restore.md new file mode 100644 index 00000000..43182bac --- /dev/null +++ b/content/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 + +{{% alert color="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/). +{{% /alert %}} + +#### 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/content/reference/api/admin/settings/update.md b/content/reference/api/admin/settings/update.md new file mode 100644 index 00000000..abfc7732 --- /dev/null +++ b/content/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 + +{{% alert color="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/). +{{% /alert %}} + +#### 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/content/reference/api/admin/settings/view.md b/content/reference/api/admin/settings/view.md new file mode 100644 index 00000000..db965c38 --- /dev/null +++ b/content/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 + +{{% alert color="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/). +{{% /alert %}} + +#### 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/content/reference/cli/settings/_index.md b/content/reference/cli/settings/_index.md new file mode 100644 index 00000000..b66680e9 --- /dev/null +++ b/content/reference/cli/settings/_index.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. + +{{% alert color="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 setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +{{% /alert %}} diff --git a/content/reference/cli/settings/update.md b/content/reference/cli/settings/update.md new file mode 100644 index 00000000..ded3d100 --- /dev/null +++ b/content/reference/cli/settings/update.md @@ -0,0 +1,110 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify platform settings. +--- + +## Command + +``` +$ vela update settings +``` + +{{% alert color="info" %}} +For more information, you can run `vela update settings --help`. +{{% /alert %}} + +## 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 + +{{% alert color="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 setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +{{% /alert %}} + +#### 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/content/reference/cli/settings/view.md b/content/reference/cli/settings/view.md new file mode 100644 index 00000000..691929e7 --- /dev/null +++ b/content/reference/cli/settings/view.md @@ -0,0 +1,58 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect platform settings. +--- + +## Command + +``` +$ vela view settings +``` + +{{% alert color="info" %}} +For more information, you can run `vela view settings --help`. +{{% /alert %}} + +## Permissions + +COMING SOON! + +## Sample + +{{% alert color="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 setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). +{{% /alert %}} + +#### 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 +```