Hyphen
Log In

Introduction

Deploy

ENV Secrets Management

Feature Flags

URL Shortening

Net.Info

Integrations

GitHub Actions

Policies

Deploy with GitHub Actions

Guide to deploying applications using GitHub Actions with 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.

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 a container registry has been created for the project.
  • 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

All parameters are optional. When omitted, the CLI falls back to values from the .hx file at the repository root and auto-detects the development environment.

  • deploymentId (optional): A specific deployment ID to run (e.g., depl_abc123). When omitted, deploys the development environment.
  • environment (optional): The environment to deploy (maps to --env).
  • project (optional): The project to deploy (maps to --project). Defaults to project_id from the .hx file.
  • organization (optional): The 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).
  • path (optional): Path, if changed from the default, where the repository has been cloned.
  • verbose (optional): Enable verbose logging. Defaults to false.

Outputs

The action sets the following step outputs, available to subsequent steps as steps..outputs.:

  • 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 your project's container registry (configured during setup).
  3. The application is deployed to your cloud provider according to the project environment deployment settings.
  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