Troubleshooting

Diagnose and recover Workflow Source Control connections, branches, sync, and deployments

Source Control is designed to fail safely: a provider or validation error does not partially update protected main or replace the active deployment.

Use the status strip at the top of Source Control to inspect the synchronization state (Synced, New commits in Git, Not synced yet, Sync failed, or Connection error) and the latest workspace snapshot or package deployment. Expand Details for the managed path, latest commit in Git, synchronized commit, and last check time. Refresh reloads recorded state. For a package destination, Sync approved changes verifies and prepares the package, then its deployment policy controls publication: manual waits for Deploy synced version; automatic publishes after validation. Capture approval alone does not publish. Follow the workspace guide for the complete review flow.

Synced, but workflows did not appear

Synced reports the saved connection's synchronization state. It does not prove that the workspace received a package or published workflows. Open Source Control > Settings, inspect the connection, and read the latest job result.

If a job reports Applied 0 Workflow bundles while you expected workflows from another workspace, check the saved workflow direction. Publishing workflows to Git is an authoring connection. An authoring connection with no registered managed workflows can finish synchronization without importing any workflows, even when a merged package exists on its branch. Git changes only controls local editing; it does not turn that connection into a package destination.

To receive the package:

  1. In GitHub, confirm the intended branch contains the reviewed package at <managed-path>/workspace-snapshot/workspace.json and its listed workflow bundles. If the capture PR merged into develop but Prod follows main, also merge a reviewed promotion PR into main.
  2. In the destination's Source Control > Settings, select Change connection. Choose the repository and workspace branch, then Receive workflows from Git. Verify the discovered workflow package, such as Dev Workspace. That name comes from Git, and does not require access to a live source workspace.
  3. Select Save connection, then Sync approved changes. An initial receiving connection requires an empty workspace, including archived workflows and folders. If the workspace already has definitions, use a separate empty destination.
  4. Check the synchronization result and imported workflows. With Deploy manually, select Deploy synced version to make them live; synchronized drafts and live versions are separate.

If receiving setup reports no workflow package on the branch, enter the Expected package folder and save the connection. It shows Waiting for first release. Publish and merge the reviewed package into that branch at the same folder, then synchronize in Releases. You can create and connect Prod first; do not create an authoring package as a substitute.

If it keeps waiting, check the exact branch and folder: packages elsewhere in the repository are ignored. An unreadable or malformed package is an error, not an empty branch. After the first verified identity is pinned, a different package identity is rejected. If you allowed direct draft edits while waiting, remove local definitions, including archived workflows and folders, before first import.

Change a Saved Connection or Promotion Target

Saved connections show their repository, workspace branch, workflow direction, and package folder as a readable summary. Select Change connection to edit them. The top Workspace branch selector supports selecting or creating a branch, then confirming a connection change.

To send changes to the next environment, use Promote to branch instead. Its Target branch is the base of a GitHub pull request; the sending workspace keeps following its current branch. For example, promoting develop into qa does not reconnect Dev to qa.

Readers can inspect saved settings. An authorized workspace or organization admin, or a person granted Manage source control, can change connections and create repository branches. Unlock changes the branch lock independently of local editing and deployment policies.

Branch Connection Cannot Be Saved or Synchronized

Message or symptomRecovery
Connection settings changedRefresh the settings and reapply your change. A newer configuration revision prevents a stale form from overwriting another person's changes
A workspace release is runningWait for synchronization, deployment, or recovery to finish before changing the connection
Existing workflow protection or editing branches block retargetingResolve retained legacy protection and open branches before changing an authoring workspace's repository, branch, or path. Its branch lock can still be changed by an authorized manager
Another workspace already authors this repository/branch/pathChoose Receive workflows from Git and select its package to create a destination, or choose a distinct path for a new authoring package. Multiple destinations may follow the same package
Destination must be emptyInitially connect an external package to a workspace with no workflows or workflow folders, including archived definitions
No matching merged approvalMerge a PR containing the exact package into the connected branch, then synchronize. Direct package edits or merge resolutions differing from the reviewed PR head are rejected. Approval checks the 100 most recently updated closed PRs
The source workspace is on another installationConnect the repository in the destination organization, select its branch and package, and configure local resource assignments. No live development-workspace lookup is required
Saved, but hourly checks could not be scheduledThe connection is saved. Restore Temporal and the Worker, then select Sync approved changes to retry
Ready to deploy after changing settingsSaving does not synchronize or deploy. Synchronize the package for the current configuration revision, then deploy if the policy is manual

For Allow direct edits, synchronization replaces local package drafts from Git. Extra local workflows outside the connected package must be moved or archived before synchronization. The currently live versions remain until deployment succeeds. See Branch-connected workspaces.

Workspace Capture Cannot Continue

A workspace_capture_conflict explains which review prerequisite changed. If upstream moved or the repository, path, or target branch changed, capture and review again. If approval is missing, merge the exact workspace PR and select Check if merged. A changed PR head, rewritten upstream history, or modified snapshot files requires a fresh capture.

