Kamal Deploy Workflow

A reusable Gitea Actions workflow for deploying applications using Kamal.

Overview

This workflow provides a standardized way to deploy applications using Kamal with integrated secrets management through Bitwarden. It handles SSH key setup, secret retrieval, environment configuration, and deployment execution.

Usage

To use this workflow in your repository, reference it in your .gitea/workflows/ directory:

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

jobs:
  deploy:
    uses: git.qlic.nl/qlic/workflows/kamal/.gitea/workflows/deploy.yml@main
    secrets:
      ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
      certificate-pem: ${{ secrets.CERTIFICATE_PEM }}  # Optional: Custom SSL certificate (use fullchain)
      private-key-pem: ${{ secrets.PRIVATE_KEY_PEM }}  # Optional: Custom SSL private key
    with:
      environment: "production"
      warden-client-id: ${{ vars.WARDEN_CLIENT_ID }}
      warden-client-secret: ${{ secrets.WARDEN_CLIENT_SECRET }}
      warden-password: ${{ secrets.WARDEN_PASSWORD }}
      secrets: "8152c344-2e85-48dd-9e37-a631f952163f > DOT_ENV"

Required Inputs

Input	Description	Required	Default
environment	Target deployment environment	✅	-
warden-client-id	Bitwarden client ID	✅	-
warden-client-secret	Bitwarden client secret	✅	-
warden-password	Bitwarden password	✅	-
secrets	List of secret IDs and corresponding environment variable names (format: SECRET_ID > ENV_VAR)	✅	-

Optional Inputs

Input	Description	Required	Default
image	Container image to use for deployment	❌	git.qlic.nl/qlic/kamal:latest
username	Registry username	❌	${{ vars.REGISTRY_USERNAME }}
password	Registry password	❌	${{ vars.REGISTRY_PASSWORD }}
warden-server	Bitwarden server URL	❌	${{ vars.WARDEN_URL }}

Required Secrets

Secret	Description	Required
ssh-private-key	SSH private key for server access	✅
certificate-pem	Optional SSL certificate in PEM format	❌
private-key-pem	Optional SSL private key in PEM format	❌

Workflow Steps

1. Checkout code - Retrieves the repository code
2. Setup SSH agent - Configures SSH access using the provided private key
3. Get bitwarden secrets - Retrieves secrets from Bitwarden using the Warden action
4. Create .env file - Generates environment-specific secrets file
5. Append registry password - Adds Docker registry credentials
6. Add optional PEM secrets - Includes SSL certificates if provided
7. Boot accessories - Restarts Kamal accessories
8. Deploy - Executes the Kamal deployment

Environment Configuration

The workflow creates a .kamal/secrets.{environment} file containing:

• Secrets retrieved from Bitwarden (via DOT_ENV variable)
• Docker registry password (KAMAL_REGISTRY_PASSWORD)
• Optional SSL certificates (CERTIFICATE_PEM, PRIVATE_KEY_PEM)

Prerequisites

• Kamal configuration files in your repository
• SSH access to target servers
• Bitwarden account with necessary secrets
• Docker registry access

Example Secret Mapping

When specifying the secrets input, use the format: SECRET_ID > ENV_VAR

secrets: "8152c344-2e85-48dd-9e37-a631f952163f > DOT_ENV"

This will retrieve the secret with UUID 8152c344-2e85-48dd-9e37-a631f952163f from Bitwarden and make it available as the DOT_ENV environment variable. The DOT_ENV variable typically contains all the environment variables needed for your Kamal deployment in a single secret.