GitHub Actions

The official haloydev/deploy-action GitHub Action handles installing the Haloy CLI and running haloy deploy in your CI pipeline. Push to main, and your app deploys.

Quick Start

Add this workflow file to your repository:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}

That’s it. Every push to main will build and deploy your application.

Setup

1. Get Your API Token

On your server, run:

sudo haloyd config get api-token
sudo haloyd config get api-token

2. Add the Token to GitHub

Go to your repository on GitHub
Navigate to Settings > Secrets and variables > Actions
Click New repository secret
Name: HALOY_API_TOKEN
Value: paste your API token

3. Add the Workflow File

Create .github/workflows/deploy.yml in your repository with the workflow shown above, then push to main.

Action Inputs

Input	Required	Default	Description
`api-token`	Yes		Haloy API token for server authentication
`target`	No		Deployment target name (for multi-target configs)
`config`	No	`./haloy.yaml`	Path to config file
`version`	No	`latest`	Haloy CLI version to install

Examples

Deploy a Specific Target

- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    target: production
- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    target: production

Custom Config Path

- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    config: ./deploy/haloy.yaml
- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    config: ./deploy/haloy.yaml

Pin CLI Version

- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    version: v0.1.0
- uses: haloydev/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    version: v0.1.0

Deploy Staging and Production

name: Deploy
on:
  push:
    branches: [main, staging]

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/staging'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
          target: staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
          target: production
name: Deploy
on:
  push:
    branches: [main, staging]

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/staging'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
          target: staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
          target: production

Deploy with Manual Approval

name: Deploy Production
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
name: Deploy Production
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}

To require approval, configure a deployment protection rule on the production environment in your repository settings.

Run Tests Before Deploying

name: Test and Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}
name: Test and Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haloydev/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}

How It Works

The action downloads the Haloy CLI for the runner’s platform, sets HALOY_API_TOKEN, and runs haloy deploy --no-logs with any flags you specify. The Docker image is built on the GitHub Actions runner and uploaded to your server via the Haloy API, the same way haloy deploy works from your local machine.

Security

Your API token is stored as a GitHub Actions secret and never exposed in logs. It authenticates using the same bearer token mechanism as the CLI, so no additional server-side configuration is needed.

Without the Action

If you’d rather skip the action, you can install the CLI directly:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      HALOY_API_TOKEN: ${{ secrets.HALOY_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Install Haloy
        run: |
          curl -fsSL -o /usr/local/bin/haloy \
            https://github.com/haloydev/haloy/releases/latest/download/haloy-linux-amd64
          chmod +x /usr/local/bin/haloy
      - run: haloy deploy --no-logs
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      HALOY_API_TOKEN: ${{ secrets.HALOY_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Install Haloy
        run: |
          curl -fsSL -o /usr/local/bin/haloy \
            https://github.com/haloydev/haloy/releases/latest/download/haloy-linux-amd64
          chmod +x /usr/local/bin/haloy
      - run: haloy deploy --no-logs

This works with any CI provider, not just GitHub Actions.

Next Steps

Server Authentication for token management details
Multi-Server Deployments for deploying to multiple servers
Deployment Strategies for zero-downtime deployments