From f2a37ffdcd8f9f6a7c6eaffda3258780db27f09a Mon Sep 17 00:00:00 2001
From: Francesco Francomano <silversoulKali@gmail.com>
Date: Thu, 18 Apr 2024 11:21:50 +0200
Subject: [PATCH] docs: improve documentation * Add '--auth-name' flag in the
 'Context set' paragraph; * Add example of deploy in a CD pipeline.

---
 docs/30_commands.md |  6 ++++++
 docs/40_examples.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/docs/30_commands.md b/docs/30_commands.md
index 0197609a..3a80409d 100644
--- a/docs/30_commands.md
+++ b/docs/30_commands.md
@@ -37,6 +37,7 @@ miactl context set CONTEXT [flags]
 
 Available flags for the command:
 
+- `--auth-name`, to set the name of the authentication to use (discover more on the [dedicated documentation section](#auth))
 - `--endpoint`, to set the Console endpoint
 - `--certificate-authority`, to provide the path to a custom CA certificate
 - `--insecure-skip-tls-verify`, to disallow the check the validity of the certificate of the remote endpoint
@@ -44,6 +45,11 @@ Available flags for the command:
 - `--project-id`, to set the ID of the desired Project
 - `--environment`, to set the environment scope for the command
 
+
+:::warning
+If you want to use `miactl` with a _Service Account_, **remember to specify** the  `--auth-name` flag, otherwise _miactl_ will try to perform a _User Login_, opening the browser for authentication the user.
+:::
+
 ### use
 
 The `context use` subcommand allows you to select an existing context as the current one.
diff --git a/docs/40_examples.md b/docs/40_examples.md
index dd30c319..695861cd 100644
--- a/docs/40_examples.md
+++ b/docs/40_examples.md
@@ -69,3 +69,48 @@ You can customize the way your Project is deployed:
 ```sh
 miactl deploy development --no-semver --revision tags/v1.0.0
 ```
+
+## Deploy Project using a service account from a CD pipeline
+
+The commands are the same used above in the [Deploy Project](#deploy-project) section, but you need to use a _Service Account_ for that.
+If you don't know how to create a _Service Account_, read the [dedicated documentation](/docs/development_suite/identity-and-access-management/manage-service-accounts).
+
+After creating the service account, you must create the `auth` on the `miactl` running the following command:
+
+```sh
+miactl context auth <miactl-auth-name> --client-id <sa-client-id> --client-secret <sa-client-secret>
+```
+
+Now you can set the context and, more important, **you must specify the auth name to be used**:
+
+```sh
+miactl context set <my-context-name> --endpoint https://console.private --company-id <my-company-id> --project-id <my-project-id> --auth-name <miactl-auth-name>
+```
+
+After that, just use the context:
+
+```sh
+miactl context use <my-context-name>
+```
+
+and deploy the pipeline:
+
+```sh
+miactl deploy development --no-semver --revision main
+```
+
+Finally, you can group the commands above and run them inside a pipeline, e.g. a GitLab pipeline:
+
+```yaml
+# Insert that after your pipeline stages
+delivery:
+    stage: deploy
+    image: ghcr.io/mia-platform/miactl:v0.12.2
+
+    script:
+      - miactl version
+      - miactl context auth deployer-sa --client-id sa-client-id --client-secret sa-super-secret
+      - miactl context set my-private-console --endpoint https://console.private --company-id id-of-my-company --project-id id-of-my-project --auth-name deployer-sa
+      - miactl use my-private-console
+      - miactl deploy DEV --no-semver --deploy-type smart_deploy --revision main
+```