身份验证

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

作为用户

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

tuist auth login

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

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

OIDC 令牌

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

支持的 CI 提供商

• GitHub Actions
• CircleCI
• Bitrise

设置 OIDC 身份验证

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

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

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

OIDC 令牌作用域

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

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

Gradle 插件身份验证

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 缓存命令和任务即可。

账户令牌

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

创建账户令牌

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	将令牌限制为特定项目句柄。如果未指定，令牌可以访问所有项目。

可用作用域

作用域	描述
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	创建和更新命令运行

作用域组

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

作用域组	包含的作用域
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

持续集成

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

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

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

管理账户令牌

列出账户的所有令牌：

tuist account tokens list my-account

按名称撤销令牌：

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

使用账户令牌

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

export TUIST_TOKEN=your-account-token

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