From 29cb434959045f5fb3001574aaa95f4c0d4b96ef Mon Sep 17 00:00:00 2001
From: Jamie Schouten <jamie@qlic.nl>
Date: Tue, 5 Aug 2025 15:16:43 +0200
Subject: [PATCH] Add readme

---
 .gitea/workflows/deploy.yml |  2 +-
 README.md                   | 94 +++++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml
index 636c913..405a730 100644
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -40,7 +40,7 @@ on:
         required: false
         default: ${{ vars.WARDEN_URL }}
       secrets:
-        description: "One or more secret Ids to retrieve and the corresponding Gitea environment variable name to set"
+        description: "List of secret IDs and corresponding environment variable names (format: SECRET_ID > ENV_VAR)"
         required: true
 
 jobs:
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16c1856
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+# 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.
-- 
2.49.1