GitHub Actions

Choose the deployment type

GitHub Actions builds the image, so Coolify must deploy the published image instead of rebuilding the same source.

Choose one:

• Create a Docker Image application for one image.
• Use Docker Compose when the deployment contains multiple services. Reference the published image with image: instead of build:.

services:
  web:
    image: ghcr.io/shadowarcanist/tasklytics:latest

Authenticate the deployment server before using a private image.

Enable Coolify API access

On a self-hosted Coolify instance:

1. Open Settings.
2. Select Configuration > Advanced.
3. Enable API Access.
4. Save the setting.

Create a Coolify API token

1. Open Keys & Tokens > API Tokens.
2. Select + Add.
3. Give the token a descriptive name.
4. Enable the deployment permission required by the authenticated deploy webhook.
5. Create the token.
6. Copy the token immediately.

Store it in a password manager until it has been added to GitHub.

Copy the deploy webhook

1. Open the application.
2. Select Configuration > Webhooks.
3. Copy Deploy Webhook (auth required).

The URL identifies the application. The API token authorizes the request.

Add GitHub repository secrets

1. Open the GitHub repository settings.
2. Select Secrets and variables > Actions.
3. Select New repository secret.

4. Create COOLIFY_WEBHOOK with the authenticated deploy webhook URL.

5. Select New repository secret again.

6. Create COOLIFY_TOKEN with the Coolify API token.

Do not commit either value to the workflow file.

Add the GitHub Actions workflow

Create .github/workflows/build.yaml:

name: Build and deploy

on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: shadowarcanist/tasklytics

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          platforms: linux/amd64
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

      - name: Trigger Coolify deployment
        run: |
          curl --fail --request GET '${{ secrets.COOLIFY_WEBHOOK }}' \
            --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}'

The workflow builds and publishes the image before asking Coolify to deploy it.

For immutable releases, publish a commit-specific tag and update the deployed image reference as part of the release process instead of relying only on latest.

Authenticate the deployment server

For a private registry, connect to every deployment server that must pull the image and authenticate Docker as the server user configured in Coolify.

echo "$GH_TOKEN" | docker login ghcr.io --username "$GITHUB_USERNAME" --password-stdin

Trigger the workflow and confirm:

1. GitHub Actions publishes the expected image.
2. The Coolify request succeeds.
3. Coolify pulls the new image.
4. The application container starts and becomes healthy.