okteto-preview

Okteto 预览环境技能

预览环境是从 git 分支部署的、可实时访问且类似生产环境的应用实例，通常与拉取请求的生命周期绑定。Okteto 会将其部署到一个以预览环境命名的专用命名空间中，并提供可分享的 URL，让审阅者、PM 和利益相关者无需进行任何本地设置，就能体验真实功能。

这项技能涵盖两项采用同一归属模式的工作：使用 CLI 直接管理预览环境（部署分支并返回 URL），以及编写负责管理每个 PR 预览环境的 CI 自动化。操作预览环境之前，先确认它归谁管理——这决定了由谁重新部署、发布 URL，以及销毁预览环境。

操作规则

1. 预览环境从已推送的分支部署，而不是从你的工作树部署。 okteto preview deploy 会克隆 --branch 指定分支中的仓库并进行部署。本地未提交的更改永远不会进入预览环境。是否提交并推送开发者的工作由开发者本人决定——在协作模式下，先展示未提交的更改，并在代为提交或推送之前征求确认。在自主模式下，部署前先推送你负责的任务分支。
2. 始终明确指定预览环境名称（例如 pr-1234），并确保名称有效（参见预览环境命名）。使用相同名称重新部署会更新同一个预览环境；省略名称则会生成一个随机名称，CI 和清理作业之后都无法再找到它。
3. 用预览环境分享成果，用命名空间开展工作。 代码迭代应在开发环境中进行（参见 okteto 技能）。预览环境是交给审阅者的产物——它不支持文件同步，也不会附加你的开发容器。
4. 绝不销毁由他人创建的预览环境。 原则与 okteto 技能中的清理规则相同：你为自己的任务创建的预览环境由你负责销毁；共享／全局预览环境和 CI 管理的预览环境则不归你管理（参见清理与拆除）。
5. 在 CI 中，由流水线管理生命周期。 PR 打开或更新时部署，PR 关闭时销毁——使用 GitHub 的 okteto/deploy-preview 和 okteto/destroy-preview，或 GitLab 的 okteto preview deploy／destroy 作业。

预览环境与命名空间：此任务需要哪种环境？

两者都能提供应用的隔离部署副本，但解决的问题不同：

	开发环境（命名空间）	预览环境
部署来源	你的本地工作树（okteto deploy）	已推送的 git 分支（服务端克隆）
生命周期	由你管理——工作持续多久，环境就保留多久	拉取请求——打开时创建，关闭时销毁
使用者	你／负责工作的 Agent	审阅者、PM、利益相关者、PR 讨论串
文件同步／okteto up	支持——可实时迭代	不支持——通过推送分支重新部署
显示位置	Okteto 控制面板中的命名空间	控制面板的预览环境版块，附带仓库／分支／PR 链接
创建方式	okteto namespace create + okteto deploy	okteto preview deploy（CLI 或 CI）

决策指南：

• “修复这个问题、测试这个、调试这个” → 在命名空间中的开发环境里进行。遵循 okteto 技能。
• “给我／团队一个链接，以查看分支 X 或 PR Y” → 预览环境。
• 从工单到 PR 的流程会同时用到两者：在命名空间开发环境中完成工作，推送分支并创建 PR，然后从已推送的分支部署预览环境，并将其 URL 发布到 PR 中。命名空间是你的工作台；预览环境是审阅者点击查看的交付成果。

---

部署预览

预览会部署 Okteto 从仓库克隆的代码，因此请先推送：

git push -u origin <branch>
okteto preview deploy pr-1234 --branch <branch> --wait

关键标志（完整列表请参阅快速参考）：

• --scope personal|global — 默认为 global：组织中的所有成员均可访问。仅在只希望自己（以及明确分享给的人）看到预览时使用 personal。不要认为默认值是 personal，事实并非如此。与特定人员分享个人预览需在其仪表板页面（/previews/<name>）中进行，而不是通过 CLI；只有所有者或管理员可以分享。
• --branch <branch> — 默认为运行命令所在检出目录的当前分支。
• --repository <url> — 默认为当前仓库的远程 URL。部署未在本地检出的仓库时，请显式传入此参数。
• --var KEY=VALUE — 向清单的部署命令注入变量。多个变量请重复使用此标志。
• --sourceUrl <pr-url> — 拉取请求／合并请求的 HTTPS URL；会在仪表板的 Previews 列表中添加 PR 链接。
• --timeout — 默认为 5m0s。大型堆栈请调高此值（-t 15m）。
• --file — Okteto Manifest 的路径（如果文件不在默认位置）。

为预览命名

预览名称会成为命名空间名称，因此必须是有效的 RFC 1123 DNS 标签：最多 63 个字符；只能包含小写字母、数字和 -；且必须以字母或数字开头和结尾（正则表达式 ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$）。不能使用大写字母、点或下划线，并应避免使用保留前缀 kube-。按照 okteto 技能生成命名空间名称的相同方式，从分支名派生安全的 slug：

