fix: improve cicd docs

cicd/carlin.ts

@@ -1,7 +1,7 @@
 import { secrets } from './secrets';
 
 export default {
-  pipelines: ['main', 'tag', 'pr'],
+  pipelines: ['pr', 'main', 'tag'],
   slackWebhookUrl: secrets.slackWebhookUrl,
   sshKey: './ssh-key',
   sshUrl: '[email protected]:ttoss/carlin.git',

cicd/commands/main

@@ -1,7 +1,5 @@
 #!/bin/bash
 
-set -e
-
 yarn lerna run "build" --stream
 yarn lerna run "test" --stream
 yarn lerna version --yes

cicd/commands/pr

@@ -1,6 +1,4 @@
 #!/bin/bash
 
-set -e
-
 yarn lerna run "build" --stream
 yarn lerna run "test" --stream

cicd/commands/tag

@@ -1,7 +1,5 @@
 #!/bin/bash
 
-set -e
-
 yarn lerna run "build" --stream
 yarn lerna run "test" --stream
 yarn lerna run "deploy" --stream

packages/cli/src/deploy/cicd/cicd.template.ts

@@ -160,6 +160,9 @@ export const getRepositoryImageBuilder = () => ({
 
               // Used in case of yarn.lock is modified.
               'RUN git checkout -- yarn.lock',
+
+              // set -e stops the execution of a script if a command or pipeline has an error.
+              'RUN set -e',
             ].join('\n'),
           },
         },

packages/website/docs/commands/deploy-cicd.mdx

@@ -2,8 +2,6 @@
 title: deploy cicd
 ---
 
-<!-- {/_ <CodeBlock className="ts">{carlinCicdConfig}</CodeBlock> _/} -->
-
 import CodeBlock from '../../src/components/CodeBlock';
 import InnerHTML from '../../src/components/InnerHTML';
 import Template from '../../src/components/Template';
@@ -28,30 +26,90 @@ In other words, how can we setup a structure to execute commands and only pays f
 
 ## Creating The CI/CD Stack
 
-This section will explain how you create the CI/CD stack. We're going to create the stack with a basic configuration
-just to understand better its operation. The next section will explain each stack component with more details.
+This section will explain how you create the CI/CD stack. The following sections will explain how to configure the stack before running
+the command `carlin deploy cicd`.
 
-Before running the command `carlin deploy cicd`, we need to create some configuration with [GitHub](https://github.com).
-GitHub was chosen by us because it fits very well in our processes and it offers a great developer experience (DX).
-However, we've architected this stack to work with any Git provider, as [BitBucket](https://bitbucket.org/), but we haven't tried yet.
+### GitHub Deploy Key
 
-### Creating a SSH Key
+GitHub was chosen by us because it fits very well in our processes and it offers a great developer experience (DX).
+However, we've architected this stack to work with any Git provider, as [BitBucket](https://bitbucket.org/), but we haven't tried
+others but GitHub, so this configuration is for GitHub.
 
 1. Create a folder in which you'll save the configurations of the CI/CD in your repository, for example `cicd`.
 1. Create a SSH key following [these steps](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key).
    1. You may want to save the keys inside the folder you've created. For example: `Enter file in which to save the key (/home/your-name/.ssh/id_ed25519): ./ssh-key`
    1. Create a `.gitignore` file containing the name of the keys (`ssh-key*` in this example).
-1. Create a [deploy key](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys) on yout GitHub repository.
-
-### Creating The CI/CD Stack
-
+1. Create a [deploy key](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys) on your GitHub repository.
 1. Create a config file, for example, `carlin.yml` inside your `cicd` folder with the configuration:
 
-   ```yaml title="carlin.yml"
-   sshKey: ./ssh-key
-   sshUrl: [email protected]:USER/REPOSITORY.git
+   ```ts title="carlin.ts"
+   export default {
+     sshKey: './ssh-key', // Or the name you've chosen.
+     sshUrl: '[email protected]:USER/REPOSITORY.git',
+   };
    ```
 
+### Pipelines
+
+Currently, the CI/CD stack supports three pipelines: `pr`, `main` and `tag`. Each pipeline is triggered in a stage of the development
+flow explained above.
+
+- `pr`: This pipeline is triggered when a pull request is opened.
+- `main`: This pipeline is triggered when a new commit is pushed to the branch `main`.
+- `tag`: This pipeline is triggered when a new tag is created.
+
+The commands that will be executed should be defined in the files `commands/[pipeline]` and the pipeline must be added to the `pipelines`
+configuration file. For example, if you want to execute the commands `npm run build`, `npm run test` and `carlin deploy`
+in the `pr` pipeline, you should create the file `commands/pr` file with the following content:
+
+```sh title="commands/pr"
+#!/bin/bash
+
+npm run build
+npm run test
+carlin deploy
+```
+
+and add `pr` to `pipelines` property on the `carlin` configuration file:
+
+```ts title="carlin.ts"
+export default {
+  pipelines: ['pr'],
+};
+```
+
+The same is true if you want to add other pipelines:
+
+```ts title="carlin.ts"
+export default {
+  pipelines: ['pr', 'main', 'tag'],
+};
+```
+
+Note that you can also define specific pipelines for [differents environments](/docs/CLI#environments):
+
+```ts title="carlin.ts"
+export default {
+  pipelines: ['pr'],
+  environments: {
+    Staging: {
+      pipelines: ['main'],
+    },
+    Production: {
+      pipelines: ['tag'],
+    },
+  },
+};
+```
+
+:::note
+
+Don't forget to create the commands files for each declared pipeline.
+
+::::
+
+### Creating The CI/CD Stack
+
 1. Execute
 
    ```
@@ -62,6 +120,8 @@ However, we've architected this stack to work with any Git provider, as [BitBuck
 
    <Template json={cicdTemplate} />
 
+The next section will explain all resources created by the CI/CD stack.
+
 ## Stack Resources
 
 When deployed, the CI/CD create these resources:

packages/website/docs/commands/deploy.mdx

@@ -64,6 +64,7 @@ update or a delete is performed.
 :::caution
 
 <InnerHTML html={stackNameWarningComment} />
+
 ::::
 
 <InnerHTML html={stackNameComment} />