Organization capture rejects later workspace edits after a reviewed snapshot. Save those edits in another workspace capture and merge its PR before retrying organization capture. A lost commit or PR response can be retried on the same capture.

Workspace capture requires settings administration and read access to every active workflow. Deleted workflows are not checked. An unreadable saved definition fails the complete operation with the workflow name. Save a valid draft and retry; workflows are never silently skipped. Capture supports up to 200 workflows, 4,096 files, and 16 MiB.

Organization releases support workflows and folders. Unsupported content in managed workspaces blocks capture. Workspace release scope shows workspaces excluded because they have independent connections. On the target, use Sync now to check the followed branch and Check readiness to diagnose missing assignments. If an automatic deployment pauses for acceptance, review the pending release before preparing and deploying it. See Release Operations and Acceptance for retries, stale plans, and rollback.

If an upgrade leaves a workspace outside organization capture, check who originally connected it. An authorized operator can restore ownership for a connection created by the old organization setup under Workspace release scope. Follow the upgrade steps in Git Approval and Release Status.

If a merged organization release does not appear, check the followed branch and confirm the target sync job is running. A signed push wakes the next scheduled check; a periodic check recovers missed deliveries. Refresh status only reloads the saved state.

The conflict also carries a machine-readable reason: not_merged, pr_closed, merged_different, or settings_changed.

Merged, but the branch no longer matches

The pull request merged with different content, or the branch changed after the merge, so the capture cannot be approved. Select Capture workspace to review again. The new capture proposes the workspace's version and replaces what is on the branch, so edit the workspace first if you want to keep what was merged.

Credential warning

A captured file holds a value shaped like a credential. Before commit, remove it from the workflow and capture again. After commit or while a PR is open, do not merge: remove it, capture again, and rotate it. Once a value is approved or already on the branch, rotate it. Removing it later does not erase it from Git history. The warning can be a false positive and never blocks the commit.

Workflow Controls Are Missing

Workflow Git setup, editing branches, and editor controls are paused in code. Setting the former WORKFLOW_SOURCE_CONTROL_ENABLED variable to true has no effect. Authenticated workflow protection, unprotection, resource-assignment updates, and branch-authoring HTTP mutations return 404 with code workflow_source_control_disabled. Chat also rejects edits to retained workflow branches. Workspace capture and PRs, repository settings, status reads, synchronization, and existing protection guards remain available.

Start with Status

Check both settings surfaces:

  • Settings > Integrations > GitHub Source Control shows organization enablement, connected repositories, connection health, and Test connection.
  • Source Control > Settings shows the saved connection and separate lock, editing, and deployment policies. Package destinations show Sync approved changes, Deploy synced version, and recent jobs. Authoring workspaces retain Sync now and confirmed Full resync.

Then open the workflow and read the release status in the source-control bar. PR merged, Approved and synchronized, and the Live version describe separate stages. A merged or synchronized change is not deployed until an admin selects Deploy approved.

Common Issues

SymptomLikely causeWhat to do
Set up GitHub Source ControlThe organization integration is disabled or no repository is connectedOpen Settings > Source Control, enable the integration, and connect a repository
Connect a repository firstThe workspace has no active repository connectionOpen Source Control > Settings, select the repository, branch, and package, then Connect workspace
Repository is missing from the selectorThe GitHub App does not have access, or the repository was not verified for the organizationConfigure the GitHub App's repository access, return to Integrations, and connect or test the repository
Repository connection needs attentionGitHub App installation access changed or the connection test failedRestore access in GitHub, then select Test connection
Authentication failed / GitHub 401GitHub rejected the App credentials; this does not establish whether the repository existsAsk the platform administrator to check the GitHub App credentials, then test again
Repository unavailable / GitHub 404The App cannot find the repository; it may be deleted, renamed, transferred, or no longer accessible to the AppOpen the repository's GitHub link and check its existence and App access before reconnecting
Branch unavailableThe repository was reached, but its default branch could not be readEnsure the repository has an initial commit and a valid default branch, then test again
Repository changedThe saved name now identifies a different GitHub repositoryChange any workspace connections first, remove the unused saved connection, and connect the intended repository again
Remove is disabledOne or more live workspaces still use the connectionChange their repository connection in Source Control > Settings first; deleted workspaces do not count as usage
Integration controls are disabled or missingYour effective role lacks organization settings permissionAsk an organization settings manager to manage the repository connection; a workspace connection grant alone does not grant organization settings access
Permissions could not be checkedSteelEngine could not load your effective organization permissionsSelect Check permissions again; a failed check is different from denied access
Create and connect repository is disabled after entering a nameThe name is invalid, for example it contains spacesRead the message beside Repository name and use letters, numbers, periods, hyphens, or underscores, such as hello-there
Target branch was not foundThe selected GitHub branch does not existOpen the branch selector, choose Create branch…, and select Create from; empty repositories need an initial commit first
Save the environment changes aboveThe mapping has unsaved changesSave the binding before creating the protection PR
Protected main is read-onlyExpected behavior for a protected workflowSelect an open source-control branch or create New branch
Branch is behind its targetThe configured environment branch advanced after the branch was createdCommit or discard local changes, then select Update branch
Branch is conflictedThe branch and main changed the same workflow fieldsSelect Resolve, choose one resolution per conflict, and select Resolve and update
Commit is disabledThe branch is clean, the review is still loading, or the commit message is emptyMake or restore a change, wait for the reviewed revision, and enter a message
Commit reports a changed remote headGitHub advanced after SteelEngine loaded the branchRefresh, then update the branch; SteelEngine will not force-push
Pull request Check failsBundle, graph, dependency, secret-scan, or resource preflight validation failedReview the safe Check details and the job result, fix the branch, and commit again
Pull request merged but main did not updateWebhook delivery was delayed, missed, or the final commit failed validationSelect Sync now and review the latest apply job
Deploy is blockedMain has a sync error, does not match the applied commit, or has unresolved resource assignmentsRepair synchronization and save all required Resource assignments
Sync now shows No result yetThe worker has not reported back after about a minuteCheck the job table on Settings, then confirm the worker is running and sync again
Saving warns that hourly checks could not be scheduledThe settings saved, but the Temporal schedule could not be setSelect Sync now, or Sync approved changes on production, which repairs the schedule
Deploy synced version is missingThe branch is ahead of the synced commitSync first, then deploy
Remote branch was deleted with dirty draftsGitHub removed the ref while SteelEngine still has uncommitted workSelect Recreate remote, then commit or discard the draft

