Dokploy Deployment Tool

Deploy applications to Dokploy from GitHub Actions or the command line.

This tool:

🎯 GitHub Action - Automated deployments in your CI/CD pipeline
💻 CLI Tool (dokdeploy) - Deploy from your local machine
✅ Proper verification - Ensures deployments actually complete (no more race conditions!)

What's New (v2.0)

This action has been completely rewritten in Python to fix critical race conditions that caused deployments to appear successful while the old version kept running. Key improvements:

Deployment tracking by ID: Tracks the specific deployment triggered, not just application status
Race condition fixes: Detects when deployment hasn't started yet (instant "done" bug)
Smart polling: Exponential backoff and state transition detection
Better error messages: Clear explanations when things go wrong
Debug mode: See full API requests/responses for troubleshooting

Inputs

`dokploy_url`

Required Dokploy dashboard URL (this should have the Dokploy API accessible at /api) - no trailing slash.

Example: https://server.example.com or https://app.dokploy.com

`auth_token`

Required The Dokploy authentication token (API key).

`application_id`

Required The Dokploy application ID.

`application_name`

Required The Dokploy application name.

`wait_for_completion`

Optional Wait for the deployment to finish before completing the action. Default: false.

When true:

Polls deployment status every 3-20 seconds with smart backoff
Verifies the triggered deployment actually started and completed
Fails if deployment errors, is cancelled, or times out
Timeout: 10 minutes (suitable for source builds)

⚠️ Recommended: Set to true to ensure deployments succeed before continuing your workflow (e.g., running tests).

`restart`

Optional Restart the Dokploy application after deployment completes. Default: false.

When true:

Only executes if deployment verification succeeds
Stops the application, waits 5 seconds, then starts it
Verifies application is running after restart

Note: Only needed if Dokploy doesn't automatically restart after deployment.

`debug`

Optional Enable debug logging to see full API requests and responses. Default: false.

Useful for troubleshooting deployment issues.

Usage

Basic Usage (Fire and Forget)

Triggers deployment without waiting for completion:

name: Deploy to Dokploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Dokploy deployment
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: ${{ secrets.DOKPLOY_URL }}
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: ${{ secrets.DOKPLOY_APP_ID }}
          application_name: my-app

⚠️ Warning: Without wait_for_completion: true, the action exits immediately and doesn't verify the deployment succeeded. The old version might keep running.

Recommended Usage (With Verification)

Wait for deployment to complete before continuing:

      - name: Deploy to Dokploy
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: https://app.dokploy.com
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: abc123
          application_name: my-app
          wait_for_completion: true

This ensures:

Deployment actually starts and completes
Errors are caught and fail the workflow
Next steps run against the new version

With Restart (Force New Version)

For apps that need explicit restart:

      - name: Deploy and restart
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: ${{ secrets.DOKPLOY_URL }}
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: ${{ secrets.DOKPLOY_APP_ID }}
          application_name: my-app
          wait_for_completion: true
          restart: true

Multiple Applications (Matrix Strategy)

Deploy multiple apps in parallel:

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        app:
          - { id: 'abc123', name: 'api' }
          - { id: 'def456', name: 'worker-1' }
          - { id: 'ghi789', name: 'worker-2' }
    steps:
      - name: Deploy ${{ matrix.app.name }}
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: https://app.dokploy.com
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: ${{ matrix.app.id }}
          application_name: ${{ matrix.app.name }}
          wait_for_completion: true
          restart: true

With E2E Tests After Deployment

Ensure tests run against the new version:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy application
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: ${{ secrets.DOKPLOY_URL }}
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: ${{ secrets.DOKPLOY_APP_ID }}
          application_name: my-app
          wait_for_completion: true  # Critical: wait before testing!

  test:
    needs: deploy
    runs-on: ubuntu-latest
    steps:
      - name: Run E2E tests
        run: npm run test:e2e

Debug Mode

Enable detailed logging to troubleshoot issues:

      - name: Deploy (with debug)
        uses: tarasyarema/dokploy-deploy-action@main
        with:
          dokploy_url: ${{ secrets.DOKPLOY_URL }}
          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
          application_id: ${{ secrets.DOKPLOY_APP_ID }}
          application_name: my-app
          wait_for_completion: true
          debug: true

How It Works

The action fixes the race condition bug by:

Capturing baseline: Gets the timestamp of the latest deployment before triggering
Triggering deployment: Calls Dokploy API to start deployment
Finding the new deployment: Polls /api/deployment.all for a deployment created after baseline
Tracking by ID: Monitors that specific deployment's status until completion
Verifying completion: Ensures deployment actually entered "running" state before "done"

