# 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](/source-control/workspace-hub) 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](/source-control/production-workspaces#where-workspace-package-names-come-from), 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](/source-control/production-workspaces#can-i-create-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 symptom                                                 | Recovery                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection settings changed                                        | Refresh the settings and reapply your change. A newer configuration revision prevents a stale form from overwriting another person's changes                                                                                              |
| A workspace release is running                                     | Wait for synchronization, deployment, or recovery to finish before changing the connection                                                                                                                                                |
| Existing workflow protection or editing branches block retargeting | Resolve 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/path      | Choose **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 empty                                          | Initially connect an external package to a workspace with no workflows or workflow folders, including archived definitions                                                                                                                |
| No matching merged approval                                        | Merge 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 installation                    | Connect 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 scheduled                    | The connection is saved. Restore Temporal and the Worker, then select **Sync approved changes** to retry                                                                                                                                  |
| Ready to deploy after changing settings                            | Saving 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](/source-control/production-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](/self-hosting/releases/operations) 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](/self-hosting/releases/git-promotion).

If a merged organization release does not appear, check the followed branch and confirm the [target sync job](/self-hosting/releases/kubernetes-setup) 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

| Symptom                                                             | Likely cause                                                                                                    | What to do                                                                                                                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Set up GitHub Source Control**                                    | The organization integration is disabled or no repository is connected                                          | Open **Settings > Source Control**, enable the integration, and connect a repository                                                                     |
| **Connect a repository first**                                      | The workspace has no active repository connection                                                               | Open **Source Control > Settings**, select the repository, branch, and package, then **Connect workspace**                                               |
| Repository is missing from the selector                             | The GitHub App does not have access, or the repository was not verified for the organization                    | Configure the GitHub App's repository access, return to Integrations, and connect or test the repository                                                 |
| **Repository connection needs attention**                           | GitHub App installation access changed or the connection test failed                                            | Restore access in GitHub, then select **Test connection**                                                                                                |
| **Authentication failed** / GitHub `401`                            | GitHub rejected the App credentials; this does not establish whether the repository exists                      | Ask the platform administrator to check the GitHub App credentials, then test again                                                                      |
| **Repository unavailable** / GitHub `404`                           | The App cannot find the repository; it may be deleted, renamed, transferred, or no longer accessible to the App | Open the repository's GitHub link and check its existence and App access before reconnecting                                                             |
| **Branch unavailable**                                              | The repository was reached, but its default branch could not be read                                            | Ensure the repository has an initial commit and a valid default branch, then test again                                                                  |
| **Repository changed**                                              | The saved name now identifies a different GitHub repository                                                     | Change any workspace connections first, remove the unused saved connection, and connect the intended repository again                                    |
| **Remove** is disabled                                              | One or more live workspaces still use the connection                                                            | Change their repository connection in **Source Control > Settings** first; deleted workspaces do not count as usage                                      |
| Integration controls are disabled or missing                        | Your effective role lacks organization settings permission                                                      | Ask an organization settings manager to manage the repository connection; a workspace connection grant alone does not grant organization settings access |
| Permissions could not be checked                                    | SteelEngine could not load your effective organization permissions                                              | Select **Check permissions again**; a failed check is different from denied access                                                                       |
| **Create and connect repository** is disabled after entering a name | The name is invalid, for example it contains spaces                                                             | Read the message beside **Repository name** and use letters, numbers, periods, hyphens, or underscores, such as `hello-there`                            |
| Target branch was not found                                         | The selected GitHub branch does not exist                                                                       | Open the branch selector, choose &#x2A;*Create branch…**, and select **Create from**; empty repositories need an initial commit first                    |
| **Save the environment changes above**                              | The mapping has unsaved changes                                                                                 | Save the binding before creating the protection PR                                                                                                       |
| Protected main is read-only                                         | Expected behavior for a protected workflow                                                                      | Select an open source-control branch or create **New branch**                                                                                            |
| Branch is behind its target                                         | The configured environment branch advanced after the branch was created                                         | Commit or discard local changes, then select **Update branch**                                                                                           |
| Branch is **conflicted**                                            | The branch and main changed the same workflow fields                                                            | Select **Resolve**, choose one resolution per conflict, and select **Resolve and update**                                                                |
| Commit is disabled                                                  | The branch is clean, the review is still loading, or the commit message is empty                                | Make or restore a change, wait for the reviewed revision, and enter a message                                                                            |
| Commit reports a changed remote head                                | GitHub advanced after SteelEngine loaded the branch                                                             | Refresh, then update the branch; SteelEngine will not force-push                                                                                         |
| Pull request Check fails                                            | Bundle, graph, dependency, secret-scan, or resource preflight validation failed                                 | Review the safe Check details and the job result, fix the branch, and commit again                                                                       |
| Pull request merged but main did not update                         | Webhook delivery was delayed, missed, or the final commit failed validation                                     | Select **Sync now** and review the latest apply job                                                                                                      |
| Deploy is blocked                                                   | Main has a sync error, does not match the applied commit, or has unresolved resource assignments                | Repair synchronization and save all required **Resource assignments**                                                                                    |
| **Sync now** shows **No result yet**                                | The worker has not reported back after about a minute                                                           | Check the job table on **Settings**, then confirm the worker is running and sync again                                                                   |
| Saving warns that hourly checks could not be scheduled              | The settings saved, but the Temporal schedule could not be set                                                  | Select **Sync now**, or **Sync approved changes** on production, which repairs the schedule                                                              |
| **Deploy synced version** is missing                                | The branch is ahead of the synced commit                                                                        | Sync first, then deploy                                                                                                                                  |
| Remote branch was deleted with dirty drafts                         | GitHub removed the ref while SteelEngine still has uncommitted work                                             | Select **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.
