Hyphen
Log In

Deploy with GitHub Actions

Learn how to automate deployments using the Hyphen Deploy GitHub Action, including prerequisites, setup, parameters, outputs, and example workflows.

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.

Table of Contents

Prerequisites

Before using the deploy action, ensure that:

  • The Setup hx Command Line action has been run.
  • Your repository contains a .hx file at the root (created by hx init), or you supply the project, app, and organization values as action inputs.
  • A deployment has been configured for the project environment you wish to deploy.
  • Your cloud provider has been connected to Hyphen and the project has ready container registry and cloud workspace connections for each cloud the deployment targets.
  • A Hyphen API key is available with appropriate permissions for deployment.

A Dockerfile will be used if present, and if not, Hyphen Code will generate one automatically. See Builds for more details.

Setting up GitHub Secrets

Add your Hyphen API key to your repository's secrets:

  1. In your GitHub repository, go to Settings > Secrets and variables > Actions.
  2. Click New repository secret.
  3. Name: HYPHEN_API_KEY.
  4. Value: Your Hyphen API key from the Hyphen App.
  5. Click Add secret.

Parameters

Use environment to select an environment in the project linked in the checked-out .hx file. Without this input, the CLI selects that project's environment of type development, regardless of its name or the browser selection.

  • environment (optional): Environment ID or alternate ID, such as production (maps to --env). Omit it to select the environment of type development.
  • project (optional): Project ID or alternate ID (maps to --project). Used when .hx has no project selected; the project recorded in .hx takes precedence.
  • organization (optional): Organization ID (maps to --organization).
  • apps (optional): A comma-separated list of apps to deploy, each optionally specifying a build (e.g., app1,app2:latest,app3:abld_xxx).
  • noBuild (optional): Skip the build step and use the latest build. Defaults to false.
  • dockerfile (optional): Path to the Dockerfile (e.g., ./Dockerfile or ./docker/Dockerfile.prod).
  • preview (optional): Preview name to deploy to (maps to --preview).
  • prefix (optional): Host prefix for the preview deployment (maps to --prefix). Required when creating a preview; also identifies an existing preview when names repeat.
  • path (optional): Path, if changed from the default, where the repository has been cloned.
  • verbose (optional): Enable verbose logging. Defaults to false.

For compatibility with existing workflows, deploymentId remains available and accepts a deployment ID or alternate ID. When supplied, it selects the deployment directly and the project and environment inputs do not select the target. Prefer the environment input with the project linked in .hx for new workflows.

Outputs

The action sets the following step outputs, available to subsequent steps as steps.<id>.outputs.<name>:

  • 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.

Example Usage

- 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 }}

- 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 }}"

Deploying on Push to Main and on Release

This workflow deploys to development when a PR is merged to main, and to production when a release is created.

name: Deploy Application

on:
  push:
    branches:
      - main
  release:
    types: [created]

jobs:
  deploy-dev:
    name: Deploy to Development
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Deploy to Development
        id: deploy
        uses: Hyphen/deploy-action@v1
        with:
          environment: development

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

  deploy-prod:
    name: Deploy to Production
    if: github.event_name == 'release'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

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

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

Pulling ENV Secrets Before Deploying

If your deployment depends on Hyphen ENV secrets, add the ENV action before the deploy step:

- name: Checkout
  uses: actions/checkout@v4

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

- name: Pull ENV secrets
  uses: Hyphen/env-action@v1
  with:
    hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }}
    environment: production
    outputs: files

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

How It Works

When the deploy action runs:

  1. The Hyphen CLI builds your Docker image (Hyphen Code generates a Dockerfile automatically if none exists).
  2. The image is pushed to every ready container registry on the project (not limited to the clouds on this deployment).
  3. The application is deployed to your cloud providers according to the project environment deployment settings. Each cloud instance uses the artifact whose target matches that cloud.
  4. Build, release, and verification steps are executed.
  5. The action waits for the deployment run to finish and exposes the result to subsequent steps via outputs.

For details on the build process, including Hyphen Code's Dockerfile auto-generation, see Builds.

Next Steps