Git Stack Sync

Overview

Git stacks are compose stacks synchronized from Git repositories. This endpoint pulls the latest changes from the repository and redeploys the stack if changes are detected.

Path Parameters

number

required

Git stack ID (not the stack name)

Response

success

boolean

Whether the sync operation succeeded

deployed

boolean

Whether the stack was redeployed (true only if changes were detected)

error

string

Error message if sync or deployment failed

message

string

Human-readable status message

output

string

Docker Compose deployment output (if deployed)

commit

string

Latest Git commit hash after sync

Sync Behavior

Check Status: Verifies stack isn’t already syncing
Git Pull: Fetches latest changes from the configured branch
Change Detection: Compares new commit hash with last deployed commit
Deploy: If changes detected, runs docker compose up -d
Skip: If no changes, returns success without deploying

The sync operation only redeploys if the Git commit hash has changed. If the repository is up-to-date, no deployment occurs.

curl -X POST "https://your-dockhand-instance.com/api/git/stacks/5/sync" \
  -H "Cookie: auth_token=your_token"

{
  "success": true,
  "deployed": true,
  "message": "Stack synced and deployed successfully",
  "commit": "a1b2c3d4e5f6g7h8i9j0",
  "output": "[+] Running 2/2\n ✔ Container my-app-web-1  Started\n ✔ Container my-app-db-1   Started"
}

Creating a Git Stack

Before syncing, you need to create a Git stack:

curl -X POST "https://your-dockhand-instance.com/api/git/stacks" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_token" \
  -d '{
    "stackName": "my-app",
    "environmentId": 1,
    "url": "https://github.com/username/my-app.git",
    "branch": "main",
    "composePath": "docker-compose.yml",
    "envFilePath": ".env",
    "autoUpdate": true,
    "autoUpdateCron": "0 3 * * *",
    "credentialId": null,
    "deployNow": true
  }'

Git Stack Configuration

stackName

string

required

Unique stack name

url

string

required

Git repository URL (HTTPS or SSH)

branch

string

default:"main"

Git branch to track

composePath

string

default:"compose.yaml"

Path to compose file in repository (relative to repo root)

envFilePath

string

Path to .env file in repository (optional)

autoUpdate

boolean

default:false

Enable automatic syncing on a schedule

autoUpdateCron

string

default:"0 3 * * *"

Cron expression for auto-sync schedule (default: 3 AM daily)

credentialId

number

Git credential ID for private repositories (optional)

webhookEnabled

boolean

default:false

Enable webhook for push-triggered deploys

webhookSecret

string

Secret for webhook verification (auto-generated if not provided)

Auto-Sync Schedules

Git stacks can automatically sync on a schedule:

{
  "autoUpdate": true,
  "autoUpdateSchedule": "daily",
  "autoUpdateCron": "0 3 * * *"
}

Common Cron Patterns

Schedule	Cron Expression	Description
Every hour	`0 * * * *`	At minute 0 of every hour
Daily at 3 AM	`0 3 * * *`	At 3:00 AM every day
Twice daily	`0 3,15 * * *`	At 3:00 AM and 3:00 PM
Every 6 hours	`0 /6 * *`	Every 6 hours
Weekly (Monday 3 AM)	`0 3 * * 1`	At 3:00 AM every Monday

Webhook Integration

Enable webhooks to trigger sync on Git push events:

Enable webhook in Git stack settings
Get webhook URL: https://your-dockhand-instance.com/api/git/stacks/{id}/webhook
Configure in GitHub/GitLab: Add webhook URL with secret

GitHub Webhook Setup

Go to repository Settings → Webhooks → Add webhook
Payload URL: https://your-dockhand-instance.com/api/git/stacks/5/webhook
Content type: application/json
Secret: (use the webhook secret from stack configuration)
Events: Select “Just the push event”
Active: ✓

GitLab Webhook Setup

Go to repository Settings → Webhooks
URL: https://your-dockhand-instance.com/api/git/stacks/5/webhook
Secret token: (use the webhook secret from stack configuration)
Trigger: Select “Push events”
Enable SSL verification: ✓

Repository Structure Example

my-app/
├── docker-compose.yml    # Main compose file
├── .env.example          # Example environment variables
├── .env                  # Actual environment variables (gitignored)
├── README.md
├── app/
│   ├── Dockerfile
│   └── src/
└── nginx/
    ├── Dockerfile
    └── nginx.conf

Environment Variable Overrides

You can override environment variables without modifying the Git repository:

// Update Git stack with env var overrides
await fetch('/api/git/stacks/5', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    envVars: [
      {
        key: 'DATABASE_URL',
        value: 'postgres://user:pass@db:5432/myapp',
        isSecret: true
      },
      {
        key: 'ENVIRONMENT',
        value: 'production',
        isSecret: false
      }
    ],
    deployNow: true
  })
});

These overrides are stored in Dockhand’s database and merged with the repository’s .env file during deployment.

Error Handling

404 Not Found

{
  "error": "Git stack not found"
}

403 Forbidden

User lacks stacks:edit permission
User cannot access the stack’s environment

409 Conflict

{
  "success": false,
  "error": "Stack is already syncing. Please wait for the current operation to complete."
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to pull from repository: Host key verification failed"
}

Common causes:

Git authentication failed
Repository not accessible
Invalid compose file syntax
Network connectivity issues

Sync Status

Get the current sync status of a Git stack:

curl "https://your-dockhand-instance.com/api/git/stacks/5" \
  -H "Cookie: auth_token=your_token"

Response:

{
  "id": 5,
  "stackName": "my-app",
  "environmentId": 1,
  "repositoryId": 3,
  "composePath": "docker-compose.yml",
  "envFilePath": ".env",
  "autoUpdate": true,
  "autoUpdateCron": "0 3 * * *",
  "lastSync": "2026-03-04T10:30:00Z",
  "lastCommit": "a1b2c3d4e5f6g7h8i9j0",
  "syncStatus": "success",
  "syncError": null
}

Permissions

Requires stacks:edit permission for the stack’s environment.

Deploy Stack - Deploy a new stack with Git integration
Update Stack - Update Git stack configuration
Delete Stack - Remove a Git-synced stack
List Stacks - View all stacks including Git-synced ones

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

Overview

Path Parameters

Response

Sync Behavior

Creating a Git Stack

Git Stack Configuration

Auto-Sync Schedules

Common Cron Patterns

Webhook Integration

GitHub Webhook Setup

GitLab Webhook Setup

Repository Structure Example

Environment Variable Overrides

Error Handling

404 Not Found

403 Forbidden

409 Conflict

500 Internal Server Error

Sync Status

Permissions

Build docs developers (and LLMs) love

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

​Overview

​Path Parameters

​Response

​Sync Behavior

​Creating a Git Stack

​Git Stack Configuration

​Auto-Sync Schedules

​Common Cron Patterns

​Webhook Integration

​GitHub Webhook Setup

​GitLab Webhook Setup

​Repository Structure Example

​Environment Variable Overrides

​Error Handling

​404 Not Found

​403 Forbidden

​409 Conflict

​500 Internal Server Error

​Sync Status

​Permissions

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Path Parameters

Response

Sync Behavior

Creating a Git Stack

Git Stack Configuration

Auto-Sync Schedules

Common Cron Patterns

Webhook Integration

GitHub Webhook Setup

GitLab Webhook Setup

Repository Structure Example

Environment Variable Overrides

Error Handling

404 Not Found

403 Forbidden

409 Conflict

500 Internal Server Error

Sync Status

Permissions

Related Endpoints