Git Sync

Git Sync keeps Dagu workflows, Markdown documents, and workflow-authoring skill files aligned with a Git repository.

What It Syncs

Git Sync can track:

• DAG files
• Markdown documents
• skills

DAG files live at the configured repository root, documents live under docs/, and skills live under skills/. Pulling a repository routes each kind to its configured local storage directory.

Tracked Items And IDs

Git Sync refers to each tracked file by an itemId. You will see that term in the CLI and REST API.

Local file	itemId	kind
my-dag.yaml	my-dag	dag
subdir/report.yml	subdir/report	dag
docs/operations/runbook.md	docs/operations/runbook	doc
skills/review/SKILL.md	skills/review/SKILL	skill

Basic Configuration

git_sync:
  enabled: true
  repository: github.com/your-org/dags
  branch: main
  path: ""
  push_enabled: true

  auth:
    type: token
    token: ${GITHUB_TOKEN}

  auto_sync:
    enabled: true
    on_startup: true
    interval: 300

  commit:
    author_name: Dagu
    author_email: dagu@localhost

Authentication

HTTPS Token

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

SSH Key

git_sync:
  repository: git@github.com:your-org/dags.git
  auth:
    type: ssh
    ssh_key_path: /home/user/.ssh/id_ed25519
    ssh_passphrase: ${SSH_PASSPHRASE}

For SSH servers that require a username other than git, put the username in the repository URL:

git_sync:
  repository: deploy@git.example.com:your-org/dags.git
  auth:
    type: ssh
    ssh_key_path: /home/user/.ssh/id_ed25519

Everyday Workflow

Most teams use Git Sync in this order:

1. Check status
2. Pull remote changes
3. Review diffs
4. Publish selected local changes
5. Discard, forget, or clean up stale items when needed

Status Values

Status	Meaning
synced	Local content matches the last synced revision
modified	Local content changed since the last sync
untracked	The local file exists but has not been published yet
conflict	Both local and remote changed
missing	A previously tracked local file is gone

CLI

Check Status

dagu sync status

Pull

dagu sync pull

Publish

dagu sync publish my-dag -m "Update workflow"
dagu sync publish docs/operations/runbook -m "Update operations runbook"
dagu sync publish skills/review -m "Update review skill"
dagu sync publish --all -m "Batch update"

Discard Local Changes

dagu sync discard my-dag

Forget Stale State

dagu sync forget missing-dag
dagu sync cleanup

Delete Or Move

dagu sync delete my-dag -m "Remove old workflow"
dagu sync mv old-dag new-dag -m "Rename workflow"
dagu sync mv docs/operations/runbook docs/operations/deploy -m "Rename runbook"

REST API

Method	Endpoint	Description
GET	/api/v1/sync/status	Overall sync status and tracked items
POST	/api/v1/sync/pull	Pull from the remote repository
POST	/api/v1/sync/publish-all	Publish selected or all changed items
POST	/api/v1/sync/test-connection	Verify repository access
GET	/api/v1/sync/config	Read current Git Sync config
PUT	/api/v1/sync/config	Update Git Sync config
GET	/api/v1/sync/items/{itemId}/diff	Show local vs remote diff
POST	/api/v1/sync/items/{itemId}/publish	Publish one item
POST	/api/v1/sync/items/{itemId}/discard	Discard one item
POST	/api/v1/sync/items/{itemId}/forget	Remove stale sync state for one item
POST	/api/v1/sync/items/{itemId}/delete	Delete one item locally and remotely
POST	/api/v1/sync/items/{itemId}/move	Rename one item
POST	/api/v1/sync/delete-missing	Delete all missing items from the remote
POST	/api/v1/sync/cleanup	Remove all missing entries from sync state

If an itemId contains /, URL-encode it in REST calls.

Permissions

Action	Requirement
View status and config	Authenticated access
Pull, publish, discard, delete, move, cleanup	permissions.write_dags plus a write-capable role
Update Git Sync config	Admin role

Write operations are blocked when Git Sync is configured as read-only (push_enabled: false).

Operational Notes

• Manage Git Sync through the UI, CLI, or API rather than editing its internal state directly.
• Documents edited in the Web UI appear as doc items in Git Sync status, diff, publish, discard, delete, and move operations.
• Pull before publishing when multiple people or systems may change the same repository.
• Use clear commit messages because Git Sync publishes normal Git commits.
• For staging and production, prefer read-only Git Sync configurations and promote reviewed workflow versions between environment branches. See Multi-Environment Deployments.

Related Pages

• Server Administration
• Documents
• Multi-Environment Deployments