Synchronization Errors

When an environment-branch commit cannot be applied, the workflow enters sync_error:

  • Main remains read-only.
  • The last successfully applied main draft remains intact.
  • The active deployment continues running unchanged.
  • New deployments and new branches from the invalid head are blocked.

A file on the branch that cannot be parsed reports one plain sentence here; the detail stays in the server logs.

Merge a repair or revert commit in GitHub, then select Sync now. If the branch has returned to the last applied commit, Sync now clears the error and applies nothing. Otherwise SteelEngine validates the managed tree again and advances only after the complete apply succeeds.

When to Use Full Resync

Use Full resync only after a repository administrator intentionally force-pushes or rewrites environment-branch history.

  1. Review the rewritten history and choose the commit the organization accepts.
  2. Open Settings > Source Control.
  3. Select Full resync.
  4. Read the warning and select Start full resync.

SteelEngine validates the complete managed path before accepting the new baseline. It does not force-push GitHub.

Do not use Full resync as a general retry button. For ordinary missed webhooks or transient provider errors, use Sync now or Retry on the failed job.

Missing Resource Assignments

A workflow can synchronize even when a logical resource role is not assigned locally, but it cannot deploy.

  1. Open the protected workflow on main.
  2. Select Configure resource assignments in the source-control bar.
  3. Map every required role to an accessible workspace connection or credential.
  4. Select Save assignments.
  5. Retry validation or deployment.

Assignments are environment-local and never committed to Git. If the required role itself is wrong, change that requirement on a branch and review it through a pull request.

GitHub Is Unavailable

During a GitHub outage or connection failure:

  • Existing branch drafts continue to autosave in SteelEngine.
  • Commits, remote branch mutations, pull requests, and provider synchronization wait or fail safely.
  • Protected main remains on the last successfully applied commit.
  • Active deployments continue to run from immutable SteelEngine snapshots.

After service returns, select Test connection, retry failed jobs, and use Sync now. Avoid recreating changes or force-pushing while durable operations are still reconciling.

Unprotect a Workflow

Unprotection is also pull-request based:

  1. Open the protected workflow on main.
  2. Select Unprotect.
  3. Confirm with Request unprotect.
  4. Open and merge the generated pull request.

The workflow stays protected and read-only while the pull request is open. Merging removes its managed repository bundle and returns normal workspace editing. Closing the pull request leaves the workflow protected. The current draft and deployment history are preserved either way.

Unprotect every dependent workflow before trying to disconnect its repository or move the workspace to another managed path.

Safe Recovery Rules

  • Prefer Retry and Sync now for transient failures.
  • Commit or discard local changes before updating or deleting a branch.
  • Repair invalid environment-branch content with a reviewed commit or revert.
  • Reserve Full resync for an intentional, reviewed history rewrite.
  • Do not place secrets in workflow fields to work around a missing resource assignment.
  • Do not force-push SteelEngine-managed branches.

If a problem persists, capture the organization and workspace, repository, branch name, short commit SHA, workflow ID, job mode, and visible error summary. Do not include tokens, private keys, credentials, prompts, or full workflow bundle contents in a support request.

On this page