Back to Details

okteto-preview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Okteto Preview Environments Skill

Okteto 预览环境技能

A Preview Environment is a live, production-like instance of the application deployed from a git branch, usually tied to the lifecycle of a pull request. Okteto deploys it into a dedicated namespace named after the preview and gives you shareable URLs, so reviewers, PMs, and stakeholders can click through real functionality without any local setup.
This skill covers two jobs that meet in one ownership model: driving previews directly with the CLI (deploy a branch, hand back the URL) and authoring the CI automation that owns previews per-PR. Before touching a preview, know which of the two owns it — that decides who redeploys it, who posts its URL, and who tears it down.
预览环境是从Git分支部署的、与生产环境类似的实时应用实例，通常与拉取请求（PR）的生命周期绑定。Okteto会将其部署到以预览环境名称命名的专属命名空间中，并提供可共享的URL，这样评审人员、产品经理和利益相关者无需任何本地配置，即可直接体验真实功能。
本技能涵盖两种场景下的操作：通过CLI直接驱动预览环境（部署分支、返回访问URL），以及编写CI自动化流程来管理每个PR的预览环境。操作预览环境前，需明确其归属方——这将决定谁有权重新部署、发布URL以及销毁该环境。

Operating rules

操作规则

  1. Previews deploy from the pushed branch, not your working tree. 
    okteto preview deploy
    clones the repository at 
    --branch
    and deploys that. Local uncommitted changes never reach a preview. Committing and pushing the developer's work is their call — in collaborative mode, show what's uncommitted and confirm before committing or pushing anything on their behalf. In autonomous mode, push the task branch you own before deploying.
  2. Always name the preview explicitly (e.g. 
    pr-1234
    ), and make it a valid name (see Naming previews). Redeploying with the same name updates the same preview; omitting the name generates a random one that CI and cleanup jobs can never find again.
  3. Use a preview to share, a namespace to work. Iterating on code belongs in a dev environment (
    okteto
    skill). A preview is the artifact you hand to reviewers — it has no file sync and no dev containers of yours attached.
  4. Never destroy a preview you did not create. Same doctrine as the 
    okteto
    skill's cleanup rules: a preview you created for your own task is yours to destroy; shared/global previews and CI-owned previews are not (see Cleanup and teardown).
  5. In CI, the pipeline owns the lifecycle. Deploy on PR open/update, destroy on PR close — via 
    okteto/deploy-preview
    and 
    okteto/destroy-preview
    (GitHub) or 
    okteto preview deploy
    /
    destroy
    jobs (GitLab).
  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
    Action，或GitLab的
    okteto preview deploy
    /
    destroy
    任务实现。

Preview vs. namespace: which environment does this task need?

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

Both give you an isolated, deployed copy of the application. They answer different questions:
Dev environment (namespace)Preview Environment
Deploys fromYour local working tree (
okteto deploy
)		A pushed git branch (server-side clone)
LifecycleYours — lives as long as the work doesA pull request — created on open, destroyed on close
AudienceYou / the agent doing the workReviewers, PMs, stakeholders, the PR thread
File sync / 
okteto up
Yes — iterate liveNo — redeploy by pushing to the branch
Where it shows upNamespaces in the Okteto dashboardPreviews section of the dashboard, with repo/branch/PR links
Created by
okteto namespace create
+ 
okteto deploy
okteto preview deploy
(CLI or CI)
Decision guide:
  • "Fix this, test this, debug this" → dev environment in a namespace. Follow the 
    okteto
    skill.
  • "Give me / the team a link to see branch X or PR Y" → preview environment.
  • Ticket-to-PR flows use both: do the work in a namespace dev environment, push the branch, open the PR — then deploy a preview from the pushed branch and post its URL on the PR. The namespace is your workbench; the preview is the deliverable reviewers click.
两者都能提供独立的应用部署实例，但适用场景不同：
开发环境（命名空间）预览环境
部署来源本地工作目录（
okteto deploy
）		已推送的Git分支（服务器端克隆）
生命周期由你掌控——与工作周期一致与拉取请求绑定——创建于PR开启时，销毁于PR关闭时
受众你/执行任务的Agent评审人员、产品经理、利益相关者、PR讨论线程参与者
文件同步 / 
okteto up
支持——可实时迭代不支持——需推送分支重新部署
展示位置Okteto控制台的命名空间列表控制台的预览环境板块，包含仓库/分支/PR链接
创建方式
okteto namespace create
+ 
okteto deploy
okteto preview deploy
（CLI或CI）
决策指南：
  • “修复、测试、调试代码” → 使用命名空间中的开发环境，遵循
    okteto
    技能规则。
  • “给我/团队一个分支X或PR Y的访问链接” → 使用预览环境。
  • “工单转PR”流程需结合两者：在命名空间开发环境中完成工作，推送分支后开启PR——然后从已推送的分支部署预览环境，并将URL发布到PR中。命名空间是你的工作台，预览环境是评审人员可点击访问的交付物。

