feat: add a new 'Automate | Continuous Integration' section to the do…

…cumentation (tuist#6631) * Add a new 'Develop | Integrate' documentation section * Document how to authenticate CI requests * Update docs/docs/guides/develop/integrate.md Co-authored-by: James Sherlock <[email protected]> * Rename 'integrate' to 'automate' * Update docs/docs/guides/develop/automate/continuous-integration.md Co-authored-by: Marek Fořt <[email protected]> --------- Co-authored-by: James Sherlock <[email protected]> Co-authored-by: Marek Fořt <[email protected]>
runtastic · Aug 21, 2024 · f5847fa · f5847fa
1 parent b8aaf84
commit f5847fa
Show file tree

Hide file tree

Showing 8 changed files with 147 additions and 65 deletions.
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
@@ -108,6 +108,7 @@ export default defineConfig({
 /cloud/on-premise/metrics /guides/dashboard/on-premise/metrics 301
 /reference/project-description/* /references/project-description/:splat 301
 /reference/examples/* /references/examples/:splat 301
+/guides/develop/workflows /guides/develop/continuous-integration/workflows 301
 
 /documentation/tuist/* / 301
     `;

diff --git a/docs/.vitepress/sidebars.mjs b/docs/.vitepress/sidebars.mjs
@@ -290,8 +290,18 @@ export const guidesSidebar = [
         ],
       },
       {
-        text: `<span style="display: flex; flex-direction: row; align-items: center; gap: 7px;">Workflows ${cloudBlank02Icon()} ${comingSoonBadge()}</span>`,
-        link: "guides/develop/workflows",
+        text: `<span style="display: flex; flex-direction: row; align-items: center; gap: 7px;">Automate ${cloudBlank02Icon()}</span>`,
+        collapsed: true,
+        items: [
+          {
+            text: `Continuous Integration`,
+            link: "guides/develop/automate/continuous-integration",
+          },
+          {
+            text: `<span style="display: flex; flex-direction: row; align-items: center; gap: 7px;">Workflows ${comingSoonBadge()}</span>`,
+            link: "guides/develop/automate/workflows",
+          },
+        ],
       },
     ],
   },

diff --git a/docs/docs/guides/develop/automate/continuous-integration.md b/docs/docs/guides/develop/automate/continuous-integration.md
@@ -0,0 +1,129 @@
+---
+title: Continuous Integration (CI)
+titleTemplate: ":title | Develop | Tuist"
+description: Learn how to use Tuist in your CI workflows.
+---
+
+# Continuous Integration (CI)
+
+You can use Tuist in [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) environments. The following sections provide examples of how to do this on different CI platforms.
+
+## Examples
+
+To run Tuist commands in your CI workflows, you’ll need to install it in your CI environment.
+
+### Xcode Cloud
+
+In [Xcode Cloud](https://developer.apple.com/xcode-cloud/), which uses Xcode projects as the source of truth, you'll need to add a [post-clone](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts#Create-a-custom-build-script) script to install Tuist and run the commands you need, for example `tuist generate`:
+
+:::code-group
+
+```bash [Mise]
+#!/bin/sh
+curl https://mise.jdx.dev/install.sh | sh
+mise install # Installs the version from .mise.toml
+
+# Runs the version of Tuist indicated in the .mise.toml file
+mise x tuist generate
+```
+```bash [Homebrew]
+#!/bin/sh
+brew install --formula [email protected]
+
+tuist generate
+```
+:::
+### Codemagic
+
+In [Codemagic](https://codemagic.io), you can add an additional step to your workflow to install Tuist:
+
+::: code-group
+```yaml [Mise]
+workflows:
+  lint:
+    name: Build
+    max_build_duration: 30
+    environment:
+      xcode: 15.0.1
+    scripts:
+      - name: Install Mise
+        script: |
+          curl https://mise.jdx.dev/install.sh | sh
+          mise install # Installs the version from .mise.toml
+      - name: Build
+        script: mise x tuist build
+```
+```yaml [Homebrew]
+workflows:
+  lint:
+    name: Build
+    max_build_duration: 30
+    environment:
+      xcode: 15.0.1
+    scripts:
+      - name: Install Tuist
+        script: |
+          brew install --formula [email protected]
+      - name: Build
+        script: tuist build
+```
+:::
+
+### GitHub Actions
+
+On [GitHub Actions](https://docs.github.com/en/actions) you can an additional step to install Tuist, and in the case of managing the installation of Mise, you can use the [mise-action](https://github.com/jdx/mise-action), which abstracts the installation of Mise and Tuist:
+
+::: code-group
+```yaml [Mise]
+name: Build Application
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: jdx/mise-action@v2
+      - run: tuist build
+```
+```yaml [Homebrew]
+name: test
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+jobs:
+  lint:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: brew install --formula [email protected]
+      - run: tuist build
+```
+:::
+
+::: tip
+We recommend using `mise use --pin` in your Tuist projects to pin the version of Tuist across environments. The command will create a `.tool-versions` file containing the version of Tuist.
+:::
+
+## Authentication
+
+When using server-side features such as [cache](/guides/develop/build/cache), you'll need a way to authenticate requests going from your CI workflows to the server. For that, you can generate a project-scoped token by running the following command:
+
+```bash
+tuist project tokens create my-handle/MyApp
+```
+
+The command will generate a token for the project with full handle `my-account/my-project`. Set the value to the environment variable 
+`TUIST_CONFIG_TOKEN` in your CI environment ensuring it's configured as a secret so it's not exposed.
+
+> [!IMPORTANT] CI ENVIRONMENT DETECTION
+> Tuist only uses the token when it detects it's running on a CI environment. If your CI environment is not detected, you can force the token usage by setting the environment variable `CI` to `1`.
diff --git a/docs/docs/guides/develop/workflows.md → ...docs/guides/develop/automate/workflows.md b/docs/docs/guides/develop/workflows.md → ...docs/guides/develop/automate/workflows.md
@@ -1,5 +1,6 @@
 ---
-title: tuist workflows
+title: Workflows
+titleTemplate: ":title | Integrate | Develop | Tuist"
 description: Integrate your changes through workflows.
 ---
 

diff --git a/docs/docs/guides/develop/build.md b/docs/docs/guides/develop/build.md
@@ -1,5 +1,6 @@
 ---
 title: Build
+titleTemplate: ":title | Develop | Tuist"
 description: Learn how to use Tuist to build your projects efficiently.
 ---
 

diff --git a/docs/docs/guides/develop/projects.md b/docs/docs/guides/develop/projects.md
@@ -1,5 +1,6 @@
 ---
 title: Projects
+titleTemplate: ":title | Develop | Tuist"
 description: Learn about Tuist's DSL for defining Xcode projects.
 ---
 

diff --git a/docs/docs/guides/develop/test.md b/docs/docs/guides/develop/test.md
@@ -1,5 +1,6 @@
 ---
 title: tuist test
+titleTemplate: ":title | Develop | Tuist"
 description: Learn how to run tests efficiently with Tuist.
 ---
 

diff --git a/docs/docs/guides/quick-start/install-tuist.md b/docs/docs/guides/quick-start/install-tuist.md
@@ -36,68 +36,6 @@ mise use -g [email protected]       # Use tuist-x.y.z as the global default
 mise use -g tuist@system      # Use the system's tuist as the global default
 ```
 
-#### Continuous integration
-
-If you are using Tuist in a continuous integration environment, the following sections show how to install Tuist in the most common ones:
-
-##### Xcode Cloud
-
-You'll need a [post-clone](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts#Create-a-custom-build-script) script that installs Mise and Tuist:
-
-```bash
-#!/bin/sh
-curl https://mise.jdx.dev/install.sh | sh
-mise install # Installs the version from .mise.toml
-
-# Runs the version of Tuist indicated in the .mise.toml file
-mise x tuist generate
-```
-
-##### Codemagic
-
-To install and use Mise and Tuist in [Codemagic](https://codemagic.io), you can add an additional step to your workflow, and run Tuist through `mise x tuist` to ensure that the right version is used:
-
-```yaml
-workflows:
-  lint:
-    name: Build
-    max_build_duration: 30
-    environment:
-      xcode: 15.0.1
-    scripts:
-      - name: Install Mise
-        script: |
-          curl https://mise.jdx.dev/install.sh | sh
-          mise install # Installs the version from .mise.toml
-      - name: Build
-        script: mise x tuist build
-```
-
-##### GitHub Actions
-
-On GitHub Actions you can use the [mise-action](https://github.com/jdx/mise-action), which abstracts the installation of Mise and Tuist and the configuration of the environment:
-
-```yaml
-name: test
-on:
-  pull_request:
-    branches:
-      - main
-  push:
-    branches:
-      - main
-jobs:
-  lint:
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: jdx/mise-action@v2
-```
-
-::: tip
-We recommend using `mise use --pin` in your Tuist projects to pin the version of Tuist across environments. The command will create a `.tool-versions` file containing the version of Tuist.
-:::
-
 ### Alternative: [Homebrew](https://brew.sh)
 
 If version pinning across environments is not a concern for you,