# 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](/source-control/workspace-hub) 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](/self-hosting/releases/git-promotion) 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 &#x2A;*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](/source-control/production-workspaces#start-with-a-new-repository-and-dev-qa-and-prod) 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](/source-control/production-workspaces#where-workspace-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](/source-control/production-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.

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:

```text
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:

| Variable                    | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| `GITHUB_APP_ID`             | GitHub App identifier                                |
| `GITHUB_APP_CLIENT_ID`      | OAuth client ID of this GitHub App                   |
| `GITHUB_APP_CLIENT_SECRET`  | OAuth client secret of this GitHub App               |
| `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 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](/self-hosting/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:

| Environment | GitHub App name                                                                    | Site                           |
| ----------- | ---------------------------------------------------------------------------------- | ------------------------------ |
| Local       | `Steel Engine Local (<developer name>)`, for example `Steel Engine Local (Jordan)` | The developer's local instance |
| Dev         | `Steel Engine Dev`                                                                 | `https://dev.steelengine.com`  |
| Production  | `Steel Engine App`                                                                 | `https://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](/source-control/troubleshooting#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](/source-control/troubleshooting) for recovery steps.