Deploying a preview

部署预览环境

Previews deploy the code Okteto clones from the repository — so push first:
bash
git push -u origin <branch>
okteto preview deploy pr-1234 --branch <branch> --wait
Key flags (see the quick reference for the full list):
  • --scope personal|global
     — defaults to 
    global
    : accessible to all members of the organization. Use 
    personal
    for experiments only you (and people you explicitly share with) should see. Don't assume personal is the default — it isn't. Sharing a personal preview with specific people happens on its dashboard page (
    /previews/<name>
    ), not through the CLI, and only the owner or an admin can share it.
  • --branch <branch>
     — defaults to the current branch of the checkout you run from.
  • --repository <url>
     — defaults to the current repo's remote URL. Pass it explicitly when deploying a repo you don't have checked out.
  • --var KEY=VALUE
     — injects a variable into the manifest's deploy commands. Repeat the flag for multiple variables.
  • --sourceUrl <pr-url>
     — the HTTPS URL of the pull/merge request; links the PR in the dashboard's Previews list.
  • --timeout
     — defaults to 
    5m0s
    . Raise it for large stacks (
    -t 15m
    ).
  • --file
     — path to the Okteto Manifest if it isn't at the default location.
预览环境部署的是Okteto从仓库克隆的代码——因此需先推送代码：
bash
git push -u origin <branch>
okteto preview deploy pr-1234 --branch <branch> --wait
关键参数（完整列表详见CLI速查）：
  • --scope personal|global
     — 默认值为**
    global
    **：组织内所有成员均可访问。使用
    personal
    仅用于你（及你明确共享的人员）可见的实验。注意默认值并非
    personal
    。共享个人预览环境需在控制台页面（
    /previews/<name>
    ）操作，仅所有者或管理员有权限。
  • --branch <branch>
     — 默认值为当前本地检出的分支。
  • --repository <url>
     — 默认值为当前仓库的远程URL。当部署未检出的仓库时需显式指定。
  • --var KEY=VALUE
     — 向清单的部署命令中注入变量，可重复使用该参数添加多个变量。
  • --sourceUrl <pr-url>
     — 拉取/合并请求的HTTPS URL；用于在控制台预览列表中关联PR。
  • --timeout
     — 默认值为
    5m0s
    。大型堆栈可延长超时时间（例如
    -t 15m
    ）。
  • --file
     — Okteto清单的路径，若不在默认位置需指定。

Naming previews

预览环境命名规则

The preview name becomes the namespace name, so it must be a valid RFC 1123 DNS label: at most 63 characters; lowercase letters, digits, and 
-
only; starting and ending with a letter or digit (regex 
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
). No uppercase, dots, or underscores, and avoid the reserved 
kube-
prefix. Derive a safe slug from a branch the same way the 
okteto
skill derives namespace names:
bash
slug=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-*//; s/-*$//' | cut -c1-50)
Conventions:
  • PR-keyed (GitHub): 
    pr-<number>
    — stable across pushes to the PR, easy for the cleanup job to find.
  • Branch-keyed (GitLab): 
    review-<branch-slug>
    — e.g. 
    review-$CI_COMMIT_REF_SLUG
    , one preview per branch.
Getting the PR number: in CI it's in the event (
${{ github.event.number }}
); on a checked-out branch, 
gh pr view --json number --jq .number
. If the PR doesn't exist yet, don't invent a number — use a branch-keyed name, or open the PR first and deploy the preview after.
If you omit the name, the CLI generates a random one. Fine for a quick manual experiment; wrong everywhere else — a redeploy creates a second preview instead of updating the first.
预览环境名称会成为命名空间名称，因此必须符合RFC 1123 DNS标签规范：最多63个字符；仅包含小写字母、数字和
-
；必须以字母或数字开头和结尾（正则表达式
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
）。不允许大写字母、点或下划线，避免使用保留前缀
kube-
。可通过以下命令从分支生成安全的名称，与
okteto
技能生成命名空间名称的方式一致：
bash
slug=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-*//; s/-*$//' | cut -c1-50)
命名约定：
  • PR关联式（GitHub）：
    pr-<编号>
    ——在PR推送过程中保持稳定，便于清理任务查找。
  • 分支关联式（GitLab）：
    review-<分支缩写>
    ——例如
    review-$CI_COMMIT_REF_SLUG
    ，每个分支对应一个预览环境。
