# 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:

```yaml
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`

```yaml
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.