sites-hosting

Generated source view for the actual executable engineering/sites-hosting skill. The durable routing article is Cloud, Data, and Service Skills. Source: skills/engineering/sites-hosting/SKILL.md

Runtime Source

Bundled Resources

No bundled resource files.

Description

Host websites with Sites. Always use after sites-building, and use for website publishing, deployment, hosting management, or projects containing .openai/hosting.json.

Skill Source

---
name: sites-hosting
description: Host websites with Sites. Always use after `sites-building`, and use for website publishing, deployment, hosting management, or projects containing `.openai/hosting.json`.
origin: codex-plugin
source_slug: "openai-bundled/sites/sites-hosting"
source_repo: "openai-bundled/sites"
source_version: "0.1.21"
---

# Sites Hosting

Use this skill for local preparation of deployable Sites source and build artifacts. Use the Sites
connector and tool descriptions as the source of truth for site creation, environment variables,
source credentials, versions, deployments, and access control.

Do not finish deployable site work with only a local build unless the user explicitly asks to
keep the work local. Complete the hosting workflow described by the connector, or
report the concrete blocker and ask for the action needed to continue.

## Plan Continuity

When `update_plan` is available, continue the plan created by `sites-building`
through source preparation, version saving, deployment, and verification. Do
not replace the plan when transitioning from building to hosting.

For a standalone multi-step hosting request without an existing plan, call
`update_plan` before source preparation. Make its concise milestones describe
the publishing work in plain language, such as preparing the site, confirming
access, publishing it, and verifying the live link. Group source preparation,
credentials, commits, artifacts, version saving, deployment calls, and status
polling beneath those phases instead of exposing them as plan steps. Keep
exactly one step `in_progress`, preserve the original wording unless scope
changes, update the plan whenever the active step changes, and use the tool
itself instead of a prose checklist. Skip plan creation for a single read-only
hosting lookup.

## Configuration Contract

Store hosting metadata in `.openai/hosting.json`.

- `project_id`: the persisted identifier returned by `create_site`. Omit it until the site is created.
- `d1`: optional logical Cloudflare D1 binding name.
- `r2`: optional logical Cloudflare R2 binding name.

Runtime environment values are managed through the Sites connector, not in
`.openai/hosting.json`. Keep local `.env` and `.env.example` keys aligned with the runtime keys
needed for local development.

## Compatible Projects

Prepare sites that can build deployment artifacts for Cloudflare Workers.

- Prefer this plugin's bundled vinext starters for new sites.
- For existing Next.js sites, use a Cloudflare Workers-compatible build path such as OpenNext
  when needed.
- For other frameworks, use the site's Cloudflare-compatible build path when one exists.
  Refer to Cloudflare's web application framework guides:
  https://developers.cloudflare.com/workers/framework-guides/web-apps/
- Do not use frameworks that cannot produce Cloudflare Worker deployment artifacts.

## Preview and Browser Gate

- Ensure the visible `open_in_codex` preview handoff from `sites-building` has been attempted before
  validation, packaging, or deployment. If it has not, perform that exact handoff now. A browser
  handoff failure does not block deployment: report it, do not claim the preview is open, and
  continue. Server, build, artifact, and deployment failures still follow their normal gates.
- Run browser UI testing or visual QA only when the user explicitly requests it. Otherwise omit it
  from the plan and perform no browser inspection or interaction, even when there is a good reason.
- Unless the user explicitly requests a Sites deployment thumbnail, do not launch, connect to,
  resize, inspect, or control a browser to produce one. A missing screenshot is valid and must not
  block validation, version saving, or deployment.

## Local Validation

Before preparing a version artifact:

1. If the D1 schema changed, generate and inspect the local migration output.
2. Run the site's deployment build command, usually `npm run build`. If `package.json` defines a
   Cloudflare-specific deployment build, use that instead.
3. Fix validation failures before continuing.

## Source Preparation

Sites versions record a Git commit SHA. Prepare and push the exact source state used for the
deployment build before saving a version through the connector.

- Reuse the source credential returned by `create_site` or
  `create_source_repository_write_credential` until it expires, supplying it through a
  per-command HTTP authorization header.
- Do not add the credential to a Git remote URL or Git configuration.
- Use the pushed branch-head commit SHA as the version's `commit_sha`.

## Artifact Preparation

Prepare the uploaded artifact from the exact source state represented by `commit_sha`.

Treat `public/screenshot.jpeg` as an optional deployment thumbnail. During normal hosting, do not
create, refresh, or delete it; preserve an existing file unchanged. Only create or refresh it when
the user explicitly requests a Sites deployment thumbnail. A generic screenshot request does not
imply a deployment-thumbnail update.

For an explicitly requested Sites deployment thumbnail, use a representative state of the final
working implementation, not a source mock. Capture the visible browser viewport once at `1200x750`
(`16:10`), reset any temporary viewport override, and keep the canonical filename and location.
Do not inspect, compare, or iterate on the result unless the user also requested UI QA. If capture
is unavailable or fails, report it truthfully and continue deployment.

1. Stage the current build output in a temporary directory with `dist/` as the archive root.
2. If `.openai/hosting.json` is not already packaged by the build, copy it to
   `dist/.openai/hosting.json`.
3. If `drizzle/` exists and is not already copied, copy it to `dist/.openai/drizzle/`.
4. Verify the staged artifact contains:
   - `dist/server/index.js`
   - `dist/client/**` or `dist/server/public/**` when static assets exist
   - `dist/.openai/hosting.json`
   - `dist/.openai/drizzle/**` when migrations exist
5. Create a tar archive from the staged directory, for example:
   `tar -C "$staged_root" -czf "$archive_path" dist`.

Use the connector's parameter descriptions for the complete archive validation contract and the
save and deployment flow.

## Deployment Selection

After saving a site version, deploy it unless the user explicitly asked to keep the work local.

1. If `deploy_private_site_version` is available in the current tool catalog, call it first for the
   normal Sites flow. It verifies owner-only access server-side and deploys only when the current
   caller is the sole explicitly allowed viewer and no groups are allowed.
2. If `deploy_private_site_version` is unavailable, or private deployment fails because the site is
   shared, public, or cannot be verified as owner-only, do not call `deploy_site_version`
   automatically. Ask the user to approve deploying the site to its configured audience.
3. Use `deploy_site_version` only after the user explicitly requests or approves deploying the
   shared, public, or access-unverified site.
4. For either deployment tool, poll `get_deployment_status` until the deployment reaches a terminal
   state before reporting completion.

## User-Facing Handoff

Treat the deployed Sites URL as the user-facing deliverable. Do not attach or link the local site
source, build output, upload archive, or individual code files in chat unless the user explicitly
asks to receive those files. Keep temporary packaging artifacts out of user-facing output folders.
After a successful deployment, return the deployed URL and a concise summary of the result.

---

Timeline

• 2026-07-15 | Generated a browseable source page from the actual executable skill file. Source: skills/engineering/sites-hosting/SKILL.md