GitHub Actions

Deploy your application automatically on every push using the official haloy/deploy-action GitHub Action. The action installs the Haloy CLI, authenticates with your server, and runs haloy deploy in your CI pipeline.

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: haloy/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: haloy/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: haloy/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    target: production
- uses: haloy/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    target: production

Custom Config Path

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

Pin CLI Version

- uses: haloy/deploy-action@v1
  with:
    api-token: ${{ secrets.HALOY_API_TOKEN }}
    version: v0.1.0
- uses: haloy/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: haloy/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: haloy/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: haloy/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: haloy/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: haloy/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: haloy/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: haloy/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: haloy/deploy-action@v1
        with:
          api-token: ${{ secrets.HALOY_API_TOKEN }}

How It Works

The GitHub Action:

Detects the runner OS and architecture
Downloads the Haloy CLI binary from GitHub releases
Sets the HALOY_API_TOKEN environment variable
Runs haloy deploy --no-logs with any additional flags you specify

The Docker image is built on the GitHub Actions runner and uploaded to your server via the Haloy API, using the same mechanism as haloy deploy from your local machine.

Security

The API token is stored as a GitHub Actions secret and never exposed in logs
Authentication uses the existing bearer token mechanism on the server
No additional server-side configuration is required

Without the Action

You can also use the Haloy CLI directly in any CI environment:

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