获取PR编号：在CI中可从事件变量获取（
${{ github.event.number }}
）；在已检出的分支上，可使用
gh pr view --json number --jq .number
。若PR尚未创建，请勿自行生成编号——使用分支关联式名称，或先创建PR再部署预览环境。
若省略名称，CLI会生成随机名称。适用于快速手动实验，但不适用于其他场景——重新部署会创建第二个预览环境，而非更新现有环境。

Capturing endpoints and posting the URL back

获取端点并发布URL

After a successful deploy, capture the endpoints:
bash
okteto preview endpoints pr-1234            # JSON (default) — parse programmatically
okteto preview endpoints pr-1234 -o md      # Markdown — made for pasting into a PR comment
The dashboard page for a preview lives at 
https://<your-okteto-url>/previews/<name>
.
Posting to the PR with 
gh
 (when you deployed the preview yourself, outside CI):
bash
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
)"
Posting to a thread (Slack, ticket, chat): same content — the endpoints from 
-o md
plus the dashboard link. The whole point of a preview is that anyone in the thread can click the same URL.
In CI you usually don't need to post at all: the 
okteto/deploy-preview
GitHub Action posts the URL and endpoints as a PR comment automatically when the 
GITHUB_TOKEN
env var is set. Don't add a second 
gh pr comment
step on top of it.
部署成功后，可获取端点信息：
bash
okteto preview endpoints pr-1234            # 默认返回JSON——便于程序解析
okteto preview endpoints pr-1234 -o md      # 返回Markdown格式——适合粘贴到PR评论中
预览环境的控制台页面地址为
https://<你的Okteto地址>/previews/<名称>
。
使用
gh
发布到PR（当你在CI外自行部署预览环境时）：
bash
gh pr comment 1234 --body "$(cat <<EOF
预览环境已就绪 — [控制台](https://<你的Okteto地址>/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
步骤。

Previews in CI

CI中的预览环境配置

GitHub Actions: 
okteto/deploy-preview

GitHub Actions：
okteto/deploy-preview

The canonical pair of workflows — deploy on PR open/update, destroy on close:
yaml
undefined
标准工作流组合——PR开启/更新时部署，PR关闭时销毁：
yaml
undefined

.github/workflows/preview.yaml

.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

```yaml
on: pull_request: branches: - main
concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: false # 切勿设为true——取消正在进行的部署会导致预览环境不一致
jobs: preview: runs-on: ubuntu-latest steps: - name: 配置上下文 uses: okteto/context@latest with: url: ${{ secrets.OKTETO_CONTEXT }} token: ${{ secrets.OKTETO_TOKEN }}
  - name: 部署预览环境
    uses: okteto/deploy-preview@latest
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}   # 启用自动发布URL到PR评论的功能
    with:
      name: pr-${{ github.event.number }}
      timeout: 15m

```yaml

.github/workflows/preview-closed.yaml

.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

Repository secrets required: `OKTETO_CONTEXT` (the URL of the Okteto instance, e.g. `https://okteto.example.com`) and `OKTETO_TOKEN` (an Okteto Admin Access Token). `GITHUB_TOKEN` is populated by GitHub automatically.

`okteto/deploy-preview` inputs: `name` (required), `scope` (default `global`), `variables` (comma-separated `VAR1=VAL1,VAR2=VAL2`), `file`, `branch` (defaults to the branch that triggered the action), `timeout`, `log-level`, `dependencies`, `labels` (comma-separated).
on: pull_request: types: - closed
jobs: closed: runs-on: ubuntu-latest steps: - name: 配置上下文 uses: okteto/context@latest with: url: ${{ secrets.OKTETO_CONTEXT }} token: ${{ secrets.OKTETO_TOKEN }}
  - name: 销毁预览环境
    uses: okteto/destroy-preview@latest
    with:
      name: pr-${{ github.event.number }}   # 必须与部署工作流中的名称完全一致

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

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

GitLab CI/CD

GitLab CI/CD

Same shape with the CLI directly (image 
ghcr.io/okteto/okteto:latest
): a 
review
job runs 
okteto preview deploy review-$CI_COMMIT_REF_SLUG --branch $CI_COMMIT_REF_NAME --repository $CI_PROJECT_URL
, and a 
stop-review
job runs 
okteto preview destroy review-$CI_COMMIT_REF_SLUG
when the branch is deleted or the MR merges. Pass the preview URL via the job's 
environment.url
so reviewers can open it from GitLab.
使用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直接访问。

Inspecting, sleeping, and waking previews

查看、休眠与唤醒预览环境

bash
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
Sleeping keeps the preview and its configuration; waking restores it. Prefer 
sleep
over 
destroy
when the goal is saving resources on a preview someone may still need. Admins can also mark a preview Persistent in the dashboard, which exempts it from automatic sleep and garbage collection — that's a dashboard action, not a CLI one.
Applications can detect they're running in a preview via the 
OKTETO_IS_PREVIEW_ENVIRONMENT=true
environment variable — useful when the task is "make the app behave differently in previews".
bash
okteto preview list                    # 查看预览环境的状态和范围（支持`-o json|yaml`格式）
okteto preview list --label team-a     # 按标签过滤预览环境
okteto preview sleep pr-1234           # 缩容以节省资源（仅所有者或管理员可操作）
okteto preview wake pr-1234            # 唤醒休眠的预览环境
休眠会保留预览环境及其配置；唤醒会恢复其运行状态。当需要为仍可能被使用的预览环境节省资源时，优先选择
sleep
而非
destroy
。管理员还可在控制台中将预览环境标记为持久化，使其免于自动休眠和垃圾回收——此操作仅能在控制台完成，无法通过CLI执行。
应用可通过环境变量
OKTETO_IS_PREVIEW_ENVIRONMENT=true
检测自身是否运行在预览环境中——适用于“让应用在预览环境中表现不同”的场景。

Cleanup and teardown

清理与销毁

okteto preview destroy <name>
runs any 
destroy
commands in the Okteto Manifest, then removes the preview and its namespace. It is destructive — the same authorization doctrine as the 
okteto
skill applies.
Decide who owns teardown when you create the preview. If the repo has preview workflows, prefer opening the PR and letting CI own the whole lifecycle, teardown included. If you deploy ad hoc for a PR, teardown rides on the PR: destroy the preview yourself when the PR closes if you're still running; otherwise say so where you posted the URL — "this preview is not destroyed automatically; after the PR closes, run 
okteto preview destroy <name>
". Sleep and the platform's garbage collection are a resource backstop, not an owner.
SituationMay the agent destroy it?
Preview the agent created this session for its own taskYes — yours to tear down when the work is done and the URL is no longer needed
CI-owned preview (e.g. 
pr-<number>
managed by workflows)		No — the close-PR workflow owns teardown. Destroying it mid-review breaks the link reviewers are using
Global preview created by someone elseNever without explicit instruction
Someone else's personal previewNever — and only admins or the owner could anyway
  • In collaborative mode, surface the command and let the developer run it: "To tear down the preview, run: 
    okteto preview destroy pr-1234
    ".
  • In autonomous mode, a preview you created this session is yours to destroy once the task no longer needs it — the same "you created it, you own its teardown" rule as the 
    okteto
    skill's worktree namespaces. One caveat: if you posted its URL to a PR or thread, reviewers may still be using it — leave it running (or 
    okteto preview sleep <name>
    ) and report the teardown command instead. For any preview you did not create, destroy only with explicit authorization, a documented cleanup policy, or pipeline ownership of this run.
  • Don't use 
    destroy
    as a retry.     A failed or stale preview is fixed by redeploying with the same name — 
    okteto preview deploy <name>
    updates in place.
