Kamal: How to integrate with GitHub Actions using multiple destinations

The recently introduced Kamal tool is very powerful and easy to use, you can achieve full deployment automation when it is integrated into the CI/CD pipelines. I'm going to walk you through how to run it automatically on GitHub Actions with multiple destinations (eg. staging and production).

Pipeline workflows:

Event	Action
Push to `main` (PR merged)	Desploy to Staging
Publish release (Tag created)	Deploy to Production

Requirements

Setup your app secrets in your repo for both environments (staging and production) in this tutorial they are prefixed by STG_ and PROD_.
Make sure you have created SSH_PRIVATE_KEY, KAMAL_REGISTRY_USERNAME and KAMAL_REGISTRY_PASSWORD secrets.

GitHub Action files

.github/
├─ workflows/
   ├─ job-deploy-kamal.yml
   ├─ workflow-deploy-production.yml
   ├─ workflow-deploy-staging.yml

job-deploy-kamal.yml is the shared job where Kamal runs
workflow-deploy-production.yml acts as a trigger for production
workflow-deploy-staging.yml acts as a trigger for staging

`job-deploy-kamal.yml`

name: Job - Deploy to Kamal

on:
  workflow_call:
    inputs:
      kamal-destination:
        required: true
        type: string
    secrets:
      KAMAL_REGISTRY_USERNAME:
        required: true
      KAMAL_REGISTRY_PASSWORD:
        required: true
      SSH_PRIVATE_KEY:
        required: true
      DATABASE_URL:
        required: true
      QUEUE_DATABASE_URL:
        required: true
      SECRET_KEY_BASE:
        required: true

env:
  DOCKER_BUILDKIT: 1
  KAMAL_REGISTRY_USERNAME: ${{ secrets.KAMAL_REGISTRY_USERNAME }}
  KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
  # App secrets
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  QUEUE_DATABASE_URL: ${{ secrets.QUEUE_DATABASE_URL }}
  SECRET_KEY_BASE: ${{ secrets.SECRET_KEY_BASE }}

jobs:
  deploy:
    name: kamal deploy
    timeout-minutes: 10
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true

      - uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.KAMAL_REGISTRY_USERNAME }}
          password: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - run: gem install kamal

      - run: kamal lock release -d ${{ inputs.kamal-destination }}

      - run: kamal deploy -d ${{ inputs.kamal-destination }}

`workflow-deploy-staging.yml`

name: Workflow - Deployment (staging)

on:
  push:
    branches:
      - main

concurrency:
  group: deployment-staging
  cancel-in-progress: false

jobs:
  deploy:
    uses: ./.github/workflows/job-deploy-kamal.yml
    with:
      kamal-destination: staging
    secrets:
      KAMAL_REGISTRY_USERNAME: ${{ secrets.KAMAL_REGISTRY_USERNAME }}
      KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
      SSH_PRIVATE_KEY: ${{ secrets.STG_SSH_PRIVATE_KEY }}
      DATABASE_URL: ${{ secrets.STG_DATABASE_URL }}
      QUEUE_DATABASE_URL: ${{ secrets.STG_QUEUE_DATABASE_URL }}
      SECRET_KEY_BASE: ${{ secrets.STG_SECRET_KEY_BASE }}

`workflow-deploy-production.yml`

name: Workflow - Deployment (production)

on:
  release:
    types: [published]

concurrency:
  group: deployment-production
  cancel-in-progress: false

jobs:
  deploy:
    uses: ./.github/workflows/job-deploy-kamal.yml
    with:
      kamal-destination: production
    secrets:
      KAMAL_REGISTRY_USERNAME: ${{ secrets.KAMAL_REGISTRY_USERNAME }}
      KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
      SSH_PRIVATE_KEY: ${{ secrets.PROD_SSH_PRIVATE_KEY }}
      DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
      QUEUE_DATABASE_URL: ${{ secrets.PROD_QUEUE_DATABASE_URL }}
      SECRET_KEY_BASE: ${{ secrets.PROD_SECRET_KEY_BASE }}

Kamal files

.kamal/
├─ secrets-common
config/
├─ deploy.production.yml
├─ deploy.staging.yml
├─ deploy.yml

`secrets-common`

KAMAL_REGISTRY_USERNAME=$KAMAL_REGISTRY_USERNAME
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
DATABASE_URL=$DATABASE_URL
QUEUE_DATABASE_URL=$QUEUE_DATABASE_URL
SECRET_KEY_BASE=$SECRET_KEY_BASE

`deploy.yml`

service: myapp
image: myorg/myapp

registry:
  username:
    - KAMAL_REGISTRY_USERNAME
  password:
    - KAMAL_REGISTRY_PASSWORD

proxy: 
  ssl: true
  app_port: 3000

builder:
  arch: amd64

volumes:
  - "app_storage:/app/storage"

`deploy.production.yml`

servers:
  web:
    - 192.168.0.1
  job:
    hosts:
      - 192.168.0.1
    cmd: bin/jobs

proxy: 
  host: api.myapp.com

env:
  clear:
    RAILS_LOG_TO_STDOUT: 1
    WEB_CONCURRENCY: 2
    JOB_CONCURRENCY: 1
    SOLID_QUEUE_IN_PUMA: true
  secret:
    - DATABASE_URL
    - QUEUE_DATABASE_URL
    - SECRET_KEY_BASE

`deploy.staging.yml`

servers:
  web:
    - 192.168.0.2
  job:
    hosts:
      - 192.168.0.2
    cmd: bin/jobs

proxy: 
  host: api-staging.myapp.com

env:
  clear:
    RAILS_LOG_TO_STDOUT: 1
    WEB_CONCURRENCY: 0
    JOB_CONCURRENCY: 1
    SOLID_QUEUE_IN_PUMA: true
  secret:
    - DATABASE_URL
    - QUEUE_DATABASE_URL
    - SECRET_KEY_BASE

Blog