Template Sources

Add external GitHub repositories as sources for Docker Compose service templates. Custom templates appear alongside built-in templates when creating new services.

List Template Sources

GET /api/v1/template-sources

Response:

{
  "data": [
    {
      "uuid": "ts-abc123",
      "name": "My Templates",
      "slug": "my-templates",
      "repository_url": "https://github.com/myorg/coolify-templates",
      "branch": "main",
      "folder_path": "templates/compose",
      "is_enabled": true,
      "sync_status": "synced",
      "last_synced_at": "2024-06-15T10:30:00Z",
      "sync_error": null,
      "template_count": 12,
      "created_at": "2024-06-01T08:00:00Z"
    }
  ]
}

Sync Statuses

Status	Description
pending	Source created, not yet synced
syncing	Sync in progress
synced	Successfully synced
failed	Sync failed (check sync_error)

Get Template Source

GET /api/v1/template-sources/{uuid}

Returns source details including the list of discovered templates:

{
  "uuid": "ts-abc123",
  "name": "My Templates",
  "repository_url": "https://github.com/myorg/coolify-templates",
  "branch": "main",
  "folder_path": "templates/compose",
  "is_enabled": true,
  "sync_status": "synced",
  "last_synced_at": "2024-06-15T10:30:00Z",
  "templates": [
    {
      "name": "whoami",
      "slogan": "A simple HTTP service for testing",
      "tags": "testing,debug"
    },
    {
      "name": "uptime-kuma",
      "slogan": "Self-hosted monitoring tool",
      "tags": "monitoring,uptime"
    }
  ]
}

Create Template Source

Add a new GitHub repository as a template source:

POST /api/v1/template-sources

{
  "name": "My Templates",
  "repository_url": "https://github.com/myorg/coolify-templates",
  "branch": "main",
  "folder_path": "templates/compose",
  "auth_token": "ghp_xxxx"
}

Parameter	Type	Required	Description
name	string	Yes	Human-readable source name
repository_url	string	Yes	GitHub repository URL
branch	string	No	Branch name (default: main)
folder_path	string	No	Path within repo to YAML templates (default: repository root)
auth_token	string	No	GitHub personal access token for private repositories

Response: 201 Created

{
  "message": "Template source created.",
  "data": {
    "uuid": "ts-abc123",
    "name": "My Templates",
    "sync_status": "pending"
  }
}

A sync job is automatically dispatched after creation.

Template Format

Templates are Docker Compose YAML files with metadata headers:

# documentation: https://example.com/docs
# slogan: A brief description of the service
# tags: category1,category2
# logo: svgs/myservice.svg

services:
  myservice:
    image: myimage:latest
    ports:
      - "8080:8080"
    volumes:
      - mydata:/data

volumes:
  mydata:

Update Template Source

PUT /api/v1/template-sources/{uuid}

{
  "name": "Updated Name",
  "branch": "develop",
  "is_enabled": false
}

Delete Template Source

DELETE /api/v1/template-sources/{uuid}

Response:

{
  "message": "Template source deleted."
}

note

Deleting a template source does not affect services that were already deployed from its templates.

Sync Template Source

Trigger a manual sync to fetch the latest templates from the repository:

POST /api/v1/template-sources/{uuid}/sync

Response:

{
  "message": "Sync job dispatched."
}

The sync runs asynchronously. Check the source's sync_status to monitor progress.

Sync All Sources

Trigger a sync for all enabled template sources:

POST /api/v1/template-sources/sync-all

Response:

{
  "message": "Sync jobs dispatched for 3 sources."
}