Source Control setup has two boundaries: the organization owns approved repository connections, and each workspace selects one connection plus a unique managed path.
Before You Start
You need:
- Organization admin access in SteelEngine to enable Source Control and connect a repository
- Permission to install or configure the SteelEngine GitHub App for the target GitHub account or organization
- Workspace admin access to create the repository binding
- An existing GitHub repository with a default branch
GitHub for workflow actions and GitHub Source Control are separate integrations. Personal GitHub OAuth connections power workflow blocks. The organization-owned GitHub App powers repository review and synchronization.
1. Enable the Organization Integration
- Open the workspace and go to Settings > Integrations.
- Search for and select GitHub Source Control.
- Select Enable integration.
Enabling the integration only makes Source Control available to the organization. It does not protect or lock any workflow.
2. Install the GitHub App
- In GitHub Source Control, select Install or configure GitHub App.
- In GitHub, choose the account or organization that owns the repository.
- Grant access to the repositories SteelEngine should manage. Prefer selecting only the repositories intended for workflow source control.
- Return to SteelEngine and select Continue with installation details.
Hosted SteelEngine uses one platform-managed GitHub App. You do not need to create an app, add environment variables, or manage its private key.
3. Verify the Repository
Enter the following installation details:
| Field | Value |
|---|---|
| GitHub App installation ID | The number at the end of the GitHub installation URL |
| Repository owner | The GitHub account or organization name |
| Repository name | The repository name without the owner or URL |
Select Connect repository. SteelEngine verifies the installation, resolves the repository's immutable ID and default branch, and stores the connection for the organization.
After connecting, select Test connection. The repository should show Active with a recent Last checked time before you bind a workspace.
SteelEngine mints short-lived GitHub App installation tokens when needed. It does not store a personal access token or expose an installation token to the browser.
4. Bind the Workspace
- Go to Settings > Source Control.
- Under Workspace binding, select a connected Repository.
- Enter a Managed repository path, such as
automation/workspaces/customer-operations. - Select Save binding.
SteelEngine manages protected workflows below:
automation/workspaces/customer-operations/workflows/<workflow-id>/Use letters, numbers, periods, underscores, hyphens, and / path separators. Do not use spaces, .., .git, absolute paths, or backslashes. A repository/path pair can belong to only one workspace.
Treat the path as durable once workflows are protected. If you need to move the workspace to another path or repository, unprotect its workflows first.
Multiple Workspaces in One Repository
Give each workspace its own prefix:
automation/
workspaces/
customer-operations/
workflows/
finance/
workflows/Each workspace still has one active binding, but an organization can connect multiple repositories and reuse a repository across distinct workspace paths.
Self-Hosted Setup
Self-hosted operators create and configure the GitHub App once for the whole SteelEngine deployment. Workspace members then use the same in-product flow as hosted customers.
Configure the GitHub App with:
- Webhook URL:
https://<your-steelengine-host>/api/source-control/github/webhook - Repository permissions: Contents (read and write), Pull requests (read and write), Checks (read and write), and Metadata (read-only)
- Webhook events: Push and Pull request
Set these server-side environment variables:
| Variable | Description |
|---|---|
GITHUB_APP_ID | GitHub App identifier |
GITHUB_APP_PRIVATE_KEY | PEM private key; escaped \n newlines are supported |
GITHUB_APP_WEBHOOK_SECRET | Webhook signing secret with at least 16 characters |
Store the private key and webhook secret in your deployment secret manager, then restart the web service. See Environment Variables for the full self-hosted configuration reference.
Confirm the Connection Is Ready
Before protecting a workflow, confirm:
- Settings > Integrations > GitHub Source Control shows the repository as Active.
- Test connection succeeds.
- Settings > Source Control shows the workspace binding as Active.
- The Applied commit matches the repository default branch baseline.
If any item needs attention, resolve it before protection. See Troubleshooting for recovery steps.