okteto preview destroy <name>
会执行Okteto清单中的
destroy
命令，然后移除预览环境及其命名空间。此操作具有破坏性——遵循与
okteto
技能相同的权限规则。
创建预览环境时需明确销毁权限归属。若仓库已有预览工作流，优先选择开启PR并让CI掌控整个生命周期（包括销毁）。若你为PR临时部署预览环境，销毁操作需与PR绑定：PR关闭时若你仍在维护，可自行销毁；否则需在发布URL的位置说明“此预览环境不会自动销毁；PR关闭后，执行
okteto preview destroy <name>
即可销毁”。休眠和平台的垃圾回收只是资源保障措施，而非替代所有者的职责。
场景Agent是否可销毁？
Agent在本次会话中为自身任务创建的预览环境是——工作完成且URL不再需要时可销毁
CI托管的预览环境（例如工作流管理的
pr-<编号>
）		否——PR关闭工作流负责销毁。评审期间销毁会破坏评审人员正在使用的链接
他人创建的全局预览环境绝对不可——除非有明确指令
他人的个人预览环境绝对不可——仅管理员或所有者可操作
  • 在协作模式下，展示销毁命令并让开发者自行执行：“如需销毁预览环境，请执行：
    okteto preview destroy pr-1234
    ”。
  • 在自主模式下，你本次会话创建的预览环境可在任务不再需要时销毁——遵循“谁创建谁负责销毁”的规则，与
    okteto
    技能中工作目录命名空间的规则一致。注意：若你已将URL发布到PR或讨论线程，评审人员可能仍在使用——可选择保持运行（或执行
    okteto preview sleep <name>
    ），并告知销毁命令。对于非你创建的预览环境，仅在有明确授权、文档化清理策略或本次流程由管道掌控时才可销毁。
  • 切勿用
    destroy
    作为重试手段    。失败或过期的预览环境可通过使用相同名称重新部署来修复——
    okteto preview deploy <name>
    会就地更新。

