DOCSEARCHbyAlgolia
Submit Docs

Tuist Documentation

repository·main·Indexed 26 days ago

https://github.com/tuist/tuist

A virtual platform team for Swift app developers providing tools to manage Xcode projects, speed up builds via caching, and optimize testing and app bundles. Includes documentation for the Cache Service, codebase search service, Grafana metrics data source, and CloudNativePG infrastructure configuration.

Tokens
188.5K
Snippets
548
Records
1.2K
Agent score
90%

What's inside Tuist

  1. Overview of Tuist solutions

    main

    Tuist provides several integrated solutions for Swift app development:

    • Generated projects: Makes Xcode projects more accessible and easier to manage.
    • Cache: Speeds up builds across environments using a content-addressable store.
    • Selective testing: Runs tests faster by selecting them based on file changes.
    • Registry: Speeds up the resolution of Swift Package Index-indexed packages.
    • Build insights: Provides actionable insights from projects, builds, and test runs.
    • Bundle insights: Analyzes built apps and provides suggestions for improvement.
    • Previews: Enables easy sharing of apps as links.

  3. Overview of Tuist codebase search service

    main

    Tuist codebase search is a private service providing the hosted Tuist Model Context Protocol (MCP) server with deterministic, read-only access to a fixed revision of the public Tuist repository. It is designed for safety and contains no language model or command execution surface.

    The service provides the following endpoints:

    • POST /v1/search: Performs bounded literal or regular-expression searches.
    • POST /v1/files: Performs bounded repository traversal.
    • POST /v1/file: Performs bounded line-range reads.
    • GET /health: Reports readiness and the current repository revision.

    All responses include the revision identifier. Search and listing responses also indicate if a result is partial and the reason for partiality.

  4. Overview of the tuist-ops Helm chart

    main

    The tuist-ops Helm chart deploys a Phoenix application along with its required infrastructure: a CloudNativePG (CNPG) Postgres instance and ExternalSecrets (ESO) for credential management. It is designed for production clusters and provides a single-replica deployment using a Recreate strategy.

    Key components include:

    • Deployment: A single-replica pod using ghcr.io/tuist/tuist-ops:<tag>.
    • Service: A ClusterIP service with the tailscale.com/expose: true annotation, making it reachable on the tailnet at ops.<tailnet>.ts.net.
    • Ingress: Public access is restricted strictly to /webhooks/slack/* on ops.tuist.dev. Other endpoints like /api/v1/policy or /db are only accessible via the tailnet.
    • Database: A single-instance CNPG Postgres cluster with 5Gi storage and daily backups to Tigris (s3://tuist-prod-pg-backups/tuist-ops).
    • Secrets: Managed via three ExternalSecrets: tuist-ops-runtime (Slack, Tailscale, GitHub), tuist-ops-app (SECRET_KEY_BASE), and tuist-ops-backup-credentials (Tigris keys).

  5. Overview of the Registry Service

    main
    The Registry Service is a standalone Phoenix service that hosts Tuist's Swift Package Registry. In production, clients access it via https://tuist.dev/api/registry/swift. For environments where the service is exposed directly, the same surface is available under /swift/*.

  7. Tuist Registry Security and Reliability

    main

    The Tuist Registry ensures package security through several mechanisms:

    • Swift Package Index Sync: Only packages available in the Swift Package Index are synced.
    • Direct Source Pulling: Sources are always pulled directly from the original package repository.
    • Checksum Verification: The swift CLI verifies downloaded package source archive checksums against the checksums provided by the registry to ensure integrity.

    This approach addresses common Git-based issues such as non-deterministic builds (reassigned tags), availability (deleted repositories), and inefficiency (cloning full histories).

  8. Understand the Pomerium identity and impersonation flow

    main

    The Pomerium deployment provides a kubectl gateway at https://kube-<env>.tuist.dev. The identity flow works as follows:

    1. Authentication: Users use pomerium-cli k8s exec-credential as a kubeconfig exec plugin. On first use, it opens a browser for Google OIDC and caches a session for ~24h.
    2. Request Injection: pomerium-cli injects the cached Pomerium session JWT as a Bearer token in kubectl requests.
    3. Validation: Pomerium validates the session and attaches user identity via headers: pass_identity_headers: true and jwt_claims_headers: { X-Pomerium-Claim-Email: email }.
    4. Policy Check: The kube-impersonator sidecar calls the tuist-ops-egress service to check the user's identity and environment against active elevation policies.
    5. Impersonation: If authorized, the sidecar strips the Bearer token, attaches the pod's ServiceAccount token, and adds Impersonate-User and Impersonate-Group headers.
    6. RBAC: The Kubernetes API server impersonates the user based on these headers, binding them to the appropriate ClusterRole (e.g., view or edit) defined in templates/access-tiers.yaml.

  9. Use ProjectDescription to define Tuist manifests

    main
    The ProjectDescription module provides a Swift DSL for defining Tuist manifest files such as Project.swift, Workspace.swift, and Tuist.swift. Instead of manually managing .xcodeproj files, you use these APIs to declaratively describe your project structure, targets, dependencies, schemes, and settings. Tuist then generates the Xcode projects based on these Swift definitions.

  10. Overcoming Scaling Challenges in Large Swift Projects

    main

    Large Swift codebases often face productivity bottlenecks due to slow build times, flaky tests, and complex dependency graphs. When scaling, teams typically face three paths:

    1. Adopting React Native: Provides faster iteration via hot-reloading and over-the-air updates, but requires abstracting away the native platform and managing a different ecosystem.
    2. Adopting Bazel: A powerful, advanced build system, but carries a high cost of implementation and maintenance, often requiring specialized knowledge that can create single points of failure.
    3. Using Tuist: A native-first approach that abstracts the complexities of the Xcode toolchain (like linking and graph management) while staying close to the native ecosystem. Tuist helps manage modularization and project generation without the overhead of replacing the entire build system.

  11. Use Once for coarse-grained build tasks

    main

    The Once tool is designed for coarse-grained build tasks rather than fine-grained incremental compilation. It is best suited for high-level operations such as:

    • Building a project
    • Running a test suite
    • Packaging an application
    • Pulling dependencies

    Once is agnostic to the command being run; it can manage rustc, npm test, or any other script-based task. It uses a provider interface to handle infrastructure, allowing you to swap the execution backend (e.g., using Tuist as a provider for low-latency remote caching) without changing your build graph.

  12. Optimize build times with Tuist caching

    main
    Tuist provides a caching system that can improve build times by up to 80% by incorporating binaries into the dependency graph. This ensures that third-party dependencies and unchanged modules are cached rather than recompiled on clean builds. The effectiveness of this system depends on the level of modularization in your project.