From 58c658f622e7b1d75e8fe03ffa0e6f53d541023c Mon Sep 17 00:00:00 2001 From: Thomas Kunwar <20840228+yathomasi@users.noreply.github.com> Date: Fri, 5 Jan 2024 20:43:16 +0545 Subject: [PATCH] update docs to reflect changes in settings page, access tokens in studio (#5064) * update docs to reflect settings changes in studio * apply feedback to account and billing documentation * update references for settings and access tokens --- content/docs/api-reference/artifacts_show.md | 6 +- .../docs/command-reference/artifacts/get.md | 5 +- content/docs/sidebar.json | 2 +- content/docs/studio/experiments.md | 4 +- content/docs/studio/model-registry.md | 5 +- content/docs/studio/rest-api.md | 15 +- .../user-guide/account-and-billing/index.md | 157 +++++++++--------- .../experiments/create-a-project.md | 2 +- .../studio/user-guide/experiments/index.md | 9 +- .../experiments/live-metrics-and-plots.md | 10 +- .../custom-gitlab-server.md | 0 .../github-app.md | 5 +- .../user-guide/git-connections/index.md | 17 ++ .../user-guide/git-integrations/index.md | 16 -- .../user-guide/model-registry/use-models.md | 7 +- redirects-list.json | 2 + 16 files changed, 140 insertions(+), 122 deletions(-) rename content/docs/studio/user-guide/{git-integrations => git-connections}/custom-gitlab-server.md (100%) rename content/docs/studio/user-guide/{git-integrations => git-connections}/github-app.md (85%) create mode 100644 content/docs/studio/user-guide/git-connections/index.md delete mode 100644 content/docs/studio/user-guide/git-integrations/index.md diff --git a/content/docs/api-reference/artifacts_show.md b/content/docs/api-reference/artifacts_show.md index 3e5a5732f6..c1f9c9671a 100644 --- a/content/docs/api-reference/artifacts_show.md +++ b/content/docs/api-reference/artifacts_show.md @@ -17,7 +17,8 @@ def artifacts_show( If you have a DVC Studio project configured with your [remote storage credentials], you may also use the DVC Studio [REST API] to programmatically access artifacts. It does not require the client to have any credentials other -than the DVC Studio [access token] and does not require DVC to be installed. +than the DVC Studio [client access token] and does not require DVC to be +installed. @@ -115,6 +116,7 @@ This example uses the returned path and Git revision in conjunction with directory. [rest api]: /doc/studio/rest-api -[access token]: /doc/studio/user-guide/account-management#studio-access-token +[client access token]: + /doc/studio/user-guide/account-and-billing#client-access-tokens [remote storage credentials]: /doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials diff --git a/content/docs/command-reference/artifacts/get.md b/content/docs/command-reference/artifacts/get.md index 880acaad20..e23839f6e5 100644 --- a/content/docs/command-reference/artifacts/get.md +++ b/content/docs/command-reference/artifacts/get.md @@ -40,7 +40,7 @@ addressed in the form `path/to/dvc.yaml:artifact_name` or `dvc artifacts get` will first try to download artifacts via the DVC Studio [REST API]. Downloading an artifact using the Studio REST API only requires a -valid DVC Studio [access token] and a Studio project configured with your +valid DVC Studio [client access token] and a Studio project configured with your [remote storage credentials]. It does not require the client to have those credentials. If you do not have a valid DVC Studio token, or the artifact is not tracked in the model registry, DVC will fall back to its typical method to get @@ -123,6 +123,7 @@ to the `dvc.yaml` file when addressing the artifact. Since we do not specify the artifact by default. [rest api]: /doc/studio/rest-api -[access token]: /doc/studio/user-guide/account-management#studio-access-token +[client access token]: + /doc/studio/user-guide/account-and-billing#client-access-tokens [remote storage credentials]: /doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json index a92df5c927..4ff1176e50 100644 --- a/content/docs/sidebar.json +++ b/content/docs/sidebar.json @@ -730,7 +730,7 @@ "children": ["billing-and-payment"] }, { - "slug": "git-integrations", + "slug": "git-connections", "children": ["github-app", "custom-gitlab-server"] }, "troubleshooting" diff --git a/content/docs/studio/experiments.md b/content/docs/studio/experiments.md index 164be7884d..c69b5f6876 100644 --- a/content/docs/studio/experiments.md +++ b/content/docs/studio/experiments.md @@ -15,8 +15,8 @@ experiments with DVC Studio: ``` - Copy your - [DVC Studio token](/doc/studio/user-guide/account-and-billing#studio-access-token) - and + [DVC Studio client access token](/doc/studio/user-guide/account-and-billing#client-access-tokens) + with Experiment operations scope, and [configure your model training environment to use the token](/doc/studio/user-guide/experiments/live-metrics-and-plots#set-up-an-access-token): ```cli diff --git a/content/docs/studio/model-registry.md b/content/docs/studio/model-registry.md index b07dd84b22..e2d571c87a 100644 --- a/content/docs/studio/model-registry.md +++ b/content/docs/studio/model-registry.md @@ -18,8 +18,9 @@ To quickly start tracking your models in the DVC Studio model registry: ``` - Copy your - [DVC Studio token](/doc/studio/user-guide/account-and-billing#studio-access-token) - and configure your model training environment to use the token: + [DVC Studio client access token](/doc/studio/user-guide/account-and-billing#client-access-tokens) + with Model registry operations scope, and configure your model training + environment to use the token: ```cli $ dvc config --global studio.token *** diff --git a/content/docs/studio/rest-api.md b/content/docs/studio/rest-api.md index 7a4e9ddcd5..7d9c1a6b8d 100644 --- a/content/docs/studio/rest-api.md +++ b/content/docs/studio/rest-api.md @@ -7,15 +7,14 @@ The API is hosted under the `/api` route on the DVC Studio server: https://studio.iterative.ai/api or https://your-domain/api in case of [self-hosted DVC Studio](/doc/studio/self-hosting/installation). -To use API, you need to generate -[DVC Studio access token](/doc/studio/user-guide/account-management#studio-access-token). +To use API, you need to generate [DVC Studio tokens] with the necessary scopes. ## Download model Get signed URL to download the model binaries for a model from the model registry. Requires the model to be stored with DVC with a S3, Azure, http or https [remote]. Note, that you need to -[set up remote cloud credentials](/doc/studio/user-guide/account-management#cloud-credentials) +[set up remote cloud credentials](/doc/studio/user-guide/account-and-billing#cloud-credentials) for DVC Studio to have rights to the signed URLs. The signed URLs expire after one hour. @@ -52,8 +51,8 @@ actually download the model. ### Example -First, you need your [DVC Studio access token]. For this example, we set it in -the `DVC_STUDIO_TOKEN` environment variable: +First, you need your [DVC Studio client access token] with Model Registry scope. +For this example, we set it in the `DVC_STUDIO_TOKEN` environment variable: ```sh export DVC_STUDIO_TOKEN= @@ -107,7 +106,7 @@ cloud credentials] in DVC Studio to where the model is stored. [remote]: /doc/user-guide/data-management/remote-storage [`dvc.yaml`]: /doc/user-guide/project-structure/dvcyaml-files -[DVC Studio access token]: - /doc/studio/user-guide/account-management#studio-access-token +[DVC Studio client access token]: + /doc/studio/user-guide/account-and-billing#client-access-tokens [set up remote cloud credentials]: - /doc/studio/user-guide/account-management#cloud-credentials + /doc/studio/user-guide/account-and-billing#cloud-credentials diff --git a/content/docs/studio/user-guide/account-and-billing/index.md b/content/docs/studio/user-guide/account-and-billing/index.md index ba7ca79244..c4e890fe8e 100644 --- a/content/docs/studio/user-guide/account-and-billing/index.md +++ b/content/docs/studio/user-guide/account-and-billing/index.md @@ -1,14 +1,19 @@ # Account Management To open your account settings, click on your user icon on the top right corner -of DVC Studio, and go to your `Profile`. You can view and update the following +of DVC Studio, and go to your `Settings`. You can view and update the following settings: -- [Personal details](#personal-details), including name, username and email - addresses -- [Security details](#security-details), including password, access token, and - cloud credentials -- [Git integrations](#git-integrations) with GitHub, GitLab and Bitbucket +- [General settings](#general-settings) + - [Profile details](#profile-details) update your name and profile picture + - [Account details](#account-details) manage your username, password, email + addresses, and delete your account +- [Git connections](#git-connections) with GitHub, GitLab and Bitbucket +- [Cloud credentials](#cloud-credentials) for data remotes +- [Teams](#teams) that you own +- [Tokens](#tokens) + - [Client access tokens](#client-access-tokens) for experiments, dataset and + model registry operations @@ -21,18 +26,28 @@ plans there and increase or decrease the number of seats in it. -## Personal details +## General settings -In your profile page, the topmost section includes your first name, last name -and profile picture. If you signed up with a GitHub, GitLab or Bitbucket -account, these details are fetched from your connected Git hosting account. +In your settings page, the general tab includes your profile and account +settings. -Your username is displayed next. This is also fetched from your connected Git -hosting account if you signed up with a GitHub, GitLab or Bitbucket account. +### Profile details -You can edit your name as well as username. +Here, you can update your first name, last name and profile picture. -### Managing email addresses +### Account details + +In the account section, your username is displayed. Here, you can also update +your username, password and email addresses. + + + +If you signed up with a GitHub, GitLab or Bitbucket account, these details are +fetched from your connected Git hosting account. + + + +#### Managing email addresses You can add multiple email addresses to a single DVC Studio account. You can login to the account with any of your verified email addresses as long as you @@ -47,64 +62,19 @@ next to the email address which you want to designate as primary. You can delete your non-primary email addresses. -## Security details - -Your password can be changed or reset from the `Account` section in your profile -page. - -### Studio access token - -DVC Studio uses access tokens to authorize [DVC] and [DVCLive] to send -experiment updates, and to authenticate you in the DVC Studio -[REST API](/doc/studio/rest-api). - -In the `Studio access token` section of your [Profile] page, you can generate a -new token as well as regenerate (replace) or delete your access token. - -The option to delete the access token is also available when you change your -password, so that you can reset all your access credentials at once. This is -handy if you suspect that your account security may have been compromised. - -### Client access tokens - -In the `Studio access token` section of your [Profile] page, you can generate -new client access tokens with specific scopes as well as delete existing access -tokens. These tokens can be used to give limited permissions to a client without -granting full access to your Studio account. - -The available scopes are: - -- `Experiment operations` - DVC uses this to share [live experiments] and to - notify [Studio](https://studio.iterative.ai/) about [pushed experiments]. -- `Dataset operations` - [Coming soon](https://cloud.dvc.ai). -- `Model registry operations` - like downloading model using - `dvc artifacts get`. - -[live experiments]: - /docs/studio/user-guide/projects-and-experiments/live-metrics-and-plots -[pushed experiments]: /docs/user-guide/experiment-management/sharing-experiment - -### Cloud credentials - -In the `Cloud Credentials` section of your [Profile] page, you can view, add and -update credentials for cloud resources. These credentials are used to -[fetch project data from data remotes](/doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials). - -To add new credentials, click `Add credentials` and select the cloud provider. -Depending on the provider, you will be asked for more details. +#### Delete account -![](https://static.iterative.ai/img/studio/s3_remote_settings_v2.png) +If you delete your account, all the projects you own and the links that you have +shared will be permanently deleted. So, click on `Delete my account` only if you +are absolutely sure that you do not need those projects or links anymore. -The credentials must have the required permissions. For -[data remotes](/doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials), -you can find more details about required permissions [here][data remote]. + -[data remote]: /doc/user-guide/data-management/remote-storage -[profile]: https://studio.iterative.ai/user/_/profile +Deleting your account in DVC Studio does not delete your Git repositories. -Finally, click `Save credentials`. + -## Git integrations +## Git Connections In this section, you can, @@ -133,17 +103,56 @@ In this section, you can, GitHub app on additional organizations or repositories, or even remove the app from organizations or repositories where you no longer need it. -## Delete account +## Cloud credentials -If you delete your account, all the projects you own and the links that you have -shared will be permanently deleted. So, click on `Delete my account` only if you -are absolutely sure that you do not need those projects or links anymore. +In this section, you can view, add and update credentials for cloud resources. +These credentials are used to +[fetch project data from data remotes](/doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials). - +To add new credentials, click `Add credentials` and select the cloud provider. +Depending on the provider, you will be asked for more details. -Deleting your account in DVC Studio does not delete your Git repositories. +![](https://static.iterative.ai/img/studio/s3_remote_settings_v2.png) - +The credentials must have the required permissions. For +[data remotes](/doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials), +you can find more details about required permissions [here][data remote]. +[data remote]: /doc/user-guide/data-management/remote-storage +[settings]: https://studio.iterative.ai/user/_/settings + +Finally, click `Save credentials`. + +## Teams + +In this section, you can view all the teams you are member of. + +Click on `select` to switch to the team's dashboard. Or, click on `manage` to go +to the team settings page and manage the team. + +To create a new team, click on `Create a team` and enter the team name. You can +invite members to the team by entering their email addresses. Find more details +[here](/doc/studio/user-guide/team-collaboration#create-a-team). + +## Tokens + +### Client access tokens + +In this tokens section of your [settings] page, you can generate new client +access tokens with specific scopes as well as delete existing access tokens. +These tokens can be used to give limited permissions to a client without +granting full access to your Studio account. + +The available scopes are: + +- `Experiment operations` - DVC uses this scope to share [live experiments] and + to notify [Studio](https://studio.iterative.ai/) about [pushed experiments]. +- `Dataset operations` - [Coming soon](https://cloud.dvc.ai). +- `Model registry operations` - like downloading model using + `dvc artifacts get`. + +[live experiments]: + /docs/studio/user-guide/projects-and-experiments/live-metrics-and-plots +[pushed experiments]: /docs/user-guide/experiment-management/sharing-experiment [dvc]: /doc [dvclive]: /doc/dvclive diff --git a/content/docs/studio/user-guide/experiments/create-a-project.md b/content/docs/studio/user-guide/experiments/create-a-project.md index 7e115c1135..2434fc5fbe 100644 --- a/content/docs/studio/user-guide/experiments/create-a-project.md +++ b/content/docs/studio/user-guide/experiments/create-a-project.md @@ -20,7 +20,7 @@ To add a new project, follow these steps. If you do not see your desired organizations or Git repositories, make sure that - [the connection to your Git server has been set up](/doc/studio/user-guide/account-and-billing#git-integrations). + [the connection to your Git server has been set up](/doc/studio/user-guide/account-and-billing#git-connections). To connect to your GitHub repositories, you must install the DVC Studio GitHub app. Refer to the section on diff --git a/content/docs/studio/user-guide/experiments/index.md b/content/docs/studio/user-guide/experiments/index.md index 13425b0102..1df02248f7 100644 --- a/content/docs/studio/user-guide/experiments/index.md +++ b/content/docs/studio/user-guide/experiments/index.md @@ -19,8 +19,9 @@ To quickly start tracking your experiments with DVC Studio: ``` - Copy your - [DVC Studio token](/doc/studio/user-guide/account-and-billing#studio-access-token) - and configure your model training environment to use the token: + [DVC Studio client access token](/doc/studio/user-guide/account-and-billing#client-access-tokens) + with Experiment operations scope, and configure your model training + environment to use the token: ```cli $ dvc config --global studio.token *** @@ -75,8 +76,8 @@ To set up, run and track This will create a `dvc.yaml` file in the Git repository. - Copy your - [DVC Studio token](/doc/studio/user-guide/account-and-billing#studio-access-token) - and + [DVC Studio client access token](/doc/studio/user-guide/account-and-billing#client-access-tokens) + with Experiment operations scope, and [configure your model training environment to use the token](/doc/studio/user-guide/experiments/live-metrics-and-plots#set-up-an-access-token): ```cli diff --git a/content/docs/studio/user-guide/experiments/live-metrics-and-plots.md b/content/docs/studio/user-guide/experiments/live-metrics-and-plots.md index fbfe176d8c..62f5b9b988 100644 --- a/content/docs/studio/user-guide/experiments/live-metrics-and-plots.md +++ b/content/docs/studio/user-guide/experiments/live-metrics-and-plots.md @@ -18,9 +18,11 @@ access tokens are rejected with an appropriate HTTP error code and error message. The access token is also used by DVC to notify DVC Studio when you push experiments using `dvc exp push`. -Once you [create your access token], pass it to your experiment. If you are -running the experiment locally, you can set the token in your [DVC config]. For -example, to set it globally for all of a user's projects: +Once you create your +[DVC Studio client access token](/doc/studio/user-guide/account-and-billing#client-access-tokens) +with Experiment operations scope, pass it to your experiment. If you are running +the experiment locally, you can set the token in your [DVC config]. For example, +to set it globally for all of a user's projects: ```cli $ dvc config --global studio.token *** @@ -143,8 +145,6 @@ An experiment can have one of the following statuses: [dvclive]: /doc/dvclive -[create your access token]: - /doc/studio/user-guide/account-and-billing#studio-access-token [push]: /doc/user-guide/experiment-management/sharing-experiments#push-experiments [dvc config]: /docs/user-guide/project-structure/configuration#studio diff --git a/content/docs/studio/user-guide/git-integrations/custom-gitlab-server.md b/content/docs/studio/user-guide/git-connections/custom-gitlab-server.md similarity index 100% rename from content/docs/studio/user-guide/git-integrations/custom-gitlab-server.md rename to content/docs/studio/user-guide/git-connections/custom-gitlab-server.md diff --git a/content/docs/studio/user-guide/git-integrations/github-app.md b/content/docs/studio/user-guide/git-connections/github-app.md similarity index 85% rename from content/docs/studio/user-guide/git-integrations/github-app.md rename to content/docs/studio/user-guide/git-connections/github-app.md index 83ecdec40d..bbb8aa1fef 100644 --- a/content/docs/studio/user-guide/git-integrations/github-app.md +++ b/content/docs/studio/user-guide/git-connections/github-app.md @@ -9,8 +9,9 @@ case, you will be prompted to configure Git integrations as shown below. ![](https://static.iterative.ai/img/studio/configure_git_integrations_v2.png) -Click on the link to `Configure Git integrations settings`. This will open the -[`Git integrations` section of your profile page](/doc/studio/user-guide/account-and-billing#git-integrations). +Click on the link to `Configure Git connections`. This will open the +[`Git connections`](/doc/studio/user-guide/account-and-billing#git-connections) +section of your profile page. ![](https://static.iterative.ai/img/studio/configure_github.png) diff --git a/content/docs/studio/user-guide/git-connections/index.md b/content/docs/studio/user-guide/git-connections/index.md new file mode 100644 index 0000000000..69dae52703 --- /dev/null +++ b/content/docs/studio/user-guide/git-connections/index.md @@ -0,0 +1,17 @@ +# Git connections + +If you sign up to use DVC Studio using your GitHub, GitLab or Bitbucket account, +connection with that Git account gets created during sign up. If you sign in +with your email address, you will need to +[set up the Git connections](/doc/studio/user-guide/account-and-billing#git-connections). +This is also needed if you want to connect to more than one Git provider. + +To **connect to your GitHub repositories**, you must +[install the DVC Studio GitHub app](/doc/studio/user-guide/git-connections/github-app). + +To **connect to a self-hosted GitLab server**, you should create a team and +[set up the GitLab server connection](/doc/studio/user-guide/git-connections/custom-gitlab-server). + +You can **remove a Git connection** from your account by visiting the +[Git connections section](/doc/studio/user-guide/account-and-billing#git-connections) +of your profile page. diff --git a/content/docs/studio/user-guide/git-integrations/index.md b/content/docs/studio/user-guide/git-integrations/index.md deleted file mode 100644 index d99d373945..0000000000 --- a/content/docs/studio/user-guide/git-integrations/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Git integrations - -If you sign up to use DVC Studio using your GitHub, GitLab or Bitbucket account, -integration with that Git account gets created during sign up. If you sign in -with your email address, you will need to -[set up the Git integrations](/doc/studio/user-guide/account-and-billing#git-integrations). -This is also needed if you want to connect to more than one Git provider. - -To **connect to your GitHub repositories**, you must -[install the DVC Studio GitHub app](/doc/studio/user-guide/git-integrations/github-app). - -To **connect to a self-hosted GitLab server**, you should create a team and -[set up the GitLab server connection](/doc/studio/user-guide/git-integrations/custom-gitlab-server). - -You can **remove a Git integration** from your account by visiting the -[Git integrations sections of your profile page](/doc/studio/user-guide/account-and-billing#git-integrations). diff --git a/content/docs/studio/user-guide/model-registry/use-models.md b/content/docs/studio/user-guide/model-registry/use-models.md index f83bb9dbba..2c9f804e3a 100644 --- a/content/docs/studio/user-guide/model-registry/use-models.md +++ b/content/docs/studio/user-guide/model-registry/use-models.md @@ -15,7 +15,8 @@ Prerequisites: - Model stored with DVC with S3, Azure, http or https [remote]. - The DVC Studio project you like to download your model from needs access to your [remote storage credentials]. -- Access to your [DVC Studio Access token]. +- Access to your [DVC Studio client access token] with Model registry operations + scope. Without these prerequisites, you can still [download a model artifact with DVC]. However, it can be easier to use the DVC Studio API since you only need to have @@ -25,8 +26,8 @@ Git repository, and you do not need to install DVC. [remote]: /doc/user-guide/data-management/remote-storage [remote storage credentials]: /doc/studio/user-guide/experiments/configure-a-project#data-remotes--cloud-storage-credentials -[DVC Studio Access token]: - /doc/studio/user-guide/account-management#studio-access-token +[DVC Studio client access token]: + /doc/studio/user-guide/account-and-billing#client-access-tokens [download a model artifact with DVC]: /doc/command-reference/artifacts/get [REST API]: /doc/studio/rest-api [Python API]: /doc/api-reference diff --git a/redirects-list.json b/redirects-list.json index ca1fed4caa..63e4246603 100644 --- a/redirects-list.json +++ b/redirects-list.json @@ -126,6 +126,8 @@ "^/doc/studio/user-guide/teams$ /doc/studio/user-guide/team-collaboration/teams", "^/doc/studio/user-guide/change-team-plan-and-size$ /doc/studio/user-guide/team-collaboration/change-team-plan-and-size", + "^/doc/studio/user-guide/git-integrations(/.*)?$ /doc/studio/user-guide/git-connections$1", + "^/doc/studio/get-started$ /doc/studio/experiments", "^/doc/studio/user-guide/projects-and-experiments/what-is-a-project$ /doc/studio/user-guide/experiments", "^/doc/studio/user-guide/projects-and-experiments(/.*)?$ /doc/studio/user-guide/experiments$1",