Connect GitHub

Connect a GitHub repository and bind it to a SteelEngine workspace

Source Control setup has two boundaries: the organization owns approved repository connections, and each workspace selects a repository, branch, and workspace package. A package's managed path and source identity come from Git. Branch locking, workflow editing, and deployment are separate settings.

Open Source Control > Settings from the workspace sidebar to follow this setup in the workspace hub. Settings > Source Control remains an equivalent entry point. The workspace guide follows the complete setup, review, and release flow.

Workspace repository setup and the complete workspace capture, review, commit, and PR flow are available independently of workflow controls. Protect a workflow, individual editing branches, and workflow editor Git actions are paused in code. There is no environment opt-in. Existing protection and synchronization remain enforced.

Before You Start

You need:

  • Organization admin access or effective organization settings permission in SteelEngine to enable Source Control and manage repository connections
  • Permission to install or configure the SteelEngine GitHub App for the target GitHub account or organization
  • Workspace admin access, organization admin access, or an effective Manage source control policy grant to configure the workspace connection
  • Write access to an existing GitHub repository, or permission to create a new one

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

  1. Open Settings > Source Control in your workspace.
  2. Select Enable integration. Repository setup stays on this page, then continues to the workspace's repository connection. Individual workflow protection setup is unavailable.

You can also manage organization connections under Settings > Integrations > GitHub Source Control.

Enabling the integration only makes Source Control available to the organization. It does not protect or lock any workflow.

2. Connect Your GitHub Account

  1. In GitHub Source Control, select Connect GitHub account and authorize the Steel Engine App. The login returns to the page you started from. If it fails or expires, that page says so and you can connect again.
  2. If no GitHub accounts are available, select Install Steel Engine App and choose the account or organization that will own your repositories.
  3. Grant access to the repositories SteelEngine should manage. You can select individual repositories.
  4. Return to SteelEngine and select Refresh. Choose a Repository owner to browse its accessible repositories.

Only accounts where the current environment's GitHub App is installed appear in the owner list. To use another organization, select Add organization, grant repository access on GitHub, then return and refresh. An installation of the dev App does not grant the production App access.

Select Disconnect GitHub account to end this browser's setup login, then connect again when needed. This does not uninstall the App, remove saved repository connections, or stop running workflows. Manage the App's repository access through Manage access on GitHub.

Hosted SteelEngine uses a platform-managed GitHub App. You do not need installation IDs, personal access tokens, or an App private key. Authorization for browsing and creating repositories lasts up to one hour; reconnect your GitHub account when prompted. Existing repository connections continue working independently.

If the login returns to Your GitHub login expired because the setup or SteelEngine session could not be recovered, nothing was connected. Return to SteelEngine, sign in if needed, and start Connect GitHub account again from your workspace's Source Control settings.

3. Choose or Create a Repository

Browse repositories lists repositories accessible to both you and the App. Search by name, then select Connect. Archived repositories and repositories where you lack write access cannot be connected. Missing a repository? Open Manage access, add it in GitHub, return, and refresh.

To start fresh, select Create repository. Enter a name without spaces, using letters, numbers, periods, hyphens, or underscores (for example, hello-there). An invalid name displays an explanation beside the field and keeps Create and connect repository disabled until corrected. Optionally add a description, then choose Private (the default) or Public. Public repositories expose their workflow definitions to everyone. Select Create and connect repository. SteelEngine initializes the repository with a README and uses your GitHub permissions to create it in the selected account.

Creation requires the App's Repository creation write permission (or existing Administration write permission) and permission for your user to create repositories. Organization policies still apply. You can also create the repository on GitHub, grant the App access, and refresh.

If creation succeeds but connection fails, the repository remains in GitHub. Use Retry connection after fixing access; do not create it again. If a request times out, refresh the repository list before retrying creation.

After connecting, select Test connection. The repository should show Available before you bind a workspace. Errors and success messages appear directly in settings.

Check or Remove a Repository Connection