CLI quick reference

CLI速查

CommandCollaborativeAutonomousPurpose
okteto preview deploy <name>
AgentAgentDeploy a preview from a pushed branch
okteto preview endpoints <name>
AgentAgentList preview URLs (
-o json
default, 
-o md
for PR comments)
okteto preview list
AgentAgentStatus and scope of your previews
okteto preview sleep <name>
Agent (own)Agent (own)Scale down a preview you own
okteto preview wake <name>
AgentAgentWake a sleeping preview
okteto preview destroy <name>
User (or self-created)Self-created / with policyTear down a preview and its namespace
okteto preview deploy
flags: 
-b/--branch
(default: current branch), 
--repository
(default: current repo), 
-s/--scope personal|global
(default: 
global
), 
-v/--var KEY=VALUE
(repeatable), 
--sourceUrl <pr-url>
, 
-t/--timeout
(default 
5m0s
), 
-w/--wait
(default 
true
), 
-f/--file
, 
--label
(repeatable), 
--dependencies
.
命令协作模式自主模式用途
okteto preview deploy <name>
Agent执行Agent执行从已推送的分支部署预览环境
okteto preview endpoints <name>
Agent执行Agent执行列出预览环境URL（默认返回JSON，
-o md
格式适合PR评论）
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
。

Common mistakes to avoid

需避免的常见错误

  • Expecting local changes in the preview. Previews deploy from the pushed branch. Commit and push before 
    okteto preview deploy
    , and push again to update it.
  • Omitting the preview name in CI. A nameless deploy gets a random name, so every run creates a new preview and the cleanup job orphans them all. Key the name to the PR (
    pr-<number>
    ) or branch slug.
  • Mismatched names between deploy and destroy workflows. The destroy job must use the exact same name expression as the deploy job, or previews leak.
  • Assuming 
    --scope
    defaults to 
    personal
    .     The default is 
    global
    — visible to the whole organization. Say 
    --scope personal
    when the work isn't ready to share.
  • Using a preview as a dev environment. No file sync, no 
    okteto up
    . To iterate on code, use a namespace dev environment (
    okteto
    skill) and keep the preview for reviewers.
  • Running 
    okteto endpoints
    instead of 
    okteto preview endpoints <name>
    .     The former targets the active namespace of your context, not the preview.
  • Setting 
    cancel-in-progress: true
    on the preview workflow.     Cancelling an in-progress deploy leaves the preview inconsistent and leaks resources. Queue per-PR with 
    cancel-in-progress: false
    .
  • Double-posting the URL in CI. With 
    GITHUB_TOKEN
    set, 
    okteto/deploy-preview
    already comments on the PR. Add your own 
    gh pr comment
    only when deploying from outside CI.
  • Destroying a preview you don't own. CI-owned, shared/global, or someone else's previews are off-limits without explicit instruction — same rule as 
    okteto destroy
    in the 
    okteto
    skill.
  • Destroying to "fix" a broken preview. Redeploy with the same name instead; it updates in place.
  • 期望本地更改同步到预览环境。预览环境从已推送的分支部署。执行
    okteto preview deploy
    前需提交并推送代码，更新预览环境需再次推送。
  • CI中省略预览环境名称。无名称的部署会生成随机名称，导致每次运行都创建新的预览环境，清理任务无法处理遗留环境。需将名称与PR（
    pr-<编号>
    ）或分支缩写绑定。
  • 部署与销毁工作流名称不匹配。销毁任务必须使用与部署任务完全相同的名称表达式，否则会遗留预览环境。
  • 默认
    --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
    的规则一致。
  • 用
    destroy
    “修复”损坏的预览环境    。应使用相同名称重新部署，实现就地更新。