diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 6eef427da3d..348feb44f90 100644 --- 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 index b22df3ab492..510afe6f23f 100644 --- a/docs/.vitepress/sidebars.mjs +++ b/docs/.vitepress/sidebars.mjs @@ -290,8 +290,18 @@ export const guidesSidebar = [ ], }, { - text: `Workflows ${cloudBlank02Icon()} ${comingSoonBadge()}`, - link: "guides/develop/workflows", + text: `Automate ${cloudBlank02Icon()}`, + collapsed: true, + items: [ + { + text: `Continuous Integration`, + link: "guides/develop/automate/continuous-integration", + }, + { + text: `Workflows ${comingSoonBadge()}`, + 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 new file mode 100644 index 00000000000..8620f1fd7de --- /dev/null +++ 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 tuist@x.y.z + +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 tuist@x.y.z + - 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 tuist@x.y.z + - 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`. \ No newline at end of file diff --git a/docs/docs/guides/develop/workflows.md b/docs/docs/guides/develop/automate/workflows.md similarity index 72% rename from docs/docs/guides/develop/workflows.md rename to docs/docs/guides/develop/automate/workflows.md index 6a337e5be43..29f2fde858b 100644 --- a/docs/docs/guides/develop/workflows.md +++ b/docs/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 index a7422f18e47..571cd1ba08b 100644 --- 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 index 89fa4659922..e5225821a1c 100644 --- 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 index cf53d796df7..bcbf6bf14df 100644 --- 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 index 21c4b7b823b..6485d1483d4 100644 --- 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 tuist@x.y.z # 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,