Sync Blueprints from GitHub
Apply version-controlled service configuration when your Blueprint file changes.
Repository synchronization connects a saved Blueprint to one GitHub repository, branch, and YAML path. A workspace owner or admin authorizes automatic sync.
Connect the source
- Install or configure the Openstead GitHub App for the workspace and grant access to the Blueprint repository. This is required even for a public repository.
- Open the Blueprint and enter its repository URL.
- Select the branch and YAML path. Defaults are
mainandopenstead.yaml. - Enable Sync YAML automatically from GitHub and save.
- Check the imported manifest and resulting services.
You can save a repository draft without pasting YAML. Use the page's GitHub connection controls if access needs updating; completing authorization returns you to Blueprints.
Existing Blueprints keep their configured YAML path. If you rename a manifest to openstead.yaml, update the Blueprint's path to match.
Decide when to deploy
Deploy new or changed services after syncing queues releases for synchronized changes. Paid terms must already cover the requested capacity. If admission fails, the whole configuration synchronization rolls back.
For a new paid application, first sync with deployment disabled. Complete checkout and configure secrets, then deploy the services and enable deployment after sync if appropriate.
Each service can also use configuration.autoDeploy: commit for ordinary code pushes. A release already queued by Blueprint synchronization is not duplicated by the regular push handler for the same commit and configuration.
What triggers a sync
Changes to the selected YAML path on the selected branch trigger synchronization. Events for other branches, deleted branches, unrelated installations, and pull requests do not apply that YAML.
The worker reads the file from an immutable commit and applies validated changes together. Existing valid configuration remains available if importing or validation fails. Temporary GitHub failures retry up to five attempts.
Use Sync now to import the current branch immediately or retry after fixing a problem. It works with automatic sync enabled or disabled. A newer synchronization request supersedes older pending work.
Understand the status
The Blueprint page displays synchronization progress, the last applied commit, last sync time, errors, and retained service names. synced means the configuration was applied. Inspect each service's deployment to confirm it became live.
While automatic sync is enabled, edit the YAML in GitHub. The dashboard prevents editing an unimported local draft as though it were the repository source.
Authority and access
The owner or admin who enabled synchronization must retain active, verified workspace access and satisfy its MFA policy. GitHub App access is checked again when reading the repository. If authority changes, another owner or admin can reconnect sync or use Sync now.
Disabling automatic synchronization invalidates pending sync work without deleting the Blueprint's services.
Resolve common failures
| Failure | Resolution |
|---|---|
| Repository access denied | Grant the connected Openstead GitHub App access to the selected repository. |
| YAML file not found | Check branch, filename, case, and path relative to the repository root. |
| Invalid configuration | Validate against the YAML reference. |
| Paid deployment rejected | Sync without deployment, complete service checkout, then deploy. |
| Bound service changed manually | Resolve its move, rename, archive, or deletion before syncing again. |
| Service name already in use | Choose a unique name or resolve the existing service explicitly. |
| Owner/admin access required | Reconnect synchronization with a current authorized workspace account. |
Removing a service from YAML retains it. Delete a retained service through the project only when you intend to remove that resource and its data.