How devevandro/coolify-app-deploy works
Project Type and Purpose
• Type: Open-source integration tool in the form of a GitHub Action.
• Purpose: When a Git push (or manual dispatch) to a branch occurs, this Action runs on a GitHub Actions runner, reads inputs/secret values, and invokes the Coolify REST API to deploy an app and update its environment variables.
File Structure
• Top-level files:
• .github/workflows/deploy.yml – CI pipeline (build & publish Action, optional).
• action.yml – Action metadata (inputs, outputs, entrypoint).
• README.md – User guide.
• package.json / tsconfig.json – Node/TypeScript config.
• Source & build dirs:
• src/index.ts – Main logic entrypoint.
• src/utils/index.ts – Payload/build helpers.
• dist/index.js – Compiled JS used at runtime.
• Lock file & ignore: typical Node modules.
README for Additional Insights
• Features:
• coolify_url, coolify_token, coolify_app_uuid as required inputs.
• Optional secrets JSON blob and secrets_to_exclude.
• Secure auth via Bearer token.
• Plug-and-play in any workflow YAML.
• Usage snippet: shows how it is invoked in a standard GH Actions workflow.
Main Components & Relationships
a. GitHub Actor (Developer / Push event)
→ triggers the workflow on GitHub.com
b. GitHub Actions Runner
– Checks out the repo (standard actions/checkout)
– Reads action.yml metadata
– Installs dependencies / Node runtime
– Executes dist/index.js with provided inputs
c. Action Logic (Node.js / TypeScript)
– Validates inputs, merges optional secrets, applies secrets_to_exclude filter
– Makes HTTP calls (e.g., via fetch or axios) to:
• POST {coolify_url}/api/applications/{appUuid}/deploy
• PUT {coolify_url}/api/applications/{appUuid}/env
– Handles HTTP responses / errors, logs status
d. Coolify Instance (Self-hosted)
– API Gateway / Auth layer (verifies coolify_token)
– Application service (updates DB, writes env vars)
– Deployment orchestrator (builds containers, updates pods)
e. External Systems
– (Optional) Secrets store: GitHub Secrets
– (Optional) Coolify’s backing DB / container registry
Architectural Patterns & Principles
• Adapter/Integration Pattern: wraps Coolify’s REST API in a simple Action interface.
• Single Responsibility: one Action for deploy + env management.
• Immutability: uses fresh runner each invocation.
• Configuration as Code: all inputs are declared in action.yml & workflow YAML.