docs(cicd): review secrets

docs/docs/ci-cd-automation/github-actions-pipeline-with-secrets.mdx

@@ -2,7 +2,7 @@
 id: github-actions-pipeline-with-secrets
 title: Github Actions Pipeline with Secrets
 description: Quick start how to configure one repository to use Tracetest and Github Action with Secrets to run trace-based tests
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -23,17 +23,18 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_T
 
 ## Running trace-based test in Github Actions with Secrets
 
-When creating testing CI scripts in Github, sometimes you need to use sensitive information, like passwords and API Keys. To keep this information safe, Github provides a feature called [Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). Secrets are encrypted environment variables that you create in a repository and are available to use in your workflows.
+When creating CI test scripts in GitHub, you sometimes need to use sensitive information, like passwords and API Keys. To keep this information safe, GitHub provides a feature called [Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). Secrets are encrypted environment variables that you create in a repository and are available to use in your workflows.
 
-On this example, you will see how to configure one repository to use Tracetest and Github Action with Secrets to run trace-based tests, keeping your sensitive information safe.
+In this example, you will see how to configure a repository to use Tracetest and Github Actions with Secrets to run trace-based tests, keeping your sensitive information safe.
 
-Let's start by using a mini Payment ecosystem with 4 APIs that work together to emulate a Payment system. These APIs are:
-- a **Gateway API** that is user-facing API that receives payment orders, protected with Basic Auth
-- a **Payment Executor API** that executes a payment order after analyzing the customer profile
-- a **Risk Analysis API** that analyze user profile to understand its score
-- a **Wallet API** that retains data about the Wallet balance of each user
+Let's start by using a mini Payment ecosystem with 4 APIs that work together to emulate a Payment system.
 