Test connection verifies the saved repository identity and its default branch. Authentication failed means GitHub rejected the App credentials; it does not prove the repository was deleted. Repository unavailable means the App cannot find it, which can also happen after a rename, transfer, or access change. Use the repository's GitHub link to check directly. A missing default branch is reported separately as Branch unavailable.

An organization manager with effective organization settings permission can select Remove beside an unused connection and confirm Remove connection. This removes the connection from SteelEngine's available repositories. It does not delete the GitHub repository, branches, or pull requests, and you can connect it again later. Historical source-control records are retained.

Repository status appears beside its name, with connection actions below the details. People without organization settings permission see an explanation, and management controls are hidden or disabled. If SteelEngine cannot check your permissions, select Check permissions again rather than assuming access was denied. Closing the removal dialog returns keyboard focus to its Remove button; after that row disappears, focus returns to the integration heading.

Connections used by workspaces show their workspace count and cannot be removed. Change those workspaces' repository connections in Source Control > Settings first. Deleted workspaces do not block removal; their historical records remain. Repository deletion or an access failure in GitHub does not automatically remove a saved SteelEngine connection.

The repository configured in Organization Releases is also in use and cannot be removed while that configuration references it.

On a self-hosted target, the same GitHub App webhook can notify both Workspace Source Control and Organization Releases. Each follows its configured repository and branch; an organization push notification only makes the next branch check due.

4. Bind the Workspace

  1. Open Source Control > Settings and select a connected Repository.
  2. Open Workspace branch to search existing branches. To create one, choose Create branch…, enter its name, choose Create from, and select Create branch. This creates a Git ref without connecting or deploying the workspace.
  3. Choose Publish workflows to Git to capture workflows authored here, or Receive workflows from Git to import reviewed definitions from this branch. A single receiving package is selected automatically; select by name and folder when several exist. For a branch with no package, enter the Expected package folder and save a receiving connection that waits for its first reviewed release.
  4. Set Lock to branch, Workflow editing, and Deployment independently. Workspace and organization admins, or policies granting Manage source control, control connection changes.
  5. Select Connect workspace. Saving does not synchronize or deploy a version.
  6. Publish from Changes by capturing workflows, reviewing files, and merging the capture PR. Use Promote to branch to review a PR into QA or Prod's branch. Receiving workspaces synchronize approved changes and deploy according to their own policy.

Follow the Dev, QA, and Prod walkthrough for a new repository. You can create QA and Prod and their branches first; save their receiving connections immediately with the expected package folder, then keep them empty until their first reviewed package arrives.

Workflow package names come from the selected branch's workspace.json manifest. A name such as Dev Workspace identifies captured workflows in Git. It is not a live-workspace selector. See where package names come from.

Workflow editing offers Git changes only for authoring workspaces as well as destinations. To change a saved policy, select it directly in Source Control > Settings; it saves immediately without entering Change connection. Authorized managers can restore Allow direct edits in the same menu.

A package received from Git must be connected to a workspace without workflows or folders, including archived definitions. Its source may be on another installation or in another organization; the destination uses its own authorized GitHub connection and local resource assignments. See Branch-connected workspaces.

Editing saved settings

Saved connections show a readable summary. Select Change connection to edit the repository, branch, and workflow direction, then Save connection or Cancel. The top Workspace branch selector also supports a confirmed branch change. Promote to branch opens a PR to another branch without changing the saved connection. Unlock changes only the branch-lock policy.

The Workflow editing and Deployment selectors remain available to authorized managers. Allow direct edits permits local drafts, while Git changes only requires approved Git updates. Deploy manually prepares drafts until you select Deploy synced version; Deploy automatically publishes after a validated synchronization. Saving any of these settings does not itself synchronize or deploy a commit. A receiving workspace also has New schedules: Start on deploy runs a newly promoted schedule as soon as its workflow deploys, and Start paused leaves it paused until you resume it.

