身份验证

身份验证 {#authentication}

为了与服务器交互，CLI 需要使用 Bearer 身份验证 对请求进行身份验证。CLI 支持以用户身份、账户身份或使用 OIDC 令牌进行身份验证。

作为用户 {#as-a-user}

在本地机器上使用 CLI 时，我们建议你以用户身份进行身份验证。要以用户身份进行身份验证，你需要运行以下命令：

tuist auth login

该命令将引导你完成基于 Web 的身份验证流程。身份验证后，CLI 会在 ~/.config/tuist/credentials 下存储一个长期有效的刷新令牌和一个短期有效的访问令牌。目录中的每个文件代表你进行身份验证的域，默认情况下应该是 tuist.dev.json。该目录中存储的信息是敏感的，请确保将其保管好。

CLI 在向服务器发出请求时会自动查找凭据。如果访问令牌已过期，CLI 将使用刷新令牌获取新的访问令牌。

OIDC 令牌 {#oidc-tokens}

对于支持 OpenID Connect (OIDC) 的 CI 环境，Tuist 可以自动进行身份验证，无需你管理长期密钥。在支持的 CI 环境中运行时，CLI 会自动检测 OIDC 令牌提供程序，并用 CI 提供的令牌交换 Tuist 访问令牌。

支持的 CI 提供商 {#supported-ci-providers}

• GitHub Actions
• CircleCI
• Bitrise

设置 OIDC 身份验证 {#setting-up-oidc-authentication}

1. 将你的仓库连接到 Tuist：按照 GitHub 集成指南 将你的 GitHub 仓库连接到你的 Tuist 项目。

2. 运行 tuist auth login：在 CI 工作流中，在任何需要身份验证的命令之前运行 tuist auth login。CLI 会自动检测 CI 环境并使用 OIDC 进行身份验证。

请参阅 持续集成指南 了解提供商特定配置示例。

OIDC 令牌作用域 {#oidc-token-scopes}

OIDC 令牌被授予 ci 作用域组，提供对连接到该仓库的所有项目的访问权限。详见 作用域组 了解 ci 作用域包含的内容。

::: tip 安全优势

OIDC 身份验证比长期令牌更安全，因为：

• 无需轮换或管理的密钥
• 令牌是短期的，并且仅限于单个工作流运行
• 身份验证与你的仓库身份绑定

:::

Gradle 插件身份验证 {#gradle-plugin-authentication}

Gradle 插件使用 Tuist CLI 的身份验证状态，没有单独的定义登录流程。使用 CLI 进行一次身份验证，插件将复用这些凭据。

对于项目和服务器配置，包括 project 和 url，请使用标准的 tuist.toml 参考。

对于本地使用，请运行：

tuist auth login

对于 CI，请使用以下任一方式：

• OIDC 身份验证（如果可用，推荐）
• 通过 TUIST_TOKEN 进行 账户令牌身份验证

对于自托管的 Tuist 服务器，请在 tuist.toml 中定义服务器 URL（例如 url = "https://tuist.your-company.com"）并运行标准登录流程。URL 从插件使用的同一配置文件解析。

配置好身份验证后，正常运行你的 Gradle 缓存命令和任务即可。

账户令牌 {#account-tokens}

对于不支持 OIDC 的 CI 环境，或者当你需要更精细地控制权限时，你可以使用账户令牌。账户令牌允许你精确指定令牌可以访问的作用域和项目。

创建账户令牌 {#creating-an-account-token}

tuist account tokens create my-account \
  --scopes project:cache:read project:cache:write \
  --name ci-cache-token \
  --expires 1y

该命令接受以下选项：

选项	描述
--scopes	必需。逗号分隔的作用域列表，授予令牌。
--name	必需。令牌的唯一标识符（1-32 个字符，仅限字母数字、连字符和下划线）。
--expires	可选。令牌应该过期的时间。使用 30d（天）、6m（月）或 1y（年）这样的格式。如果未指定，令牌永不过期。
--projects	将令牌限制为特定项目句柄。如果未指定，令牌可以访问所有项目。

可用作用域 {#available-scopes}

作用域	描述
account:members:read	读取账户成员
account:members:write	管理账户成员
account:registry:read	从 Swift 包注册表读取
account:registry:write	发布到 Swift 包注册表
project:previews:read	下载预览
project:previews:write	上传预览
project:admin:read	读取项目设置
project:admin:write	管理项目设置
project:cache:read	下载缓存的二进制文件
project:cache:write	上传缓存的二进制文件
project:bundles:read	查看 bundle
project:bundles:write	上传 bundle
project:tests:read	读取测试结果
project:tests:write	上传测试结果
project:builds:read	读取构建分析
project:builds:write	上传构建分析
project:runs:read	读取命令运行
project:runs:write	创建和更新命令运行

作用域组 {#scope-groups}

作用域组提供了一种便捷的方式来授予多个相关作用域，只需使用一个标识符。当你使用作用域组时，它会自动展开为包含的所有独立作用域。

作用域组	包含的作用域
ci	project:cache:write, project:previews:write, project:bundles:write, project:tests:write, project:builds:write, project:runs:write
mcp	project:cache:read, project:previews:read, project:bundles:read, project:tests:read, project:builds:read, project:runs:read

持续集成 {#continuous-integration}

对于不支持 OIDC 的 CI 环境，你可以使用具有 ci 作用域组的账户令牌来验证你的 CI 工作流：

tuist account tokens create my-account --scopes ci --name ci

这会创建一个具有典型 CI 操作（缓存、预览、bundle、测试、构建和运行）所需所有作用域的令牌。将生成的令牌作为密钥存储在你的 CI 环境中，并将其设置为 TUIST_TOKEN 环境变量。

管理账户令牌 {#managing-account-tokens}

列出账户的所有令牌：

tuist account tokens list my-account

按名称撤销令牌：

tuist account tokens revoke my-account ci-cache-token

使用账户令牌 {#using-account-tokens}

账户令牌应定义为环境变量 TUIST_TOKEN：

export TUIST_TOKEN=your-account-token

::: tip 何时使用账户令牌

在以下情况下使用账户令牌：

• 在不支持 OIDC 的 CI 环境中进行身份验证
• 精细控制令牌可以执行哪些操作
• 令牌可以访问账户中的多个项目
• 自动过期的有时间限制的令牌

:::