slug=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-*//; s/-*$//' | cut -c1-50)

约定：

• 按 PR 命名（GitHub）：pr-<number> — 对同一个 PR 的多次推送保持不变，便于清理任务查找。
• 按分支命名（GitLab）：review-<branch-slug> — 例如 review-$CI_COMMIT_REF_SLUG，每个分支对应一个预览。

**获取 PR 编号：**在 CI 中，编号包含在事件里（${{ github.event.number }}）；在已检出的分支上，使用 gh pr view --json number --jq .number。如果 PR 尚不存在，不要虚构编号 — 使用按分支命名的方式，或先创建 PR，再部署预览。

如果省略名称，CLI 会随机生成一个名称。快速手动试验时可以这样做；其他情况都不合适 — 重新部署会创建第二个预览，而不是更新第一个。

---

捕获端点并回传 URL

部署成功后，捕获端点：

okteto preview endpoints pr-1234            # JSON (default) — parse programmatically
okteto preview endpoints pr-1234 -o md      # Markdown — made for pasting into a PR comment

预览的仪表板页面位于 https://<your-okteto-url>/previews/<name>。

使用 gh 发布到 PR（在 CI 之外自行部署预览时）：

gh pr comment 1234 --body "$(cat <<EOF
Preview environment ready — [dashboard](https://<your-okteto-url>/previews/pr-1234)

$(okteto preview endpoints pr-1234 -o md)
EOF
)"

发布到讨论串（Slack、工单、聊天）：内容相同 — -o md 输出的端点以及仪表板链接。预览的意义就在于，讨论串中的任何人都可以点击同一个 URL。

在 CI 中，通常无需手动发布：设置 GITHUB_TOKEN 环境变量后，okteto/deploy-preview GitHub Action 会自动将 URL 和端点发布为 PR 评论。不要再额外添加 gh pr comment 步骤。

---

在 CI 中使用预览

GitHub Actions：okteto/deploy-preview

标准工作流组合 — PR 打开／更新时部署，关闭时销毁：

# .github/workflows/preview.yaml
on:
  pull_request:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false   # never true — cancelling an in-progress deploy leaves the preview inconsistent

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Context
        uses: okteto/context@latest
        with:
          url: ${{ secrets.OKTETO_CONTEXT }}
          token: ${{ secrets.OKTETO_TOKEN }}

      - name: Deploy preview environment
        uses: okteto/deploy-preview@latest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}   # enables the automatic PR comment with the URL
        with:
          name: pr-${{ github.event.number }}
          timeout: 15m

# .github/workflows/preview-closed.yaml
on:
  pull_request:
    types:
      - closed

jobs:
  closed:
    runs-on: ubuntu-latest
    steps:
      - name: Context
        uses: okteto/context@latest
        with:
          url: ${{ secrets.OKTETO_CONTEXT }}
          token: ${{ secrets.OKTETO_TOKEN }}

      - name: Destroy preview environment
        uses: okteto/destroy-preview@latest
        with:
          name: pr-${{ github.event.number }}   # must match the deploy workflow's name exactly

所需的仓库机密：OKTETO_CONTEXT（Okteto 实例的 URL，例如 https://okteto.example.com）和 OKTETO_TOKEN（Okteto 管理员访问令牌）。GitHub 会自动填充 GITHUB_TOKEN。

okteto/deploy-preview 输入参数：name（必需）、scope（默认为 global）、variables（逗号分隔的 VAR1=VAL1,VAR2=VAL2）、file、branch（默认为触发 Action 的分支）、timeout、log-level、dependencies、labels（逗号分隔）。

GitLab CI/CD

直接使用 CLI 的方式相同（镜像 ghcr.io/okteto/okteto:latest）：review 作业运行 okteto preview deploy review-$CI_COMMIT_REF_SLUG --branch $CI_COMMIT_REF_NAME --repository $CI_PROJECT_URL，stop-review 作业则在分支被删除或 MR 合并时运行 okteto preview destroy review-$CI_COMMIT_REF_SLUG。通过作业的 environment.url 传递预览 URL，方便审阅者从 GitLab 打开。

---

检查、休眠和唤醒预览

okteto preview list                    # status and scope of your previews (-o json|yaml)
okteto preview list --label team-a     # filter by label
okteto preview sleep pr-1234           # scale it down to save resources (owner or admin only)
okteto preview wake pr-1234            # bring a sleeping preview back

休眠会保留预览及其配置；唤醒则会将其恢复。如果目的是节省资源，而预览之后可能还会用到，请优先使用 sleep，而不是 destroy。管理员也可以在仪表板中将预览标记为 Persistent，使其不受自动休眠和垃圾回收影响——这是仪表板操作，不是 CLI 操作。

应用可以通过环境变量 OKTETO_IS_PREVIEW_ENVIRONMENT=true 检测自己是否运行在预览环境中——适用于“让应用在预览环境中表现不同”这类任务。

