Git Sync ​

Synchronize DAG definitions with a Git repository.

Configuration ​

gitSync:
  enabled: true
  repository: github.com/your-org/dags
  branch: main
  path: ""  # Subdirectory in repo (empty = root)
  pushEnabled: true

  auth:
    type: token
    token: ${GITHUB_TOKEN}

  autoSync:
    enabled: true
    onStartup: true
    interval: 300  # seconds

  commit:
    authorName: Dagu
    authorEmail: dagu@localhost

Authentication ​

Token (HTTPS) ​

GitHub offers two types of Personal Access Tokens. Choose one:

Option A: Fine-grained PAT (Recommended) ​

Fine-grained tokens are scoped to specific repositories with granular permissions.

Create at: GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens

Required settings:

If you only need to pull (read-only mode with pushEnabled: false):

Option B: Classic PAT ​

Classic tokens use broad OAuth scopes and access all repositories you can access.

Create at: GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic)

Required scopes:

Configuration ​

gitSync:
  repository: github.com/your-org/dags
  branch: main
  auth:
    type: token
    token: ${GITHUB_TOKEN}

Environment variables:

export DAGU_GITSYNC_AUTH_TYPE=token
export DAGU_GITSYNC_AUTH_TOKEN=ghp_xxxxxxxxxxxx

SSH Key ​

Supported key types: RSA, ED25519, ECDSA (via go-git/v5).

Repository URL must use SSH format: git@github.com:org/repo.git

Add your public key to GitHub: Settings > SSH and GPG keys > New SSH key

gitSync:
  repository: git@github.com:your-org/dags.git
  branch: main
  auth:
    type: ssh
    sshKeyPath: /home/user/.ssh/id_ed25519
    sshPassphrase: ${SSH_PASSPHRASE}  # Only if key is encrypted

Environment variables:

export DAGU_GITSYNC_AUTH_TYPE=ssh
export DAGU_GITSYNC_AUTH_SSH_KEY_PATH=/home/user/.ssh/id_ed25519
export DAGU_GITSYNC_AUTH_SSH_PASSPHRASE=your-passphrase

CLI Commands ​

Status ​

dagu sync status

Output: repository, branch, last sync time/commit, DAG counts by status.

Pull ​

dagu sync pull

Fetches remote changes. Local modifications preserved (marked modified). Conflicts detected when both local and remote changed.

Publish ​

dagu sync publish my-dag -m "Updated schedule"
dagu sync publish --all -m "Batch update"

Flags:

• -m, --message <string>: Commit message
• --all: Publish all modified DAGs
• -f, --force: Force publish (overwrite conflicts)

Discard ​

dagu sync discard my-dag

Restores remote version. Permanently discards local changes.

DAG Status States ​

Conflict Resolution ​

# Option 1: Force publish (overwrites remote)
dagu sync publish my-dag --force -m "Override remote"

# Option 2: Discard local (restores remote)
dagu sync discard my-dag

# Option 3: Manual merge, then publish
# Edit the file, then:
dagu sync publish my-dag -m "Merged changes"

REST API ​

Examples ​

# Get status
curl http://localhost:8080/api/v2/sync/status

# Pull
curl -X POST http://localhost:8080/api/v2/sync/pull

# Publish DAG
curl -X POST http://localhost:8080/api/v2/dags/my-dag/sync/publish \
  -H "Content-Type: application/json" \
  -d '{"message": "Updated schedule", "force": false}'

Configuration Reference ​

Main Options ​

Authentication (auth) ​

Auto-Sync (autoSync) ​

Commit (commit) ​

Read-Only Mode ​

Set pushEnabled: false for deployments where DAGs are managed externally (CI/CD pushes to repo, Dagu only pulls).

gitSync:
  enabled: true
  repository: github.com/your-org/dags
  branch: main
  pushEnabled: false
  auth:
    type: token
    token: ${GITHUB_TOKEN}
  autoSync:
    enabled: true
    interval: 300

In this mode, dagu sync publish returns error "push operations are disabled".

Permissions ​

Git Sync operations require the following user roles (when authentication is enabled):

Additionally:

• Server must have writeDAGs permission enabled in server.permissions
• If pushEnabled: false, all write operations return 403 Forbidden

Data Management ​

Storage Locations ​

State File Format ​

Top-level fields:

Per-DAG state (dags[id]):

Change Detection ​

Content hash: sha256: + hex(SHA256(file_content))

• localHash == lastSyncedHash → synced
• localHash != lastSyncedHash → modified
• No lastSyncedHash → untracked

Sync Algorithm ​

Pull:

1. git fetch --depth=1 from remote
2. For each remote .yaml/.yml file:
   • Compute remote hash
   • If local status=modified AND remote hash != lastSyncedHash → conflict
   • Else update local file, set status=synced
3. Scan local DAGs dir for untracked files
4. Save state.json

Publish:

1. If status=conflict and force=false → error
2. Copy DAG file to repo working tree
3. git add + git commit (with configured author)
4. git push
5. Update state: status=synced, update hashes

Conflict occurs when:

• Local file modified (localHash != lastSyncedHash)
• AND remote changed (pulled hash != lastSyncedHash)

State Transitions ​

[new file] → untracked
                ↓ publish
            synced ←──────────────┐
                ↓ local edit      │
            modified              │
           ↙        ↘             │
    [pull+remote    [publish] ────┘
     changed]
        ↓
    conflict
        ↓ publish --force OR discard
    synced

Internals ​

References ​

• GitHub: Managing personal access tokens
• GitHub: Fine-grained PAT permissions
• GitHub: Scopes for OAuth Apps