Agent Skill · Okteto

okteto-preview

Okteto Preview Environment skill. Use when someone wants a live, shareable environment for a branch or pull request — "deploy a preview for this PR", "give me a URL for branch X", posting a preview link back to a PR or thread — or when setting up PR preview automation in CI (GitHub Actions or GitLab). Use alongside the `okteto` skill: for editing, syncing, and iterating on code, defer to that skill's dev environments. Requires an Okteto context; previews are an Okteto Platform feature.

Provider: Okteto Path in repo: plugins/okteto/skills/preview/SKILL.md

Skill body

Okteto Preview Environments Skill

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.

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).

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

Both give you an isolated, deployed copy of the application. They answer different questions:

  Dev environment (namespace) Preview Environment
Deploys from Your local working tree (okteto deploy) A pushed git branch (server-side clone)
Lifecycle Yours — lives as long as the work does A pull request — created on open, destroyed on close
Audience You / the agent doing the work Reviewers, PMs, stakeholders, the PR thread
File sync / okteto up Yes — iterate live No — redeploy by pushing to the branch
Where it shows up Namespaces in the Okteto dashboard Previews section of the dashboard, with repo/branch/PR links
Created by okteto namespace create + okteto deploy okteto preview deploy (CLI or CI)

Decision guide:


Deploying a preview

Previews deploy the code Okteto clones from the repository — so push first:

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

Key flags (see the quick reference for the full list):

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:

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

Conventions:

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.


Capturing endpoints and posting the URL back

After a successful deploy, capture the endpoints:

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):

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.


Previews in CI

GitHub Actions: okteto/deploy-preview

The canonical pair of workflows — deploy on PR open/update, destroy on close:

# .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

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).

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.


Inspecting, sleeping, and waking previews

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”.


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.

Situation May the agent destroy it?
Preview the agent created this session for its own task Yes — 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 else Never without explicit instruction
Someone else’s personal preview Never — and only admins or the owner could anyway

CLI quick reference

Command Collaborative Autonomous Purpose
okteto preview deploy <name> Agent Agent Deploy a preview from a pushed branch
okteto preview endpoints <name> Agent Agent List preview URLs (-o json default, -o md for PR comments)
okteto preview list Agent Agent Status and scope of your previews
okteto preview sleep <name> Agent (own) Agent (own) Scale down a preview you own
okteto preview wake <name> Agent Agent Wake a sleeping preview
okteto preview destroy <name> User (or self-created) Self-created / with policy Tear 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.

Common mistakes to avoid

Skill frontmatter

license: Apache-2.0

Work with this as data

Every skill here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for agent skills

4 MCP tools reach this
  • find_skillsBrowse and filter every skill in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This skill
curl "https://apis.io/api/v1/skills/okteto-preview"
All agent skills
curl "https://apis.io/api/v1/skills?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.