---

清理和拆除

okteto preview destroy <name> 会运行 Okteto Manifest 中的任何 destroy 命令，然后移除预览及其命名空间。这是破坏性操作——适用与 okteto 技能相同的授权原则。

创建预览时就要确定由谁负责拆除。 如果仓库中有预览工作流，优先打开 PR，让 CI 负责整个生命周期，包括拆除。如果你为 PR 临时部署预览，拆除工作也由 PR 决定：如果 PR 关闭时你仍在运行，就自行销毁预览；否则请在发布 URL 的位置说明：“此预览不会自动销毁；PR 关闭后，请运行 okteto preview destroy <name>。”休眠和平台的垃圾回收只是资源保障措施，不代表有人负责。

情况	Agent 可以销毁吗？
Agent 在本次会话中为自己的任务创建的预览	可以 — 工作完成且不再需要 URL 时，由你负责拆除
由 CI 管理的预览（例如由工作流管理的 pr-<number>）	不可以 — 关闭 PR 的工作流负责拆除。在评审过程中销毁预览会导致评审者正在使用的链接失效
由其他人创建的全局预览	绝不可以，除非得到明确指示
其他人的个人预览	绝不可以 — 而且只有管理员或所有者才能销毁

• 在协作模式下，提供命令并让开发者运行：“要拆除预览，请运行：okteto preview destroy pr-1234。”
• 在自主模式下，本次会话中由你创建的预览，一旦任务不再需要，就由你负责销毁——这与 okteto 技能中“由你创建，由你负责拆除”的工作树命名空间规则相同。需要注意的是：如果你已在 PR 或讨论串中发布其 URL，评审者可能仍在使用它——请让预览继续运行（或运行 okteto preview sleep <name>），并改为报告拆除命令。对于任何并非由你创建的预览，只有在获得明确授权、存在有记录的清理策略，或由流水线负责本次运行时，才能销毁。
• 不要用 destroy 来重试。 失败或过期的预览，应通过使用相同名称重新部署来修复——okteto preview deploy <name> 会就地更新。

---

CLI 快速参考

命令	协作式	自主式	用途
okteto preview deploy <name>	Agent	Agent	从已推送的分支部署预览环境
okteto preview endpoints <name>	Agent	Agent	列出预览环境 URL（默认使用 -o json，PR 评论使用 -o md）
okteto preview list	Agent	Agent	查看预览环境的状态和范围
okteto preview sleep <name>	Agent（自己的）	Agent（自己的）	缩容自己拥有的预览环境
okteto preview wake <name>	Agent	Agent	唤醒休眠的预览环境
okteto preview destroy <name>	用户（或自己创建的）	自己创建的／符合策略的	拆除预览环境及其命名空间

okteto preview deploy 标志：-b/--branch（默认值：当前分支）、--repository（默认值：当前仓库）、-s/--scope personal|global（默认值：global）、-v/--var KEY=VALUE（可重复）、--sourceUrl <pr-url>、-t/--timeout（默认值：5m0s）、-w/--wait（默认值：true）、-f/--file、--label（可重复）、--dependencies。

应避免的常见错误

• 以为预览环境会包含本地更改。 预览环境从已推送的分支部署。执行 okteto preview deploy 前先提交并推送；要更新预览环境，请再次推送。
• 在 CI 中未指定预览环境名称。 未命名的部署会获得随机名称，因此每次运行都会创建一个新的预览环境，清理任务也会把它们全都遗留下来。请将名称设为与 PR 关联的名称（pr-<number>）或分支标识。
• 部署和销毁工作流中的名称不一致。 销毁任务必须使用与部署任务完全相同的名称表达式，否则预览环境会遗留下来。
• 误以为 --scope 的默认值是 personal。 默认值是 global，整个组织都可以看到。尚未准备好共享时，请指定 --scope personal。
• 将预览环境用作开发环境。 预览环境不支持文件同步，也不支持 okteto up。如需迭代代码，请使用命名空间开发环境（okteto 技能），并将预览环境留给审阅者使用。
• 运行 okteto endpoints，而不是 okteto preview endpoints <name>。 前者针对当前上下文中的活动命名空间，而非预览环境。
• 在预览工作流中设置 cancel-in-progress: true。 取消进行中的部署会导致预览环境状态不一致，并造成资源泄漏。请按 PR 排队，并设置 cancel-in-progress: false。
• 在 CI 中重复发布 URL。 设置了 GITHUB_TOKEN 后，okteto/deploy-preview 已会在 PR 中评论。仅在 CI 之外部署时，才添加自己的 gh pr comment。
• 销毁不属于自己的预览环境。 未经明确指示，不得操作由 CI 管理、共享／全局或属于他人的预览环境——这与 okteto 技能中的 okteto destroy 规则相同。
• 通过销毁来“修复”损坏的预览环境。 请改用相同名称重新部署；这会就地更新预览环境。