The managed path uses letters, numbers, periods, underscores, hyphens, and /, up to 240 characters. Do not use spaces, .., .git, absolute paths, or backslashes. Every segment must be non-empty and cannot be .. One authoring workspace owns a repository/branch/path combination; several destination workspaces may follow it.

Existing environment labels remain descriptive. The explicitly selected branch determines pull request targets and synchronization. Existing legacy workflow protections and open branches must be resolved before retargeting an authoring binding; its branch lock remains configurable by authorized managers.

Saving a workspace connection explicitly makes it independent of Organization Releases, including when the old organization setup originally created that connection.

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:

  • User authorization callback URL: https://<your-steelengine-host>/api/source-control/github/callback
  • 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), Metadata (read-only), and Repository creation (write) to support creating repositories in settings
  • Webhook events: Push, Pull request, and Branch or tag deletion (used to detect a deleted remote branch that still has local changes)

Set these server-side environment variables:

VariableDescription
GITHUB_APP_IDGitHub App identifier
GITHUB_APP_CLIENT_IDOAuth client ID of this GitHub App
GITHUB_APP_CLIENT_SECRETOAuth client secret of this GitHub App
GITHUB_APP_PRIVATE_KEYPEM private key; escaped \n newlines are supported
GITHUB_APP_WEBHOOK_SECRETWebhook signing secret with at least 16 characters

Store these values in your deployment secret manager, then restart the web service. The background Worker also needs GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY. These credentials are separate from GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, which power workflow actions. Configure the callback and webhook for each deployment; changing the App homepage alone does not connect production.

For ECS deployments, seed the optional secret keys before applying task definitions (ECS requires referenced JSON keys to exist), populate their values, and roll out web and Worker tasks. Until all five values are configured, settings displays GitHub setup is unavailable. See Environment Variables for the full self-hosted configuration reference.

Separate Apps for Local, Dev, and Production

Keep a separate GitHub App registration and separate credentials for each environment:

EnvironmentGitHub App nameSite
LocalSteel Engine Local (<developer name>), for example Steel Engine Local (Jordan)The developer's local instance
DevSteel Engine Devhttps://dev.steelengine.com
ProductionSteel Engine Apphttps://app.steelengine.com

Each developer owns a distinct local App; do not change the shared Dev or Production App to point at localhost. App names must be unique on GitHub, so use the developer's GitHub handle when names collide. Give local and dev installations access to QA repositories only.

Use the callback and webhook paths above with the corresponding site's origin. Local OAuth can return to http://localhost:3000, but webhook delivery requires a public HTTPS tunnel to that local server. Without a tunnel, disable webhook delivery on the local App. Repository discovery, connection changes, and manual synchronization can still be tested with a running Worker; public push delivery cannot. Hourly reconciliation also requires Temporal and a running Worker.

When the application and public API use separate hosts, the authorization callback must use NEXT_PUBLIC_APP_URL so the setup cookies return to the same host. Webhook delivery can use the stable PUBLIC_API_URL. For hosted production, the callback is https://app.steelengine.com/api/source-control/github/callback, while the webhook remains https://steelengine.com/api/source-control/github/webhook.

The integration screen shows the App name returned by GitHub alongside the deployment host. Confirm both before QA. Changing the configured App ID, OAuth client ID, or site origin invalidates temporary setup authorization and requires reconnecting the GitHub account.

Confirm the Connection Is Ready

Before capturing or synchronizing a workspace, confirm:

  • Settings > Integrations > GitHub Source Control shows the repository as Available.
  • Test connection succeeds.
  • Source Control > Settings shows the expected repository, branch, and package.
  • The status strip names the intended branch and reports a successful synchronization.
  • For a package destination, the latest job and imported workflows match the package you selected. Synced alone does not confirm workflows were imported; see Synced, but workflows did not appear.
  • For a package destination, Workspace deployment shows the synchronized commit separately from the last successful deployment. Ready to deploy means manual publication is still pending.

If any item needs attention, resolve it before publication. See Troubleshooting for recovery steps.

On this page