← Volver al listado de tecnologías ← Índice de Dokploy

CI/CD con Webhooks y Dokploy CLI

28 de febrero de 2026 Por: Artiko

dokployci-cdcliwebhooksautomatizacion

CI/CD con Webhooks y Dokploy CLI

Dokploy ofrece dos mecanismos principales para automatizar deployments: webhooks nativos para deploy al hacer push, y un CLI oficial para integracion con pipelines de CI/CD.

Webhooks: Deploy Automatico al Hacer Push

Cada aplicacion en Dokploy genera un webhook URL unico. Al recibirlo, Dokploy ejecuta un nuevo deployment automaticamente.

Obtener la URL del webhook

En el panel de Dokploy, entra a tu aplicacion
Ve a la pestana Deployments
Copia la URL del webhook

El formato es:

https://tu-dominio.com/api/deploy/webhook?token=TOKEN_UNICO

Configurar Webhook en GitHub

Ve a tu repositorio en GitHub
Settings > Webhooks > Add webhook
Configura:

Campo	Valor
Payload URL	La URL del webhook de Dokploy
Content type	`application/json`
Secret	(dejar vacio)
Events	Just the push event

Haz clic en Add webhook

Verifica que funciona haciendo un push. En la seccion de webhooks de GitHub veras el historial de entregas con codigo 200.

Configurar Webhook en GitLab

Ve a tu proyecto en GitLab
Settings > Webhooks
Configura:

Campo	Valor
URL	La URL del webhook de Dokploy
Trigger	Push events
Branch filter	`main` (o la rama que desees)
SSL verification	Enable

Haz clic en Add webhook

Configurar Webhook en Gitea/Forgejo

Ve a tu repositorio
Settings > Webhooks > Add Webhook > Gitea
Configura la URL del webhook y selecciona Push Events

Dokploy CLI

El CLI oficial @dokploy/cli permite interactuar con Dokploy desde la terminal o desde pipelines de CI/CD.

Instalacion

npm install -g @dokploy/cli

Autenticacion

dokploy auth login

Te pedira:

URL del servidor: https://tu-dominio.com
Token de API: generalo desde Settings > Profile > API Tokens

La configuracion se guarda en ~/.dokploy/config.json.

Comandos Principales

Proyectos

# Listar proyectos
dokploy project list

# Crear proyecto
dokploy project create --name "mi-proyecto"

Aplicaciones

# Listar aplicaciones
dokploy app list

# Ver detalles de una aplicacion
dokploy app info --app-id APP_ID

# Deploy manual
dokploy deploy --app-id APP_ID

Bases de datos

# Listar bases de datos
dokploy db list

# Ver informacion de conexion
dokploy db info --db-id DB_ID

Variables de entorno

# Listar variables
dokploy env list --app-id APP_ID

# Agregar variable
dokploy env set --app-id APP_ID --key DATABASE_URL --value "postgres://..."

# Eliminar variable
dokploy env unset --app-id APP_ID --key DATABASE_URL

Integrar Dokploy CLI en GitHub Actions

Workflow basico

Crea .github/workflows/deploy.yml:

name: Deploy to Dokploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Dokploy CLI
        run: npm install -g @dokploy/cli

      - name: Deploy
        env:
          DOKPLOY_TOKEN: ${{ secrets.DOKPLOY_TOKEN }}
          DOKPLOY_URL: ${{ secrets.DOKPLOY_URL }}
        run: |
          dokploy auth login --url "$DOKPLOY_URL" --token "$DOKPLOY_TOKEN"
          dokploy deploy --app-id ${{ secrets.DOKPLOY_APP_ID }}

Configurar secrets en GitHub

En tu repositorio: Settings > Secrets and variables > Actions:

Secret	Valor
`DOKPLOY_TOKEN`	Token de API generado en Dokploy
`DOKPLOY_URL`	`https://tu-dominio.com`
`DOKPLOY_APP_ID`	ID de la aplicacion (visible en la URL del panel)

Workflow con tests antes del deploy

name: Test and Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: success()
    steps:
      - name: Install Dokploy CLI
        run: npm install -g @dokploy/cli

      - name: Deploy
        env:
          DOKPLOY_TOKEN: ${{ secrets.DOKPLOY_TOKEN }}
          DOKPLOY_URL: ${{ secrets.DOKPLOY_URL }}
        run: |
          dokploy auth login --url "$DOKPLOY_URL" --token "$DOKPLOY_TOKEN"
          dokploy deploy --app-id ${{ secrets.DOKPLOY_APP_ID }}

Watch Paths: Deploy Selectivo (v0.20+)

Desde la version 0.20, Dokploy soporta watch paths para deployar solo cuando cambian ciertos archivos. Esto es especialmente util en monorepos.

Configuracion

En la pestana Advanced de tu aplicacion:

Busca Watch Paths
Agrega los patrones de archivos que deben disparar un deploy

Ejemplos de patrones:

# Solo archivos en la carpeta src
src/**

# Solo archivos de configuracion y codigo
src/**
package.json
Dockerfile

# Excluir tests y docs
!tests/**
!docs/**

Caso de uso: monorepo

Si tienes un monorepo con frontend y backend:

/
  apps/
    frontend/
    backend/
  packages/
    shared/

Configura la aplicacion de frontend con watch paths:

apps/frontend/**
packages/shared/**

Y la de backend:

apps/backend/**
packages/shared/**

Asi, un cambio en apps/frontend/ solo redespliega el frontend.

Ejemplo de Pipeline Completo

Pipeline para una aplicacion Node.js con tests, build de imagen Docker, y deploy a Dokploy:

name: Full Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: 20

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm ci
      - run: npm test

  deploy:
    needs: [lint, test]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - name: Install Dokploy CLI
        run: npm install -g @dokploy/cli

      - name: Authenticate and Deploy
        env:
          DOKPLOY_TOKEN: ${{ secrets.DOKPLOY_TOKEN }}
          DOKPLOY_URL: ${{ secrets.DOKPLOY_URL }}
        run: |
          dokploy auth login --url "$DOKPLOY_URL" --token "$DOKPLOY_TOKEN"
          dokploy deploy --app-id ${{ secrets.DOKPLOY_APP_ID }}

      - name: Notify on failure
        if: failure()
        run: echo "Deploy failed - check Dokploy dashboard"

Este pipeline:

Ejecuta lint y tests en paralelo en PRs y pushes a main
Solo despliega cuando se hace push a main y los tests pasan
Usa el CLI para autenticarse y disparar el deploy

Webhook vs CLI: cuando usar cada uno

Criterio	Webhook	CLI en CI/CD
Simplicidad	Alta, solo configurar URL	Media, requiere pipeline
Control	Basico, deploy en cada push	Total, condicionar con tests
Monorepo	Limitado (usa watch paths)	Flexible, deploy selectivo
Auditoria	Logs en Dokploy	Logs en CI/CD + Dokploy
Recomendado para	Proyectos simples	Proyectos con tests/lint

Siguiente: Templates One-Click