从 CI 启用 Nx 远程缓存读写访问NX_CLOUD_ACCESS_TOKEN 完整配置指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxNx Cloud 内置了强大的远程缓存Remote Caching能力可以把任务结果在不同开发机与 CI 任务之间共享。然而缓存安全与访问控制至关重要本篇指南将讲解如何在 Nx Cloud 工作区配置中创建访问令牌从而为 GitHub Actions 等 CI 环境启用对远程缓存的读写访问。读完本文你将掌握read-only与read-write两类 CI 访问令牌的区别与适用场景能够在 GitHub Actions、GitLab、CircleCI、Azure DevOps、BitBucket、Jenkins 等主流 CI 平台中正确注入NX_CLOUD_ACCESS_TOKEN并理解它在 Nx 源码中的底层加载与优先级机制。为什么需要 CI 访问令牌Nx 会在本地缓存任务结果让同一台机器不会重复执行输入相同的任务而远程缓存则把这些结果进一步共享到开发机和 CI 任务之间。远程缓存命中时Nx 会恢复终端输出以及任务声明的产物如构建目录或打包目录行为与本地缓存命中完全一致不会重新执行任务。但问题在于Nx Cloud 上的权限与成员关系决定了开发者在 nx.app 上能访问什么却不会影响你在 CI 中执行 Nx 命令时的行为。要在 CI 里控制远程缓存的读写权限就必须在工作区设置的Access Control选项卡下配置 CI 访问令牌CI access tokens。在 Nx Cloud 工作区的Access Control选项卡中有一个Use recommended settings按钮可以一键生成正确的 CI 访问令牌、并要求开发者登录后才能读取缓存等推荐配置是快速上手的最佳路径。注意read-write令牌对远程缓存拥有完整的写权限只能在可信环境中使用。访问令牌的两种类型Nx Cloud 的 runner 目前提供两种 CI 访问令牌两者都支持分布式任务执行distributed task execution并允许 Nx Cloud 存储有关运行runs的元数据类型权限适用场景read-only只能读取全局远程缓存未受保护的 PR 分支、临时构建read-write可以读取并写入远程缓存受保护的主干分支如main、可信 CI 流水线只读访问read-onlyread-only令牌只能从全局远程缓存中读取。使用这种令牌产生的任务结果会被存储在一个隔离的远程缓存中该缓存仅对 CI 上下文中的特定分支可见不会影响全局共享缓存。不过这个用read-only令牌产生的隔离缓存对该次 CI 执行中的所有机器或 Agent 都是可访问的——也就是说在分布式任务执行过程中各机器之间依然可以通过它共享缓存。读写访问read-writeread-write令牌允许任务结果被存入远程缓存供其他机器或 CI 流水线下载并回放replay。这一访问级别只能用于可信环境例如 CI 流水线中的受保护分支。推荐的组合是为受保护分支配置read-write令牌为未受保护分支配置read-only令牌。这样 PR 分支的构建只能读取既有缓存并写入隔离缓存而主干分支的构建可以把结果写入全局缓存让所有人受益。在 GitHub Actions 中启用读写访问在 CI 中配置访问令牌的方式是设置NX_CLOUD_ACCESS_TOKEN环境变量。GitHub 允许为每个环境environment指定不同的 Secrets而一个环境可以绑定到特定分支——这正是我们区分受保护与未受保护分支的天然工具。在仓库的Settings选项卡中点击Environments为你的受保护分支创建一个环境如release或protected。通常组织已经有某种 release 或 protected 环境可以直接复用。如果你没有受保护分支建议至少把默认分支main/master设为受保护分支。添加环境应用范围的限制将其应用到所有受保护分支。在该环境中添加名为NX_CLOUD_ACCESS_TOKEN的read-write访问令牌。进入侧边栏Secrets and variablesActions。在仓库 Secrets 中添加名为NX_CLOUD_ACCESS_TOKEN的read-only访问令牌。现在你会看到 2 个 Secrets一个属于受保护环境另一个是默认仓库 Secrets。对应的 GitHub Actions 配置示例如下// .github/workflows/ci.yml name: CI env: NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }} jobs: main: runs-on: ubuntu-latest steps: ...NX_CLOUD_ACCESS_TOKEN会优先于nx.json中的任何认证方式。在 GitHub Actions 中由于环境级 Secret 的优先级机制受保护分支如main上的 job 会自动解析到环境的read-write令牌而 PR 分支上的 job 则回退到仓库级的read-only令牌——你无需在 workflow 中手写分支判断逻辑。其他主流 CI 平台的配置方式访问令牌机制与 CI 平台无关核心都是把NX_CLOUD_ACCESS_TOKEN按分支环境注入。下面是几个主流平台的配置要点与示例。Azure DevOps利用 Azure DevOps 的变量组Variable groups创建两个变量组在项目中进入Pipelines Library。创建名为protected的变量组添加NX_CLOUD_ACCESS_TOKENread-write令牌。在该变量组的Pipeline permissions中添加当前流水线配置。在Approvals and checks中添加Branch control检查只允许受保护分支并勾选Verify branch protection。再创建名为unprotected的变量组添加NX_CLOUD_ACCESS_TOKENread-only令牌Branch control 使用*通配符且不勾选 Verify branch protection。流水线中按分支条件引入变量组// azure-pipelines.yml variables: - group: unprotected - ${{ if eq(variables[Build.SourceBranchName], main) }}: - group: protected由于启用了Verify branch protectionCI 只在受保护分支运行时才能读取protected变量组即使开发者试图把流水线改成引用它也会因为不在受保护分支上而报错。但要小心如果团队成员对受保护分支拥有直接写权限他们可能绕过代码评审修改流水线向 Nx 缓存写入。GitLab在Operate Environments创建用于受保护分支的新环境。进入Settings CI/CD展开Variables部分添加两个变量read-only令牌Type 为VariableEnvironments 为AllVisibility 为Masked and hidden取消勾选Protected variable。read-write令牌Type 为VariableEnvironments 选择第 1 步创建的受保护环境Visibility 为Masked and hidden勾选Protected variable。在流水线中为需要写入缓存的 job 指定环境// .gitlab-ci.yml job-name: environment: name: environment-name由于使用了Protected variable标志CI 只有在受保护分支运行时才能读取该变量如果开发者试图把 PR job 改到带read-write令牌的环境中令牌也不会被填充因为其分支未被标记为受保护。CircleCI利用 CircleCI 的Contexts与表达式限制在Organization settings Contexts创建新 context受保护环境可复用已有 context。添加Add Expression Restriction限制只在受保护分支生效例如pipeline.git.branch main。为该 context 添加NX_CLOUD_ACCESS_TOKENread-write令牌。在项目流水线设置Project Settings的Environment Variables中添加NX_CLOUD_ACCESS_TOKENread-only令牌。在 workflow 中为需要写缓存的 job 指定 context// .circleci/config.yml jobs: run-tests-protected: - ... run-tests-prs: - ... workflows: my-workflow: jobs: - run-tests-protected: context: - protected-branches filters: branches: only: main - run-tests-prs: filters: branches: ignore: mainBitBucket Cloud利用 BitBucket Pipelines 的环境变量机制在Repository settings Deployment中为受保护分支选择或创建环境注意分支保护规则选择是 BitBucket Cloud 的付费功能。在该环境设置变量NX_CLOUD_ACCESS_TOKENread-write令牌。在Repository settings Repository variables设置NX_CLOUD_ACCESS_TOKENread-only令牌。在bitbucket-pipelines.yml中引用部署环境// bitbucket-pipelines.yml pipelines: branches: main: - step: name: main checks deployment: Production ...JenkinsJenkins 实例差异较大这里给出最小可行方案创建unprotected与protected两个目录folder分别存放凭据。至少需要 Folders、Credentials、Credentials Binding 这几个插件。在unprotected目录中为NX_CLOUD_ACCESS_TOKEN创建凭据read-only令牌。在protected目录中为NX_CLOUD_ACCESS_TOKEN创建凭据read-write令牌。在Jenkinsfile中用 Credential Binding 插件引用// Jenkinsfile pipeline { agent any stages { stage(Build) { steps { withCredentials([string(credentialsId: NX_CLOUD_ACCESS_TOKEN, variable: NX_CLOUD_ACCESS_TOKEN)]) { sh echo Nx Cloud access token is now set in this context } } } } }遗留的令牌配置方式与迁移建议在较老版本的 Nx 中也可以把访问令牌直接写进nx.json{ nxCloudAccessToken: SOMETOKEN }我们不建议把访问令牌提交到仓库中。此外从 Nx 19.7 开始新工作区改用nxCloudId属性连接 Nx Cloud并推荐开发者使用nx login为本地用户认证配置个人访问令牌personal access tokens。另一个遗留方式是使用nx-cloud.env文件Nx Cloud CLI 会读取工作区根目录下这个文件来加载NX_CLOUD_ACCESS_TOKEN等自定义配置。这些环境变量优先于nx.json中的配置。底层实现令牌的加载与优先级从源码看Nx 在启动时会通过 packages/nx/src/nx-cloud/utilities/environment.ts 中的loadEnvVars()解析环境变量ACCESS_TOKEN process.env.NX_CLOUD_AUTH_TOKEN || process.env.NX_CLOUD_ACCESS_TOKEN || parsed.NX_CLOUD_AUTH_TOKEN || parsed.NX_CLOUD_ACCESS_TOKEN;可以看到令牌解析的优先级链为进程环境变量NX_CLOUD_AUTH_TOKEN→ 进程环境变量NX_CLOUD_ACCESS_TOKEN→nx-cloud.env文件中的NX_CLOUD_AUTH_TOKEN→nx-cloud.env文件中的NX_CLOUD_ACCESS_TOKEN。其中nx-cloud.env通过dotenv.parse读取若文件不存在则返回空对象environment.ts。这解释了为什么在 CI 中设置NX_CLOUD_ACCESS_TOKEN环境变量即可生效并且文档明确说明它优先于nx.json中的任何认证方式——因为令牌在进程启动早期就被读取并用于后续所有 Nx Cloud 通信包括远程缓存的读写与分布式任务执行。与之呼应的是Nx 的任务运行器在 packages/nx/src/tasks-runner/cache.ts 等模块中统一处理本地缓存与远程缓存remote cache的读写而 CI 访问令牌正是决定这些读写是否被允许的关键凭证。远程缓存安全模型回顾结合 远程缓存 文档Nx Cloud 通过以下机制保护缓存结果缓存条目一旦写入即不可变immutable。访问令牌控制读与写权限即本文核心。任务产物支持端到端加密参见 encryption。企业版提供区域性与自托管部署选项。正确的令牌配置原则是开发机可以读取缓存结果而可信的 CI job 才写入缓存。缓存正确性还依赖任务配置中准确的inputs与outputs缺失 input 可能产生过期的缓存命中未声明的 output 则不会被恢复。小结本文围绕 Enable Read/Write Access to your Nx Remote Cache from CI 这一课程主题完整覆盖了 CI 访问令牌的配置路径在 Nx Cloud 工作区的Access Control选项卡创建 CI 访问令牌理解read-only与read-write两种令牌的权限边界与安全含义通过设置NX_CLOUD_ACCESS_TOKEN环境变量在 CI 中注入令牌并利用各 CI 平台的环境/分支保护机制实现受保护分支可写、PR 分支只读的分级策略了解令牌在 Nx 源码中的解析优先级与遗留配置方式的迁移方向。按照这一方案你的 GitHub Actions以及 GitLab、CircleCI、Azure DevOps 等流水线就能在安全的前提下充分利用 Nx Cloud 远程缓存受保护分支把构建产物写入全局缓存所有分支与开发机共享这些结果从而显著减少重复构建时间。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从 CI 启用 Nx 远程缓存读写访问：NX_CLOUD_ACCESS_TOKEN 完整配置指南
从 CI 启用 Nx 远程缓存读写访问NX_CLOUD_ACCESS_TOKEN 完整配置指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nxNx Cloud 内置了强大的远程缓存Remote Caching能力可以把任务结果在不同开发机与 CI 任务之间共享。然而缓存安全与访问控制至关重要本篇指南将讲解如何在 Nx Cloud 工作区配置中创建访问令牌从而为 GitHub Actions 等 CI 环境启用对远程缓存的读写访问。读完本文你将掌握read-only与read-write两类 CI 访问令牌的区别与适用场景能够在 GitHub Actions、GitLab、CircleCI、Azure DevOps、BitBucket、Jenkins 等主流 CI 平台中正确注入NX_CLOUD_ACCESS_TOKEN并理解它在 Nx 源码中的底层加载与优先级机制。为什么需要 CI 访问令牌Nx 会在本地缓存任务结果让同一台机器不会重复执行输入相同的任务而远程缓存则把这些结果进一步共享到开发机和 CI 任务之间。远程缓存命中时Nx 会恢复终端输出以及任务声明的产物如构建目录或打包目录行为与本地缓存命中完全一致不会重新执行任务。但问题在于Nx Cloud 上的权限与成员关系决定了开发者在 nx.app 上能访问什么却不会影响你在 CI 中执行 Nx 命令时的行为。要在 CI 里控制远程缓存的读写权限就必须在工作区设置的Access Control选项卡下配置 CI 访问令牌CI access tokens。在 Nx Cloud 工作区的Access Control选项卡中有一个Use recommended settings按钮可以一键生成正确的 CI 访问令牌、并要求开发者登录后才能读取缓存等推荐配置是快速上手的最佳路径。注意read-write令牌对远程缓存拥有完整的写权限只能在可信环境中使用。访问令牌的两种类型Nx Cloud 的 runner 目前提供两种 CI 访问令牌两者都支持分布式任务执行distributed task execution并允许 Nx Cloud 存储有关运行runs的元数据类型权限适用场景read-only只能读取全局远程缓存未受保护的 PR 分支、临时构建read-write可以读取并写入远程缓存受保护的主干分支如main、可信 CI 流水线只读访问read-onlyread-only令牌只能从全局远程缓存中读取。使用这种令牌产生的任务结果会被存储在一个隔离的远程缓存中该缓存仅对 CI 上下文中的特定分支可见不会影响全局共享缓存。不过这个用read-only令牌产生的隔离缓存对该次 CI 执行中的所有机器或 Agent 都是可访问的——也就是说在分布式任务执行过程中各机器之间依然可以通过它共享缓存。读写访问read-writeread-write令牌允许任务结果被存入远程缓存供其他机器或 CI 流水线下载并回放replay。这一访问级别只能用于可信环境例如 CI 流水线中的受保护分支。推荐的组合是为受保护分支配置read-write令牌为未受保护分支配置read-only令牌。这样 PR 分支的构建只能读取既有缓存并写入隔离缓存而主干分支的构建可以把结果写入全局缓存让所有人受益。在 GitHub Actions 中启用读写访问在 CI 中配置访问令牌的方式是设置NX_CLOUD_ACCESS_TOKEN环境变量。GitHub 允许为每个环境environment指定不同的 Secrets而一个环境可以绑定到特定分支——这正是我们区分受保护与未受保护分支的天然工具。在仓库的Settings选项卡中点击Environments为你的受保护分支创建一个环境如release或protected。通常组织已经有某种 release 或 protected 环境可以直接复用。如果你没有受保护分支建议至少把默认分支main/master设为受保护分支。添加环境应用范围的限制将其应用到所有受保护分支。在该环境中添加名为NX_CLOUD_ACCESS_TOKEN的read-write访问令牌。进入侧边栏Secrets and variablesActions。在仓库 Secrets 中添加名为NX_CLOUD_ACCESS_TOKEN的read-only访问令牌。现在你会看到 2 个 Secrets一个属于受保护环境另一个是默认仓库 Secrets。对应的 GitHub Actions 配置示例如下// .github/workflows/ci.yml name: CI env: NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }} jobs: main: runs-on: ubuntu-latest steps: ...NX_CLOUD_ACCESS_TOKEN会优先于nx.json中的任何认证方式。在 GitHub Actions 中由于环境级 Secret 的优先级机制受保护分支如main上的 job 会自动解析到环境的read-write令牌而 PR 分支上的 job 则回退到仓库级的read-only令牌——你无需在 workflow 中手写分支判断逻辑。其他主流 CI 平台的配置方式访问令牌机制与 CI 平台无关核心都是把NX_CLOUD_ACCESS_TOKEN按分支环境注入。下面是几个主流平台的配置要点与示例。Azure DevOps利用 Azure DevOps 的变量组Variable groups创建两个变量组在项目中进入Pipelines Library。创建名为protected的变量组添加NX_CLOUD_ACCESS_TOKENread-write令牌。在该变量组的Pipeline permissions中添加当前流水线配置。在Approvals and checks中添加Branch control检查只允许受保护分支并勾选Verify branch protection。再创建名为unprotected的变量组添加NX_CLOUD_ACCESS_TOKENread-only令牌Branch control 使用*通配符且不勾选 Verify branch protection。流水线中按分支条件引入变量组// azure-pipelines.yml variables: - group: unprotected - ${{ if eq(variables[Build.SourceBranchName], main) }}: - group: protected由于启用了Verify branch protectionCI 只在受保护分支运行时才能读取protected变量组即使开发者试图把流水线改成引用它也会因为不在受保护分支上而报错。但要小心如果团队成员对受保护分支拥有直接写权限他们可能绕过代码评审修改流水线向 Nx 缓存写入。GitLab在Operate Environments创建用于受保护分支的新环境。进入Settings CI/CD展开Variables部分添加两个变量read-only令牌Type 为VariableEnvironments 为AllVisibility 为Masked and hidden取消勾选Protected variable。read-write令牌Type 为VariableEnvironments 选择第 1 步创建的受保护环境Visibility 为Masked and hidden勾选Protected variable。在流水线中为需要写入缓存的 job 指定环境// .gitlab-ci.yml job-name: environment: name: environment-name由于使用了Protected variable标志CI 只有在受保护分支运行时才能读取该变量如果开发者试图把 PR job 改到带read-write令牌的环境中令牌也不会被填充因为其分支未被标记为受保护。CircleCI利用 CircleCI 的Contexts与表达式限制在Organization settings Contexts创建新 context受保护环境可复用已有 context。添加Add Expression Restriction限制只在受保护分支生效例如pipeline.git.branch main。为该 context 添加NX_CLOUD_ACCESS_TOKENread-write令牌。在项目流水线设置Project Settings的Environment Variables中添加NX_CLOUD_ACCESS_TOKENread-only令牌。在 workflow 中为需要写缓存的 job 指定 context// .circleci/config.yml jobs: run-tests-protected: - ... run-tests-prs: - ... workflows: my-workflow: jobs: - run-tests-protected: context: - protected-branches filters: branches: only: main - run-tests-prs: filters: branches: ignore: mainBitBucket Cloud利用 BitBucket Pipelines 的环境变量机制在Repository settings Deployment中为受保护分支选择或创建环境注意分支保护规则选择是 BitBucket Cloud 的付费功能。在该环境设置变量NX_CLOUD_ACCESS_TOKENread-write令牌。在Repository settings Repository variables设置NX_CLOUD_ACCESS_TOKENread-only令牌。在bitbucket-pipelines.yml中引用部署环境// bitbucket-pipelines.yml pipelines: branches: main: - step: name: main checks deployment: Production ...JenkinsJenkins 实例差异较大这里给出最小可行方案创建unprotected与protected两个目录folder分别存放凭据。至少需要 Folders、Credentials、Credentials Binding 这几个插件。在unprotected目录中为NX_CLOUD_ACCESS_TOKEN创建凭据read-only令牌。在protected目录中为NX_CLOUD_ACCESS_TOKEN创建凭据read-write令牌。在Jenkinsfile中用 Credential Binding 插件引用// Jenkinsfile pipeline { agent any stages { stage(Build) { steps { withCredentials([string(credentialsId: NX_CLOUD_ACCESS_TOKEN, variable: NX_CLOUD_ACCESS_TOKEN)]) { sh echo Nx Cloud access token is now set in this context } } } } }遗留的令牌配置方式与迁移建议在较老版本的 Nx 中也可以把访问令牌直接写进nx.json{ nxCloudAccessToken: SOMETOKEN }我们不建议把访问令牌提交到仓库中。此外从 Nx 19.7 开始新工作区改用nxCloudId属性连接 Nx Cloud并推荐开发者使用nx login为本地用户认证配置个人访问令牌personal access tokens。另一个遗留方式是使用nx-cloud.env文件Nx Cloud CLI 会读取工作区根目录下这个文件来加载NX_CLOUD_ACCESS_TOKEN等自定义配置。这些环境变量优先于nx.json中的配置。底层实现令牌的加载与优先级从源码看Nx 在启动时会通过 packages/nx/src/nx-cloud/utilities/environment.ts 中的loadEnvVars()解析环境变量ACCESS_TOKEN process.env.NX_CLOUD_AUTH_TOKEN || process.env.NX_CLOUD_ACCESS_TOKEN || parsed.NX_CLOUD_AUTH_TOKEN || parsed.NX_CLOUD_ACCESS_TOKEN;可以看到令牌解析的优先级链为进程环境变量NX_CLOUD_AUTH_TOKEN→ 进程环境变量NX_CLOUD_ACCESS_TOKEN→nx-cloud.env文件中的NX_CLOUD_AUTH_TOKEN→nx-cloud.env文件中的NX_CLOUD_ACCESS_TOKEN。其中nx-cloud.env通过dotenv.parse读取若文件不存在则返回空对象environment.ts。这解释了为什么在 CI 中设置NX_CLOUD_ACCESS_TOKEN环境变量即可生效并且文档明确说明它优先于nx.json中的任何认证方式——因为令牌在进程启动早期就被读取并用于后续所有 Nx Cloud 通信包括远程缓存的读写与分布式任务执行。与之呼应的是Nx 的任务运行器在 packages/nx/src/tasks-runner/cache.ts 等模块中统一处理本地缓存与远程缓存remote cache的读写而 CI 访问令牌正是决定这些读写是否被允许的关键凭证。远程缓存安全模型回顾结合 远程缓存 文档Nx Cloud 通过以下机制保护缓存结果缓存条目一旦写入即不可变immutable。访问令牌控制读与写权限即本文核心。任务产物支持端到端加密参见 encryption。企业版提供区域性与自托管部署选项。正确的令牌配置原则是开发机可以读取缓存结果而可信的 CI job 才写入缓存。缓存正确性还依赖任务配置中准确的inputs与outputs缺失 input 可能产生过期的缓存命中未声明的 output 则不会被恢复。小结本文围绕 Enable Read/Write Access to your Nx Remote Cache from CI 这一课程主题完整覆盖了 CI 访问令牌的配置路径在 Nx Cloud 工作区的Access Control选项卡创建 CI 访问令牌理解read-only与read-write两种令牌的权限边界与安全含义通过设置NX_CLOUD_ACCESS_TOKEN环境变量在 CI 中注入令牌并利用各 CI 平台的环境/分支保护机制实现受保护分支可写、PR 分支只读的分级策略了解令牌在 Nx 源码中的解析优先级与遗留配置方式的迁移方向。按照这一方案你的 GitHub Actions以及 GitLab、CircleCI、Azure DevOps 等流水线就能在安全的前提下充分利用 Nx Cloud 远程缓存受保护分支把构建产物写入全局缓存所有分支与开发机共享这些结果从而显著减少重复构建时间。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
