usertasks
All documentationStart free beta
Documentation hub

Feature guide

GitHub Sync

Version, schedule, export, and deploy UserTasks configuration through a connected GitHub repository using the UI or public API.

On this page

Complete feature description

Understanding github sync in UserTasks

GitHub Sync provides a governed configuration-as-code path for UserTasks assets. A workspace connects to a repository and branch, then serializes supported assets into a stable directory and manifest layout. Changes can be committed automatically, queued for review, exported as a full snapshot, or limited to selected asset types and IDs.

Outbound synchronization and inbound deployment are deliberately separate. A sync run writes workspace configuration to GitHub; a deployment reads a pinned branch, ref, or commit and imports it into the current tenant. Dry-run deployments let operators inspect the plan before changing local assets.

The public API supports asynchronous control. Starting a sync or deployment returns an identifier and status URL, and status endpoints expose progress, commit SHA, file counts, import statistics, timestamps, and errors. Schedule management uses the same timezone-aware hourly, daily, and weekly contract as the UI.

When to use this feature

  • Configuration changes require Git history, review, or rollback evidence.
  • Assets must be promoted between development, test, and production tenants.
  • A CI pipeline needs to export or deploy configuration programmatically.
  • The workspace needs scheduled configuration backups.

What you can build

  • Nightly configuration backups
  • Pull-request-based design review
  • Environment promotion pipelines
  • Scoped project or asset releases
  • Dry-run deployment gates
  • Automated configuration compliance checks

Production design notes

  • Use a fine-grained GitHub token limited to the intended repository with Contents read/write permission.
  • Use scoped syncs for releases and full syncs for complete snapshots; only one background sync runs per tenant at a time.
  • Pin production deployments to a reviewed commit SHA instead of a moving branch name.
  • Poll with backoff and stop on completed or failed; retain the returned commit SHA and deployment statistics in CI logs.

Core concepts

Workspace connection

A tenant connects one repository, branch, path prefix, write-capable token, and queue or automatic push mode.

Outbound sync

Full, pending-change, scheduled, and scoped runs serialize governed assets into a portable repository layout and commit them to GitHub.

Inbound deployment

Deployments import a pinned Git ref or commit into the workspace, with dry-run support and stable deployment status polling.

Asynchronous operations

Background sync runs and deployments return IDs immediately; callers poll status resources for progress, commit SHA, statistics, or errors.

Actions and capabilities

What designers and operators can do in this product area.

GitHub Sync actions

The main operations available in GitHub Sync.

GitHub Sync actions

Check GitHub sync status

Read the sanitized connection, pending-change count, latest sync run, configured schedule, and latest deployment.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Check GitHub sync status”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Start a full sync

Export all supported workspace assets in the background and return a sync-run polling URL.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Start a full sync”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Commit pending changes

Flush queued asset changes only, either synchronously through the commit endpoint or asynchronously as a commit run.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Commit pending changes”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Start a scoped sync

Export selected asset sections or individual assets without creating a saved sync template.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Start a scoped sync”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Set an automatic schedule

Configure hourly, daily, or weekly synchronization with a minute, time, weekday, and IANA timezone.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Set an automatic schedule”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Poll sync-run status

Inspect phase, completed and total files, commit SHA, changed-file count, timestamps, and failure information.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Poll sync-run status”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Deploy from GitHub

Pin a branch, ref, or commit and enqueue a dry-run or live import into the current tenant.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Deploy from GitHub”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

GitHub Sync actions

Poll deployment status

Inspect pending, running, completed, or failed deployment state and import statistics.

Example: Start a scoped workflow-and-form sync, poll its status URL, then deploy the resulting commit into a test workspace using dry_run.
Configuration inputs
  • Permission to view and edit the relevant github sync assets.
  • The target repository connection, sync kind, optional asset scope, schedule, run ID, or deployment ref.
  • Any required mappings, recipients, filters, variables, permissions, or lifecycle settings shown by the designer.
How to use it
  1. 1.Open Settings → GitHub Sync or the /api/v1/github-sync API from the main navigation.
  2. 2.Create or open the relevant asset and choose “Poll deployment status”.
  3. 3.Complete the required fields, map dynamic values, and review access to every referenced asset.
  4. 4.Use preview, test, or validation where available; correct errors before publishing or executing.
  5. 5.Run the action and inspect its status, output, history, or audit record.
Expected results
  • The operation returns tenant-scoped status, a background run or deployment ID, and auditable Git/import results.
  • Failures remain visible with enough context to correct configuration or retry safely.

Potential use cases

Patterns you can adapt to your own operating model.

Nightly configuration backup

Export the complete workspace configuration to a protected repository every night.

Connect repository
Set daily UTC schedule
Scheduled run starts
Poll latest status
Retain commit history

Promote configuration between environments

Export approved assets from one environment and deploy a pinned commit into another.

Run scoped sync
Review pull request
Pin commit SHA
Dry-run deployment
Run live deployment

CI-managed configuration

Use API or OAuth credentials from CI to start syncs and wait for deterministic completion.

Start background sync
Read status URL
Poll until terminal
Capture commit SHA
Fail CI on sync error