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.
Start with Status
Check both settings surfaces:
- Settings > Integrations > GitHub Source Control shows organization enablement, connected repositories, connection health, and Test connection.
- Settings > Source Control shows the workspace binding, last synchronized time, applied commit, Sync now, Full resync, and recent validation/apply jobs.
Then open the workflow and read the branch and protection status in the source-control bar.
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 > Integrations > GitHub Source Control, enable it, and connect a repository |
| Connect a repository first | The workspace has no active repository/path binding | Open Settings > Source Control, select a repository and managed path, then Save binding |
| 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 |
| Protected main is read-only | Expected behavior for a protected workflow | Select an open source-control branch or create New branch |
| Branch is behind main | The repository default branch advanced after the branch was created | Commit or discard local changes, then select Update branch from main |
| 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 |
| 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 a default-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.
Merge a repair or revert commit in GitHub, then select Sync now. 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 default-branch history.
- Review the rewritten history and choose the commit the organization accepts.
- Open Settings > Source Control.
- Select Full resync.
- 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.
- Open the protected workflow on
main. - Select Configure resource assignments in the source-control bar.
- Map every required role to an accessible workspace connection or credential.
- Select Save assignments.
- 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:
- Open the protected workflow on
main. - Select Unprotect.
- Confirm with Request unprotect.
- 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 default-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.