-These APIs are instrumented with [OpenTelemetry SDKs](https://opentelemetry.io/docs/languages/) and send data to [Jaeger](https://www.jaegertracing.io/) via the [OTel Collector](https://opentelemetry.io/docs/collector/).
+- **Gateway API**: User-facing API that receives payment orders, protected with Basic Auth.
+- **Payment Executor API**: Executes a payment order after analyzing the customer profile.
+- **Risk Analysis API**: Analyzes a user profile to understand its score.
+- **Wallet API**: Retains data about the Wallet balance of each user.
+
+These APIs are instrumented with [OpenTelemetry SDKs](https://opentelemetry.io/docs/languages/) and send data to [Jaeger](https://www.jaegertracing.io/) via the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/).
 
 ```mermaid
 flowchart LR
@@ -57,21 +58,29 @@ flowchart LR
 
 Each one of these APIs has their code specified inside our source code on GitHub ([here](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets)) inside the `services` folder.
 
-To see more details about the code of each API, you can check the following link: https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets
+:::info
+[View the full example code of each API on GitHub, here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-with-github-action-and-secrets)
+:::
 
 You can run them together using Docker Compose along with a Tracetest Agent, that we will use soon to test these services, with the following command:
 
-```sh
+```bash
 git clone [email protected]:kubeshop/tracetest.git
 cd ./tracetest/examples/tracetest-with-github-action-and-secrets
 TRACETEST_API_KEY=<your-agent-key> docker compose up
 ```
 
-To run a test, you need execute an API call to the Gateway API, that is protected with Basic Auth. On this tutorial, you will use a Github Secret to store the Basic Auth credentials and use it in our Github Action workflow by adding it to a [VariableSet](/concepts/variable-sets.mdx) as a secret.
+To run a test, you need execute an API call against the Gateway API. It's protected with Basic Auth.
+
+In this tutorial, you will use a Github Secret to store the Basic Auth credentials and use it in our Github Action workflow by adding it to a [VariableSet](/concepts/variable-sets.mdx) as a secret.
+
+## Creating a GitHub Actions Workflow
 
-### Creating a Github Actions Workflow
+To test this recipe, create a repository in your machine, add it to GitHub, and run the workflow. 
 
-To test this recipe, let's create repository in your machine, add it to Github and run the workflow. First of all, you need to create a new folder on your machine to store the service code and the repository code. You can do this by running the following commands:
+### Creating the API Services GitHub Repo
+
+First of all, you need to create a new folder on your machine to store the service code and the repository code. You can do this by running the following commands:
 
 ```sh
 # sandbox folder to store our files
@@ -82,7 +91,7 @@ mkdir my-repository
 cd ./my-repository
 ```
 
-Now, we will copy the code of the Payment Ecosystem to this repository. You can do this by running the following commands:
+Now copy the code of the Payment Ecosystem to this repository. You can do this by running the following commands:
 
 ```sh
 cd ..
@@ -100,7 +109,7 @@ git add .
 git commit -m "Initial commit"
 ```
 
-Then, [create a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories#create-a-repository) on Github and perform the commands below:
+Then, [create a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories#create-a-repository) on GitHub and perform the commands below:
 
 :::note
 Remember to replace `<your-github-user>` and `<your-github-name>` with your Github user and the name of the repository you created.
@@ -111,14 +120,17 @@ git remote add origin https://github.com/<your-github-user>/<your-github-name>.g
 git push origin main
 ```
 
-After that, you need to configure a new environment on [Tracetest](http://app.tracetest.io) with [these instructions](/concepts/environments.mdx) and generate an environment token for it ([here](/concepts/environment-tokens.mdx)). Remember to store the API Key generated to the agent and the environment token, they will be used on next step.
+After that, you need to configure a new environment on [Tracetest](http://app.tracetest.io) with [these instructions](/concepts/environments.mdx) and generate an environment token for it ([here](/concepts/environment-tokens.mdx)). Remember to store the API Key generated for the Tracetest Agent and the environment token as they will be used on next step.
 
-One you have these data, you need to register three secrets on your Github repository using [these instructions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository):
+You need to register three secrets in your GitHub repository using [these instructions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository):
 - `TRACETEST_API_KEY`: that is the API key used by your [agent](/concepts/agent.mdx) to connect to Tracetest
-- `TRACETEST_CLI_TOKEN`: an environment token used by the CI to run a test
+- `TRACETEST_CLI_TOKEN`: an [environment token](/concepts/environment-tokens) used by the CI to run a test
 - `API_SECRET_PASSWORD`: the password used to authenticate on the Gateway API. For demo purposes, its value is `supersecret`.
 
-Now that you have the repository set, let's create a new Github Actions workflow file on your repository. First, create a new file on the `.github/workflows` folder with the following content:
+
+### Creating the GitHub Actions Workflow
+
+Now that you have the repository set, let's create a new Github Actions workflow file in your repository. First, create a new file in the `.github/workflows` folder with the following content:
 
 ```yaml
 name: Run trace-based tests
@@ -146,9 +158,9 @@ jobs:
       # more steps to add
 ```
 
-This file defines a workflow that runs on every push to the `main` branch and can be manually triggered via the Actions tab on Github. It also defines an environment variable `TRACETEST_API_KEY` that is set to the value of the secret `TRACETEST_API_KEY`, that will be used by the Tracetest Agent defined inside our `docker-compose.yml` file and also adds the first step, that checks out the repository code into the CI container.
+This file defines a workflow that runs on every push to the `main` branch and can be manually triggered via the Actions tab on GitHub. It also defines an environment variable `TRACETEST_API_KEY` that is set to the value of the secret `TRACETEST_API_KEY`. This value will be used by the Tracetest Agent defined inside our `docker-compose.yml` file. The file also adds the first step that checks out the repository code into the CI container.
 
-The next step that you will add is to install the Tracetest CLI on the CI container with the [Tracetest Github Action](https://github.com/kubeshop/tracetest-github-action) and configure the CLI. You can do this by adding the following step:
+The next step that you will add is to install the Tracetest CLI in the CI container with the [Tracetest Github Action](https://github.com/kubeshop/tracetest-github-action) and configure the CLI. You can do this by adding the following step:
 
 ```yaml
 # ...
@@ -163,7 +175,7 @@ The next step that you will add is to install the Tracetest CLI on the CI contai
       # more steps to add
 ```
 
-Then, the next following two steps will start the APIs locally using Docker Compose and will configure Tracetest Agent to read traces from the Jaeger instance running inside of the docker compose network:
+Then, the two following steps will start the APIs locally using Docker Compose and configure Tracetest Agent to read traces from the Jaeger instance running inside of the Docker Compose network:
 
 ```yaml
 # ...
@@ -183,14 +195,14 @@ Then, the next following two steps will start the APIs locally using Docker Comp
 
 ```
 
-Now, you will setup a [VariableSet](/concepts/variable-sets.mdx) with the id `tracetesting-vars` that will have all variables used in your test context, including the `API_SECRET_PASSWORD` secret. This will make Tracetest understand that this variable is a secret and should not be presented on the UI and CLI outputs. You can do this by adding the following step to the workflow file:
+Now, you will set up a [VariableSet](/concepts/variable-sets) with the id `tracetesting-vars` that will have all variables used in your test context, including the `API_SECRET_PASSWORD` secret. This will make Tracetest understand that this variable is a secret and should not be presented on the UI and CLI outputs. You can do this by adding the following step to the workflow file:
 
 ```yaml
 # ...
     steps:
       # previous steps ...
 
-      - name: Inject secrets as a variable set on Tracetest
+      - name: Inject secrets as a variable set in Tracetest
         run: |
           cat << EOF > vars.yaml
           type: VariableSet
@@ -211,7 +223,7 @@ Now, you will setup a [VariableSet](/concepts/variable-sets.mdx) with the id `tr
       # more steps to add
 ```
 
-Finally, you will run the test using the Tracetest CLI, passing the `tracetesting-vars` VariableSet on `--vars` argumen and the test file `trace-based-test.yaml` that contains the test definition. You can do this by adding the following step to the workflow file:
+Finally, you will run the test using the Tracetest CLI, passing the `tracetesting-vars` Variable Set with the `--vars` argument and the test file `trace-based-test.yaml` that contains the test definition. You can do this by adding the following step to the workflow file:
 
 ```yaml
 # ...
@@ -225,7 +237,7 @@ Finally, you will run the test using the Tracetest CLI, passing the `tracetestin
       # more steps to add
 ```
 
-And now its done. You can run the test by pushing a new commit to the `main` branch with:
+You can run the test by pushing a new commit to the `main` branch with:
 
 ```sh
 # assuming that you are on "my-repository" folder
@@ -235,17 +247,19 @@ git commit -m "Add Tracetest Github Action workflow"
 git push origin main
 ```
 
-After a while, you can go to the "Actions" on Github and see the workflow running, as shown below:
+After a while, you can go to the "Actions" on Github and see the workflow running, as shown below.
 
 ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-screenshot_xb2bwj.png)
 
+Drill down to see the jobs contained in this workflow.
+
 ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-steps_ji02ev.png)
 
-Then, you can see the execution of this workflow:
+You can also see the execution of this workflow.
 
 ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1717457464/docs/github-action-running-step_w9supy.png)
 
-Once it is finished, you can also see the results of the test on the Tracetest UI, as shown logs or by going to your environment on [app.tracetest.io](https://app.tracetest.io) and clicking on "Runs".
+Once it's finished, you can see the results of the test in the Tracetest Web UI by going to your environment on [app.tracetest.io](https://app.tracetest.io) and clicking on "Runs".
 
 ## Learn More