Deployment Run Methods in Hyphen

A deployment run on Hyphen is the act of running a specific deployment configuration. Each time you run a deployment, Hyphen will return a unique URL so that you and your team can preview changes in a live environment.

GitHub

The most common way to run a deployment is by pushing code or opening a pull request to a Hyphen-connected Git repository. When you import a Git repository to Hyphen, you can setup an action so that each commit or pull request automatically triggers a deployment run.

You can also create deployments from a Git reference using the Hyphen Dashboard if you need to deploy specific commits or branches manually.

For a detailed guide on setting up GitHub Actions workflows to automate deployments, see GitHub Actions Deployment.

CLI

Use the Hyphen CLI (hx) when you want to launch a deployment run directly from your terminal or a custom automation script. The CLI packages the code that is currently checked out locally, builds the artifacts that your deployment policy expects, and streams status updates until the run completes.

For details on the build process, see Builds.

hx deploy <deployment-policy-name-or-ID>

The ID of the deployment policy is available in the url when looking at the deployment policy detail.

Run the command from the repository root that was initialized with hx init. Replace <deployment-policy-id> with either the ID or the name of the deployment policy you want to execute. The CLI authenticates using the credentials saved during hx auth.

If you are authenticating in a CI/CD environment and need to authenticate using an API key, you can do so in 2 ways:

Use API Key

--use-api-key will look for the HYPHEN_API_KEY environment variable first and if not found it will prompt for the key.
```
hyphen auth -- use-api-key
```
Set API Key

--set-api-key VALUE will expect an inline value. The risk in using this method is just in exposing the secret in your terminal output, but it's provided for convenience.
```
hyphen auth --set-api-key VALUE
```

While the run is in progress the CLI shows each build, release, and verification step in the order they are executed. When the deployment finishes you will receive a link to the generated preview environment as well as the run ID, which you can use to inspect logs in the Dashboard or reference the run from follow-up automation.

REST API

Hyphen also exposes a REST API for triggering deployment runs programmatically. This is useful when you need to integrate deployments into an external build system, ticketing workflow, or release orchestration tool.

Create a run by sending an authenticated POST request to /api/organizations/{organizationId}/deployments/{deploymentId}/runs, using the deployment ID shown on the Deployment Policy detail page. The request body is optional; include it when you want to pin the run to specific build artifacts.

Each artifact entry must provide an appId and either a buildId (to reuse an existing Hyphen build) or a published container image reference:

curl -X POST "https://api.hyphen.ai/api/organizations/$HYPHEN_ORG/deployments/$DEPLOYMENT_ID/runs" \
  -H "Authorization: Bearer $HYPHEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "artifacts": [
          { "appId": "app_123", "buildId": "ab_456" },
          {
            "appId": "app_789",
            "artifact": {
              "type": "Docker",
              "image": { "uri": "gcr.io/my-project/custom-image:latest" }
            }
          }
        ]
      }'

The response contains the deployment run record, including its ID, current status, pipeline steps, and preview URL. Follow-up calls to GET /api/organizations/{organizationId}/deployments/{deploymentId}/runs/{runId} return the latest status, and PUT /api/organizations/{organizationId}/deployments/{deploymentId}/runs/{runId}/status (body { "status": "canceled" }) lets you cancel a run that is still in progress.

Dashboard

For ad-hoc deployments you can start a run directly from the Hyphen Dashboard:

Navigate to Deploy → Deployment Policies, then choose the policy you want to execute.
Select Run latest build and the latest build be used in the deployment run.
1. To run a previous build, open the dropdown men and select Run previous build...
2. Select the Deploy button to the corresponding with the commit SHA you want to deploy
Confirm the run to queue it. The status panel updates in real time and links to the preview environment once the deployment completes.

Dashboard-triggered runs behave the same way as runs started from Git pushes, the CLI, or the API—they appear in the deployment history, emit events, and reuse the configuration defined by the deployment policy.