95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# 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.
|