From 06efc52564b85c638f9bcbc47909e6ee6cc75be0 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Tue, 21 Nov 2023 16:55:34 +0200 Subject: [PATCH] Update the docs with the quickstart command (#1707) Signed-off-by: Radoslav Dimitrov --- docs/docs/getting_started/enroll_provider.md | 38 +++++++++++ docs/docs/getting_started/first_profile.md | 2 +- docs/docs/getting_started/login.md | 31 +-------- docs/docs/getting_started/quickstart.md | 67 ++++++++++++++++++++ docs/docs/getting_started/register_repos.md | 2 +- 5 files changed, 110 insertions(+), 30 deletions(-) create mode 100644 docs/docs/getting_started/enroll_provider.md create mode 100644 docs/docs/getting_started/quickstart.md diff --git a/docs/docs/getting_started/enroll_provider.md b/docs/docs/getting_started/enroll_provider.md new file mode 100644 index 0000000000..2d12928e5b --- /dev/null +++ b/docs/docs/getting_started/enroll_provider.md @@ -0,0 +1,38 @@ +--- +title: Enrolling a Provider +sidebar_position: 40 +--- + +# Enrolling a Provider + +Once you have authenticated to Minder, you'll want to enroll your GitHub credentials to allow Minder to manage your GitHub repositories. In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner. + +## Prerequisites + +* A running Minder server, including a running KeyCloak installation +* A GitHub account +* [The `minder` CLI application](./install_cli.md) +* [Logged in to Minder server](./login.md) + +## Enrolling the GitHub Provider + +To enroll your GitHub credentials in your Minder account, run: + +```bash +minder provider enroll --provider github +``` + +A browser session will open, and you will be prompted to login to your GitHub account. + +![Enrollment screenshot](./enroll-screenshot.png) + +Once you have granted Minder access, you will be redirected back, and the user will be enrolled. The `minder` CLI application will report the session is complete. + +When enrolling an organization, use the `--owner` flag of the `minder provider enroll` command to specify the organization name: +```bash +minder provider enroll --provider github --owner test-org +``` +The `--owner` flag is not required when enrolling repositories from your personal account. + +Note: If you are enrolling an organization, the account you use to enroll must be an Owner in the organization +or an Admin on the repositories you will be registering. diff --git a/docs/docs/getting_started/first_profile.md b/docs/docs/getting_started/first_profile.md index 1e4a9b551d..0b7a1603f4 100644 --- a/docs/docs/getting_started/first_profile.md +++ b/docs/docs/getting_started/first_profile.md @@ -1,6 +1,6 @@ --- title: Creating your first profile -sidebar_position: 40 +sidebar_position: 60 --- # Creating your first profile diff --git a/docs/docs/getting_started/login.md b/docs/docs/getting_started/login.md index 016cd176c0..10588255e7 100644 --- a/docs/docs/getting_started/login.md +++ b/docs/docs/getting_started/login.md @@ -1,9 +1,9 @@ --- title: Logging in to Minder -sidebar_position: 20 +sidebar_position: 30 --- -# Logging in and Enrolling a Provider +# Logging in to Minder Minder consists of a client-side CLI tool and a server-side component. The server-side component runs as a multi-user service. In order to use Minder to manage repositories and artifacts, you need to log in, which will automatically create an account. @@ -51,29 +51,4 @@ Your web browser will be opened to log in to Keycloak, and then a banner will b Your access credentials have been saved to ~/.config/minder/credentials.json ``` -Once you have logged in, you'll want to [enroll your GitHub credentials in Minder so that it can act on your behalf](#enrolling-the-github-provider). - -## Enrolling the GitHub Provider - -Once you have authenticated to Minder, you'll want to enroll your GitHub credentials to allow Minder to manage your GitHub repositories. In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner. - -To enroll your GitHub credentials in your Minder account, run: - -```bash -minder provider enroll --provider github -``` - -A browser session will open, and you will be prompted to login to your GitHub account. - -![Enrollment screenshot](./enroll-screenshot.png) - -Once you have granted Minder access, you will be redirected back, and the user will be enrolled. The `minder` CLI application will report the session is complete. - -When enrolling an organization, use the `--owner` flag of the `minder provider enroll` command to specify the organization name: -```bash -minder provider enroll --provider github --owner test-org -``` -The `--owner` flag is not required when enrolling repositories from your personal account. - -Note: If you are enrolling an organization, the account you use to enroll must be an Owner in the organization -or an Admin on the repositories you will be registering. \ No newline at end of file +Once you have logged in, you'll want to [enroll your GitHub credentials in Minder so that it can act on your behalf](./enroll_provider.md). diff --git a/docs/docs/getting_started/quickstart.md b/docs/docs/getting_started/quickstart.md new file mode 100644 index 0000000000..4c32af1cf4 --- /dev/null +++ b/docs/docs/getting_started/quickstart.md @@ -0,0 +1,67 @@ +--- +title: Quickstart with Minder (< 1 min) +sidebar_position: 20 +--- + +# Quickstart with Minder (< 1 min) + +Minder provides a "happy path" that guides you through the process of creating your first profile in Minder. In just a few seconds, you will register your repositories and enable secret scanning protection for all of them! + +## Prerequisites + +* A running Minder server, including a running KeyCloak installation +* A GitHub account +* [The `minder` CLI application](./install_cli.md) +* [Logged in to Minder server](./login.md) + +## Quickstart + +Now that you have installed your minder cli and have logged in to your Minder server, you can start using Minder! + +Minder has a `quickstart` command which guides you through the process of creating your first profile. +In just a few seconds, you will register your repositories and enable secret scanning protection for all of them. +To do so, run: + +```bash +minder quickstart +``` + +This will prompt you to enroll your provider, select the repositories you'd like, create the `secret_scanning` +rule type and create a profile which enables secret scanning for the selected repositories. + +To see the status of your profile, run: + +```bash +minder profile_status list --profile quickstart-profile --detailed +``` + +You should see the overall profile status and a detailed view of the rule evaluation statuses for each of your registered repositories. + +Minder will continue to keep track of your repositories and will ensure to fix any drifts from the desired state by +using the `remediate` feature or alert you, if needed, using the `alert` feature. + +Congratulations! 🎉 You've now successfully created your first profile! + +## What's next? + +You can now continue to explore Minder's features by adding or removing more repositories, create more profiles with +various rules, and much more. There's a lot more to Minder than just secret scanning. + +The `secret_scanning` rule is just one of the many rule types that Minder supports. + +You can see the full list of ready-to-use rules and profiles +maintained by Minder's team here - [stacklok/minder-rules-and-profiles](https://github.com/stacklok/minder-rules-and-profiles). + +In case there's something you don't find there yet, Minder is designed to be extensible. +This allows for users to create their own custom rule types and profiles and ensure the specifics of their security +posture are attested to. + +Now that you have everything set up, you can continue to run `minder` commands against the public instance of Minder +where you can manage your registered repositories, create profiles, rules and much more, so you can ensure your repositories are +configured consistently and securely. + +For more information about `minder`, see: +* `minder` CLI commands - [Docs](https://minder-docs.stacklok.dev/ref/cli/minder). +* `minder` REST API Documentation - [Docs](https://minder-docs.stacklok.dev/ref/api). +* `minder` rules and profiles maintained by Minder's team - [GitHub](https://github.com/stacklok/minder-rules-and-profiles). +* Minder documentation - [Docs](https://minder-docs.stacklok.dev). diff --git a/docs/docs/getting_started/register_repos.md b/docs/docs/getting_started/register_repos.md index 137d42cdac..2f51b1d5b1 100644 --- a/docs/docs/getting_started/register_repos.md +++ b/docs/docs/getting_started/register_repos.md @@ -1,6 +1,6 @@ --- title: Register Repositories -sidebar_position: 30 +sidebar_position: 50 --- ## Prerequisites