okteto-preview

Okteto プレビュー環境スキル

プレビュー環境とは、通常はプルリクエストのライフサイクルに紐づき、Git ブランチからデプロイされる、実稼働環境に近いアプリケーションの稼働インスタンスです。Okteto はプレビューにちなんだ名前の専用ネームスペースにデプロイし、共有可能な URL を提供します。そのため、レビュアー、PM、関係者はローカルで何も設定することなく、実際の機能を試せます。

このスキルでは、1 つのオーナーシップモデルに関わる 2 つの作業を扱います。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 ブランチ（サーバー側でクローン）
ライフサイクル	あなたが管理します。作業が続く限り稼働します	プルリクエストに紐づきます。作成時に作成され、クローズ時に削除されます
対象者	作業を行うあなた／エージェント	レビュアー、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 がデフォルトだと思い込まないでください。デフォルトではありません。個人用プレビューを特定の相手と共有するには、CLI ではなくダッシュボードページ（/previews/<name>）を使います。共有できるのはオーナーまたは管理者だけです。
• --branch <branch> — デフォルトは、実行元のチェックアウトの現在のブランチです。
• --repository <url> — デフォルトは、現在のリポジトリのリモート URL です。チェックアウトしていないリポジトリをデプロイするときは、明示的に指定してください。
• --var KEY=VALUE — マニフェストのデプロイコマンドに変数を渡します。複数の変数を渡す場合は、このフラグを繰り返し指定してください。
• --sourceUrl <pr-url> — プル／マージリクエストの HTTPS URL です。ダッシュボードの「Previews」リストで PR にリンクします。
• --timeout — デフォルトは 5m0s です。大規模なスタックの場合は延長してください（-t 15m）。
• --file — Okteto マニフェストがデフォルトの場所にない場合に、そのパスを指定します。

プレビューの命名

プレビュー名はネームスペース名になるため、有効な RFC 1123 DNS ラベルである必要があります。最大 63 文字で、小文字、数字、- のみを使用でき、先頭と末尾は文字または数字にしてください（正規表現 ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$）。大文字、ピリオド、アンダースコアは使用できません。また、予約済みの kube- プレフィックスは避けてください。ブランチから安全なスラッグを作るには、okteto スキルがネームスペース名を生成する方法に従います。

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。ブランチごとにプレビューを 1 つ作成します。

PR 番号の取得方法： CI ではイベントに含まれています（${{ github.event.number }}）。チェックアウト済みのブランチでは、gh pr view --json number --jq .number を実行します。まだ PR が存在しない場合は、番号を作り出さないでください。ブランチをキーにした名前を使うか、先に PR を作成してからプレビューをデプロイしてください。

名前を省略すると、CLI がランダムな名前を生成します。手動で簡単な実験をするには問題ありませんが、それ以外の用途には適していません。再デプロイすると、既存のプレビューが更新されず、2 つ目のプレビューが作成されます。

---

エンドポイントの取得と 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 が PR コメントとして URL とエンドポイントを自動的に投稿します。その上に gh pr comment ステップを追加しないでください。

---

CI でのプレビュー

GitHub Actions：okteto/deploy-preview

標準的な 2 つのワークフローです。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 Admin Access Token）。GITHUB_TOKEN は GitHub によって自動的に設定されます。

okteto/deploy-preview の入力項目：name（必須）、scope（デフォルトは global）、variables（カンマ区切りの VAR1=VAL1,VAR2=VAL2）、file、branch（デフォルトはアクションをトリガーしたブランチ）、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 を実行し、ブランチが削除されたとき、または MR がマージされたときに stop-review ジョブで okteto preview destroy review-$CI_COMMIT_REF_SLUG を実行します。レビュー担当者が GitLab からプレビューを開けるように、ジョブの environment.url にプレビュー URL を渡します。

---

プレビューの確認、スリープ、再開

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

スリープするとプレビューとその構成は維持され、再開すると復元されます。まだ必要とする人がいる可能性のあるプレビューで、リソースの節約が目的なら、destroy より sleep を優先してください。管理者はダッシュボードでプレビューを 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> を実行してください」と明記します。スリープとプラットフォームのガベージコレクションは、リソース保護のための最後の手段であり、担当者の代わりにはなりません。

状況	エージェントは削除してもよいですか？
エージェントがこのセッションで自身のタスクのために作成したプレビュー	はい — 作業が完了し、URL が不要になったら、自分で削除します
CI が所有するプレビュー（例：ワークフローが管理する pr-<number>）	いいえ — PR クローズ時のワークフローが削除を担当します。レビュー中に削除すると、レビュー担当者が使っているリンクが機能しなくなります
他の人が作成したグローバルプレビュー	明示的な指示がない限り、絶対に削除しないでください
他の人の個人用プレビュー	絶対に削除しないでください — そもそも削除できるのは管理者または所有者だけです

• 共同作業モードでは、コマンドを提示し、開発者自身に実行してもらいます。「プレビューを削除するには、次を実行してください：okteto preview destroy pr-1234」。
• 自律モードでは、このセッションで作成したプレビューは、タスクで不要になった時点で自分で削除できます。これは okteto スキルのワークツリー名前空間と同じ「自分で作成したものは、自分で削除する」ルールです。ただし、URL を PR やスレッドに投稿した場合は、レビュー担当者がまだ使っている可能性があります。その場合は、プレビューを実行したままにする（または okteto preview sleep <name> を実行する）か、代わりに削除コマンドを報告してください。自分が作成していないプレビューは、明示的な許可、文書化されたクリーンアップポリシー、またはこの実行のパイプラインによる所有がない限り、削除しないでください。
• 再試行に destroy を使わないでください。 失敗したプレビューや古くなったプレビューは、同じ名前で再デプロイして修正します。okteto preview deploy <name> は既存のプレビューを更新します。

---

CLI クイックリファレンス

コマンド	協調型	自律型	目的
okteto preview deploy <name>	エージェント	エージェント	プッシュ済みブランチからプレビューをデプロイします
okteto preview endpoints <name>	エージェント	エージェント	プレビュー URL を一覧表示します（デフォルトは -o json、PR コメントには -o md）
okteto preview list	エージェント	エージェント	プレビューのステータスとスコープを確認します
okteto preview sleep <name>	エージェント（自身のもの）	エージェント（自身のもの）	自分が所有するプレビューをスケールダウンします
okteto preview wake <name>	エージェント	エージェント	スリープ中のプレビューを起動します
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 preview endpoints <name> ではなく okteto endpoints を実行する。 前者はプレビューではなく、現在のコンテキストでアクティブな名前空間を対象にします。
• プレビューワークフローで cancel-in-progress: true を設定する。 実行中のデプロイをキャンセルすると、プレビューの状態が不整合になり、リソースが残ります。cancel-in-progress: false にして、PR ごとにキューに入れてください。
• CI で URL を二重に投稿する。 GITHUB_TOKEN が設定されている場合、okteto/deploy-preview はすでに PR にコメントを投稿します。CI 外からデプロイする場合に限り、独自の gh pr comment を追加してください。
• 自分が所有していないプレビューを削除する。 CI が所有するもの、共有／グローバルなもの、他のユーザーのプレビューは、明示的な指示がない限り削除できません。okteto スキルの okteto destroy と同じルールです。
• 壊れたプレビューを「修正」するために削除する。 代わりに同じ名前で再デプロイしてください。その場で更新されます。