Deno Deploy

This skill covers managing Deno Deploy cloud services using the built-in deno deploy command and the advanced deployctl utility.

Core Concepts (Deno 2.x / 2026)

• Integrated Build System: Deno Deploy now handles builds (install + build steps) on its own infrastructure with automatic caching and live logs.
• Deployment Contexts: Environment variables and configurations are separated into Production, Development (Preview/Branch), and Build contexts.
• Runtime Permissions: Applications run with --allow-all by default, supporting subprocesses, FFI, and full npm compatibility.
• Static Assets: First-class support for static files (Vite, SSG) which are automatically cached by the Deno Deploy CDN.

Built-in deno deploy

The deno deploy command is integrated into the Deno CLI and is suitable for basic deployment tasks.

Commands

• deno deploy [OPTIONS] [entrypoint]: Deploy the project. If entrypoint is omitted, it's guessed from deno.json or files.
• deno deploy create: Create a new application.
• deno deploy env: Manage environment variables in the cloud (supports contexts).
• deno deploy logs: Stream live logs from a deployed application.
• deno deploy switch: Switch between organizations and applications.
• deno deploy sandbox: Interact with sandboxes.
• deno deploy setup-aws / setup-gcp: Configure cloud connections (OIDC).
• deno deploy logout: Revoke the Deno Deploy authentication token.

Advanced Management via deployctl

For more granular control, including listing deployments and managing projects, use deployctl.

Installation

deno install -gArf jsr:@deno/deployctl

Projects and Deployments

• deployctl list: List all deployments for the current project.
• deployctl projects list: List all projects in your account.
• deployctl deployments show <id>: Show detailed information for a specific deployment/build.
• deployctl redeploy --deployment=<id>: Roll back or redeploy a specific version.
• deployctl projects create <name>: Create a new project.
• deployctl projects delete <name>: Delete a project.

Troubleshooting & Best Practices

Local Debugging Protocol (CRITICAL)

ALWAYS test deployment commands locally before updating CI/CD workflows.

1. Use the same token as in CI/CD.
2. Verify file uploading and revision creation.
3. Check for IsADirectory errors (often caused by missing .gitignore entries like .playwright-browsers/).

Unstable APIs (Deno KV, etc.)

If your app uses Deno.openKv() or other unstable APIs:

• Local run: Requires --unstable-kv.
• Deno Deploy (CLI): The deno deploy command DOES NOT support --unstable-kv or --unstable flags.
• Deno Deploy (Runtime): You MUST enable unstable features in deno.json:

  {
    "unstable": ["kv"]
  }

  Without this, the app will fail with TypeError: Deno.openKv is not a function in the cloud.

Exclusions and File Management

• Native CLI: deno deploy DOES NOT support the --exclude flag.
• Solution: Use .gitignore to exclude files and directories. All files not ignored by git will be uploaded.
• Large Directories: Always exclude large local-only directories (like .playwright-browsers/) to avoid IsADirectory errors and slow uploads.

CI/CD with GitHub Actions

Recommended workflow for complex projects:

1. Permissions: If using OIDC (automatic auth), ensure correct permissions:

   permissions:
     id-token: write
     contents: read

2. Native CLI: Prefer native deno deploy over deployctl Action if you encounter authorization issues (The bearer token is invalid).
3. Explicit Entrypoint: Always specify the entrypoint file to avoid guessing errors in CI.

   - name: Upload to Deno Deploy
     run: deno deploy --app=my-app --token=${{ secrets.DENO_DEPLOY_TOKEN }} --prod main.ts

Private Dependencies (npm/JSR)

Deployments from local console may fail with Internal Server Error if the project uses private npm packages.

• Cause: Deno Deploy build servers cannot access your local private registry credentials.
• Solution: Use GitHub Actions. It can authenticate against private registries before deploying.

Common Workflows

Deploying to Production (Explicit)

deno deploy --app=my-app --prod main.ts

Managing Environment Variables

deno deploy env set MY_VAR=value --context=production