Push and pull

Push workspace configuration to Git as a pull request, then pull a reviewed commit into another workspace.

Enterprise Edition

Push and pull require a workspace connected to a repository. See Workspace Git sync to connect a provider and bind a workspace.

Push and open a pull request

Use the Push tab to push the full workspace configuration.

1. Choose a branch and commit message

   On the Push tab, use the branch picker beside Into to choose an existing branch or enter a new branch name and click Create. Enter a commit message. New branches start from the base branch. Tracecat blocks direct pushes to both the base branch and the repository default branch.

   
2. Preview changes

   Click Preview to compare with the target branch, or the base branch when creating a branch. Expand a resource group to review its file changes. Use Preview again after making more edits.

3. Push

   Click Push and open PR (Push and open MR on GitLab); the button includes the change count after a preview. Use the adjacent menu to choose Push only when you want a commit without a pull request. Tracecat commits only changed files, deletes stale files, and reuses an open pull request on the same branch.

   The pull request body names the workspace and the publishing user’s email.

Push one resource type

Each resource list page has its own Push button, which exports that resource type plus everything it references onto its own branch.

Tables

Case fields

Skills

Push a single workflow

From the workflow builder’s Publish dropdown, choose Open PR or Push directly; a direct push commits to the selected branch with no pull request.

Pull a commit

A merged pull request changes nothing in a workspace until you or your pipeline pull that commit.

1. Choose a commit

   On the Pull tab, use the commit picker beside From to choose a commit from the base branch.

   
2. Preview changes

   Click Preview to dry-run the pull. If Tracecat cannot resolve a model, MCP integration, or secret store, choose its target in the matching dialog, then click Save and preview again. Use Choose matches to reopen unresolved choices. Resolve any validation errors before pulling.

   
3. Apply

   Click Pull into <workspace>; the button includes the change count after a preview. Tracecat enables it only after a successful preview for the same commit and options. A pull updates matching workspace resources and leaves schedules untouched unless you check Overwrite schedules. Changing the commit, schedule option, or reference matches requires another preview.

A pull can overwrite local edits made after the preview. Coordinate workspace edits, run one push or pull at a time, and wait for it to finish before starting another. Leaving the page does not cancel an in-flight sync. A push exports the workspace state when you submit it, so preview again after editing resources.

Until you publish a pulled workflow, its runs resolve actions against the workspace’s current registry versions. Publishing it records the registry lock.

Staging to production

1. Bind both workspaces

   Bind staging and production workspaces to the same repository. Role assignments are per workspace, so grant workspace_sync:sync (workspace-editor and above) in each.

2. Push from staging

   Build in staging, then choose Push and open PR (MR on GitLab) from its Push tab.

3. Review and merge

   Merge the pull request in your repository, where branch protection and required reviews apply.

4. Pull into production

   In production, select the merged commit, click Preview, then Pull into <workspace>. Publish any workflow that needs a registry lock.

API reference

Exporting a workspace requires workspace_sync:sync. Reading branches and commits, pulling, and publishing one workflow also accept workflow:sync, so a service account holding only workflow:sync can pull from CI.

Action	Endpoint	Scopes
Save provider credentials	POST /organization/vcs/{provider}/credentials (github or gitlab)	org:settings:update
Bind a repository	PATCH /workspaces/{workspace_id} with settings.git_provider and settings.git_repo_url	workspace:update
Preview an export	POST /workflows/sync/export/preview	workspace_sync:sync
Export and open a pull request	POST /workflows/sync/export	workspace_sync:sync
Push one workflow	POST /workflows/{workflow_id}/publish	workflow:update, plus workflow:sync or workspace_sync:sync
List branches and commits	GET /workflows/sync/branches, GET /workflows/sync/commits?branch=	workflow:sync or workspace_sync:sync
Pull a commit	POST /workflows/sync/pull with a required commit_sha	workflow:sync or workspace_sync:sync

Related pages

• See Workspace Git sync for connecting a repository and the layout of an export.
• See Security architecture for the GitOps model and how registry versions resolve after a pull.
• See Roles and permissions for the scopes that gate connecting, exporting, and pulling.
• See Workflows for YAML export and import without Git.