This prevents the bug where the action would check applicationStatus (already "done" from previous deployment) instead of tracking the triggered deployment.

Troubleshooting

"Deployment marked 'done' after only Xs without entering 'running' state"

This warning indicates a potential race condition. The deployment might not have started yet, or completed extremely quickly. If you see this consistently, enable debug: true to see detailed API responses.

"No new deployment appeared within 30 seconds"

The deployment trigger succeeded but no deployment was created. Possible causes:

Application ID is incorrect
Dokploy is experiencing issues
Deployment is queued but hasn't started

Check the Dokploy dashboard manually.

"Deployment stuck in 'idle' state"

The deployment is queued behind other deployments. This is normal for busy Dokploy instances. The action will continue waiting up to the timeout (10 minutes).

Enable Debug Logging

Set debug: true to see:

Full API request URLs and bodies
Complete API responses
Detailed state transitions

with:
  debug: true

CLI Tool: Deploy from Your Machine

The dokdeploy CLI lets you deploy directly to Dokploy from your local machine or any CI system.

Quick Start

# 1. Install dependencies
uv sync

# 2. Initialize config file
uv run ./dokdeploy init

# 3. Edit ~/.dokploy/deploy.yaml with your apps
vim ~/.dokploy/deploy.yaml

# 4. Deploy!
uv run ./dokdeploy deploy api
uv run ./dokdeploy deploy --all

Example Config

~/.dokploy/deploy.yaml:

dokploy:
  url: https://app.dokploy.com
  auth_token: $DOKPLOY_AUTH_TOKEN

defaults:
  wait_for_completion: true
  restart: false

apps:
  api:
    id: 7YIYBwVKk_V3lUJKp37Va
    name: qaforme-api-gp9he8

  worker:
    id: rfDCKRDJMlfCxX_nZ2qIq
    name: qaforme-worker-wwmm7o

CLI Commands

# List configured apps
uv run ./dokdeploy list

# Deploy one or more apps
uv run ./dokdeploy deploy api
uv run ./dokdeploy deploy api worker frontend

# Deploy all apps (like your GitHub matrix!)
uv run ./dokdeploy deploy --all

# Check status
uv run ./dokdeploy status api

# View deployment history
uv run ./dokdeploy history api

# Validate config
uv run ./dokdeploy config validate

See DEVELOPMENT.md for complete CLI documentation.

Testing Locally

You can test the deployment script locally without GitHub Actions.

Quick start:

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Copy template and add your credentials
cp test_local.sh.template test_local.sh
# Edit test_local.sh with your Dokploy credentials

# Run it
./test_local.sh

See DEVELOPMENT.md for detailed local development guide.

Testing with a Different Branch

To test changes from a branch in your workflow:

- uses: tarasyarema/dokploy-deploy-action@your-branch-name

Or reference your fork:

- uses: your-username/dokploy-deploy-action@main

What Was Fixed

Before (v1.x - Bash version):

❌ Checked applicationStatus (wrong field, race condition)
❌ 60-second initial wait (too long, missed state changes)
❌ No deployment ID tracking
❌ Instant "done" accepted as success
❌ Reload called without coordination
❌ Restart could start old version

After (v2.0 - Python version):

✅ Tracks specific deployment by ID
✅ 3-second initial poll (catches deployment quickly)
✅ Detects race conditions (instant "done" warning)
✅ Smart polling with exponential backoff
✅ Restart only after verified deployment
✅ Debug mode for troubleshooting
✅ Clear error messages

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github		.github
src		src
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
action.yml		action.yml
deploy.yaml.template		deploy.yaml.template
dokdeploy		dokdeploy
pyproject.toml		pyproject.toml
readme.md		readme.md
requirements.txt		requirements.txt
test_local.sh.template		test_local.sh.template

License

tarasyarema/dokploy-deploy-action

Folders and files

Latest commit

History

Repository files navigation

Dokploy Deployment Tool

What's New (v2.0)

Inputs

dokploy_url

auth_token

application_id

application_name

wait_for_completion

restart

debug

Usage

Basic Usage (Fire and Forget)

Recommended Usage (With Verification)

With Restart (Force New Version)

Multiple Applications (Matrix Strategy)

With E2E Tests After Deployment

Debug Mode

How It Works

Troubleshooting

"Deployment marked 'done' after only Xs without entering 'running' state"

"No new deployment appeared within 30 seconds"

"Deployment stuck in 'idle' state"

Enable Debug Logging

CLI Tool: Deploy from Your Machine

Quick Start

Example Config

CLI Commands

Testing Locally

Testing with a Different Branch

What Was Fixed

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`dokploy_url`

`auth_token`

`application_id`

`application_name`

`wait_for_completion`

`restart`

`debug`

Packages