GitHub Action to Run a Hyphen Deployment using the Hyphen CLI

This action runs a Hyphen deployment from a GitHub workflow. It wraps the hx deploy CLI command, waits for the deployment run to finish, and exposes the resulting deployment ID, run ID, URL, and status as step outputs so subsequent steps can act on them.

More information on Hyphen deployments can be found in our docs.

Inputs

All inputs are optional. When omitted, the CLI falls back to the .hx metadata file at the repository root (organization, project, and app IDs) and its auto-detection of the development environment.

Input	Description	Default
deploymentId	Specific deployment ID to run (e.g. depl_abc123). If omitted, deploys the development environment.
environment	Environment to deploy (maps to --env).
project	Project to deploy (maps to --project). Defaults to project_id from .hx config.
organization	Organization ID (maps to -o / --organization).
apps	Comma-separated list of apps to deploy, each optionally specifying a build (e.g. app1,app2:latest).
noBuild	Skip the build step and use the latest build.	false
dockerfile	Path to Dockerfile (e.g. ./Dockerfile or ./docker/Dockerfile.prod).
preview	Preview name to deploy to (maps to -r / --preview).
prefix	Host prefix for the preview deployment (maps to -x / --prefix).
path	Path, if changed from the default, where the repository has been cloned.
verbose	Enable verbose logging.	false

Outputs

Output	Description
deployment-id	The deployment ID that was run.
run-id	The deployment run ID.
deployment-url	URL to the deployment run in the Hyphen dashboard.
status	Final status of the deployment run (succeeded | failed | canceled).
reason	Failure reason when status is not succeeded. Empty on success.

The action also writes a short summary to $GITHUB_STEP_SUMMARY — the deployment status, the failure reason if any, and a clickable link to the deployment run in the Hyphen dashboard — so the run-summary panel of the GitHub Actions UI links straight to the deployment.

Usage

Important

The Hyphen CLI is required for this action to work. Install it on the runner first via the Setup Hyphen CLI Action.

steps:
  - name: Checkout
    id: checkout
    uses: actions/checkout@v4

  - name: setup hx CLI
    id: setup
    uses: Hyphen/setup-hx-action@v1
    with:
      apiKey: ${{ secrets.HYPHEN_API_KEY }}

  # Optional — only needed if your deployment depends on Hyphen ENV secrets.
  - name: Pull ENV secrets
    id: pull-env
    uses: Hyphen/env-action@v1
    with:
      hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }}
      environment: production
      outputs: files

  - name: Deploy
    id: deploy
    uses: Hyphen/deploy-action@v1
    with:
      environment: production

  - name: Report deployment URL
    run: echo "Deployed at ${{ steps.deploy.outputs.deployment-url }}"

For more information on the Hyphen CLI, see the CLI Documentation.

---

Developing the Action

Initial Setup

After you've cloned the repository to your local machine or codespace, you'll need to perform some initial setup steps before you can develop your action.

1. 🛠️ Install the dependencies

   npm install

2. 🏗️ Package the TypeScript for distribution

   npm run bundle

3. ✅ Run the tests

   npm test

Packaging the Action

TypeScript actions require you to commit the compiled version of the code (the dist/ folder). The Check-Dist action ensures the committed dist/ stays in sync with the source.

Version

For information about versioning your action, see Versioning in the GitHub Actions toolkit.

Publishing a New Release

This project includes a helper script, script/release, designed to streamline the process of tagging and pushing new releases for GitHub Actions.

GitHub Actions allows users to select a specific version of the action to use, based on release tags. This script simplifies this process by performing the following steps:

1. Retrieving the latest release tag: The script starts by fetching the most recent SemVer release tag of the current branch, by looking at the local data available in your repository.
2. Prompting for a new release tag: The user is then prompted to enter a new release tag. To assist with this, the script displays the tag retrieved in the previous step, and validates the format of the inputted tag (vX.X.X). The user is also reminded to update the version field in package.json.
3. Tagging the new release: The script then tags a new release and syncs the separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0, v2.1.2). When the user is creating a new major release, the script auto-detects this and creates a releases/v# branch for the previous major version.
4. Pushing changes to remote: Finally, the script pushes the necessary commits, tags and branches to the remote repository. From here, you will need to create a new release in GitHub so users can easily reference the new tags in their workflows.