deployctl

Compatibility Warning

deployctl is specifically designed for managing Deno Deploy Classic organizations and projects.

If you are using a new Deno Deploy organization, you should use the deno deploy command built directly into the Deno Runtime instead of deployctl.

To deploy a project, navigate to your project directory and run the deploy command. For a quick test, you can use the provided hello-world example.

cd examples/hello-world
deployctl deploy

To install deployctl globally using JSR, run the following command. Ensure you have Deno installed before proceeding.

deno install -gArf jsr:@deno/deployctl

You can find concrete implementation examples for deployctl in the following directories within the repository:

• Hello-World: A basic starting point.
• Link Shortener: A practical application example.
• Fresh Hello-World: An example using the Fresh framework.

For more extensive tutorials and use cases, refer to the official Deno Deploy docs.

To deploy to Deno Deploy using GitHub Actions, include denoland/deployctl@v1 as a step in your workflow.

Prerequisites:

1. Link your GitHub repository to your Deno Deploy project.
2. In your Deno Deploy project settings (at https://dash.deno.com), select the "GitHub Actions" deployment mode.
3. You do not need to configure any secrets manually.

Required Permissions: You must grant the job id-token: write permission to allow authentication with Deno Deploy.

jobs:
  deploy:
    permissions:
      id-token: write # required
      contents: read
    steps:
      # ... your deployctl step here

You can automate deployments using the denoland/deployctl GitHub Action.

Required Permissions: To allow the action to authenticate with Deno Deploy, the job must have id-token: write permissions.

Configuration Options:

• project: The name of the project on Deno Deploy.
• entrypoint: The entrypoint file to deploy (e.g., main.ts).

name: Deploy

on: push

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      id-token: write # Required for Deno Deploy authentication
      contents: read

    steps:
      - name: Clone repository
        uses: actions/checkout@v4

      - name: Deploy to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: my-project # the name of the project on Deno Deploy
          entrypoint: main.ts # the entrypoint to deploy

When an API request fails, the client throws an APIError. This error contains a code (e.g., projectNotFound, deploymentNotFound) and an optional xDenoRay string.

The x-deno-ray value is a unique identifier used for debugging. If you encounter frequent errors, you should contact deploy@deno.com and provide this value.

You can configure the client to always print the x-deno-ray header (even on successful requests) by setting alwaysPrintXDenoRay: true in the APIConfig.

For security reasons, Deno Deploy does not currently support deployments triggered by pull requests originating from forks. If a pull_request event is detected from a fork, the action will skip the deployment and set the following outputs to empty strings:

• deployment-id = ""
• url = ""

deployctl automatically searches for configuration files starting from the current working directory and moving up through parent directories (ancestors).

It looks for the following filenames in order:

1. deno.json
2. deno.jsonc

If a configuration file is found, deployctl reads the deploy property to determine the active deployment settings. If no configuration file is found in the current or any parent directory, deployctl will operate without persisted settings.