From 1def4ff26c146109b627171377dfff10cf4e98de Mon Sep 17 00:00:00 2001 From: Kelly Merrick Date: Mon, 24 Jun 2024 17:37:14 -0500 Subject: [PATCH] feat(dashboard): add dashboard commands to cli reference (#413) --- content/reference/cli/dashboard/_index.md | 16 +++ content/reference/cli/dashboard/add.md | 100 ++++++++++++++++++ content/reference/cli/dashboard/get.md | 119 ++++++++++++++++++++++ content/reference/cli/dashboard/update.md | 108 ++++++++++++++++++++ content/reference/cli/dashboard/view.md | 93 +++++++++++++++++ 5 files changed, 436 insertions(+) create mode 100644 content/reference/cli/dashboard/_index.md create mode 100644 content/reference/cli/dashboard/add.md create mode 100644 content/reference/cli/dashboard/get.md create mode 100644 content/reference/cli/dashboard/update.md create mode 100644 content/reference/cli/dashboard/view.md diff --git a/content/reference/cli/dashboard/_index.md b/content/reference/cli/dashboard/_index.md new file mode 100644 index 000000000..bef8a900b --- /dev/null +++ b/content/reference/cli/dashboard/_index.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. + +{{% 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/dashboard/add.md b/content/reference/cli/dashboard/add.md new file mode 100644 index 000000000..8dd11aec5 --- /dev/null +++ b/content/reference/cli/dashboard/add.md @@ -0,0 +1,100 @@ +--- +title: "Add" +linkTitle: "Add" +description: > + Learn how to create a dashboard. +--- + +## Command + +``` +$ vela add dashboard +``` + +{{% alert color="info" %}} +For more information, you can run `vela add dashboard --help`. +{{% /alert %}} + +## 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` | + +{{% alert color="info" %}} +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/). +{{% /alert %}} + +## 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 +$ 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/content/reference/cli/dashboard/get.md b/content/reference/cli/dashboard/get.md new file mode 100644 index 000000000..ccb0751c5 --- /dev/null +++ b/content/reference/cli/dashboard/get.md @@ -0,0 +1,119 @@ +--- +title: "Get" +linkTitle: "Get" +description: > + Learn how to list dashboards. +--- + +## Command + +``` +$ vela get dashboard +``` + +{{% alert color="info" %}} +For more information, you can run `vela get dashboard --help`. +{{% /alert %}} + +## 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` | + +{{% alert color="info" %}} +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/). +{{% /alert %}} + +## 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 +$ 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/content/reference/cli/dashboard/update.md b/content/reference/cli/dashboard/update.md new file mode 100644 index 000000000..6cac7d98e --- /dev/null +++ b/content/reference/cli/dashboard/update.md @@ -0,0 +1,108 @@ +--- +title: "Update" +linkTitle: "Update" +description: > + Learn how to modify a dashboard. +--- + +## Command + +``` +$ vela update dashboard +``` + +{{% alert color="info" %}} +For more information, you can run `vela update dashboard --help`. +{{% /alert %}} + +## 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` | + +{{% alert color="info" %}} +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/). +{{% /alert %}} + +## 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 +$ 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/content/reference/cli/dashboard/view.md b/content/reference/cli/dashboard/view.md new file mode 100644 index 000000000..67dd0d475 --- /dev/null +++ b/content/reference/cli/dashboard/view.md @@ -0,0 +1,93 @@ +--- +title: "View" +linkTitle: "View" +description: > + Learn how to inspect a dashboard. +--- + +## Command + +``` +$ vela view dashboard +``` + +{{% alert color="info" %}} +For more information, you can run `vela view dashboard --help`. +{{% /alert %}} + +## 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` | + +{{% alert color="info" %}} +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/). +{{% /alert %}} + +## 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 +$ 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 +```