# Deploy from GitHub

> Deploy an app from a GitHub repository, release changes after a merge, and optionally send runtime variables from your pipeline.

Source: https://docs.stacksync.com/enterprise-os/applications/github-deployments

A repository should be enough to start deploying an application. EOS can build your app directly from GitHub, publish its first version from the dashboard, and deploy future changes when a pull request is merged into your chosen branch. You do not need a terminal or a GitHub Actions workflow for this flow.

## Choose a deployment mode

| Mode                                          | What starts a deployment                                                                    | Where runtime variables come from                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Deploy on merge — no workflow required**    | A GitHub App webhook after a pull request is merged into the configured branch.             | Variables already saved in EOS.                                                      |
| **Deploy from pipeline — send variables**     | The generated GitHub Actions workflow submits the merged commit and selected values to EOS. | Your pipeline supplies the configured names; other saved EOS variables are retained. |
| **Deploy now from current GitHub repository** | You choose to deploy the current state of the saved branch, before another merge.           | Saved EOS variables. Values available only in a pipeline are not loaded.             |

Terminal deployments and redeploying a retained version from **Deployments** remain available. Each EOS app has one configured GitHub repository and target branch. A direct push to the branch is not a merged pull request and does not trigger the default merge flow.

## Before you start

Sign in to a claimed EOS workspace. Creating an app requires workspace membership; configuring an existing app requires **Editor** or **Owner** access. Your GitHub account must be able to authorize the Stacksync GitHub App for the repository. An organization may require an owner to approve the installation or repository access.

The GitHub App needs read access to repository contents and pull requests. EOS checks both the app installation's access and your GitHub account's access when you choose a repository.

## Create an app without the terminal

1. Open **Applications** and select **Deploy a new app from GitHub**.
2. Enter an application name using lowercase letters, numbers, and hyphens.
3. Optionally enter runtime variables, one `NAME=value` per line. EOS stores these values; they are not sent to GitHub or committed to your repository.
4. Select **Continue to GitHub** and authorize access with the GitHub account you want to use. If no installation is available, use **Install GitHub App** and grant access to the repository.
5. Return to the app's **Deploy from GitHub** tab and select the repository and target branch.
6. Leave **Application directory** as `.` for the repository root, or enter a relative subdirectory such as `apps/portal`.
7. Choose **Deploy on merge — no workflow required**, leave automatic deployments enabled, and select **Save configuration**.
8. In the prompt, select **Deploy now from current GitHub repository** to publish the branch's current state. You can instead wait for the next merge.

Creating the app reserves its configuration; it does not start a build until you explicitly deploy or an enabled trigger runs.

<div data-with-frame="true">
  <figure><img src="/images/enterprise-os/github-create-app.png" alt="The new GitHub app dialog in the Stacksync EOS workspace asks for an application name and optional runtime variables, with Continue to GitHub as the next action." width="1600" height="1050" loading="lazy" decoding="async" /><figcaption>Create an app and save its runtime variables in EOS before choosing its GitHub repository.</figcaption></figure>
</div>

## Connect an existing app

Open **Applications → your application → Deploy from GitHub**, then select **Connect to GitHub App**. Authorize GitHub, select the repository and branch, and save the configuration. Existing installations are reused; you do not need to install the App again for each EOS application.

**Save configuration** stays disabled until valid settings differ from the saved configuration. Saving a new or changed configuration offers an immediate deployment. Saving alone does not deploy, and declining the prompt keeps the saved configuration for future merges.

<div data-with-frame="true">
  <figure><img src="/images/enterprise-os/github-connect-app.png" alt="The partner-crm application's Deploy from GitHub tab in the Stacksync EOS workspace offers Connect to GitHub App." width="1600" height="1050" loading="lazy" decoding="async" /><figcaption>Connect an existing EOS application from its Deploy from GitHub tab.</figcaption></figure>
</div>

## Add repository access

Select **Add repositories** in a connected app. EOS opens the existing GitHub installation's settings in a new tab. Add the repositories under repository access, save on GitHub, and return to EOS. Repository and branch dropdowns refresh automatically when you return or interact with them; valid selections and unsaved form edits are preserved.

Adding access does not change an app's saved repository. Select the newly available repository and branch, then save to change that application's deployment source. If GitHub authorization has expired, disconnect and reconnect to renew repository selection. Disconnecting stops future GitHub deployments for that app and leaves its running version available.

## Deploy after a merge

With **Deploy on merge** enabled, merging a pull request into the selected target branch sends a signed GitHub webhook to EOS. EOS fetches the exact merged commit, builds the configured application directory, and deploys it with the saved runtime variables. No workflow file or EOS API key is required in the repository.

Use **Recent GitHub deployments** to follow the commit and deployment request. Open **Deployments** for version details and build output. The previous successful revision remains **Healthy and serving traffic** while a new revision builds, fails, or is cancelled. The green badge moves after the new deployment succeeds. An app with no successful deployment has no serving revision yet.

To pause future automatic deployments, clear **Enable automatic deployments** and save. Explicit manual deployments remain available. Changing or disconnecting the GitHub configuration invalidates work queued against the old configuration.

## Environment variables without committing secrets

For the default merge flow, save variables in EOS when creating the app or manage them through the deployment's **Environment** tab. GitHub only notifies EOS about the merge; it does not need to store or send those values.

If your deployment pipeline already loads configuration from a secret manager or another approved source, use **Deploy from pipeline — send variables**:

1. Select pipeline mode in **Deploy from GitHub**.
2. Enter only the variable **names** to receive from the pipeline, one per line, and save.
3. Select **View workflow** or **Download workflow**. Save the generated file as `.github/workflows/eos-deploy.yml` on the selected branch.
4. Add your existing configuration-loading step before **Submit to EOS**. Make the selected values available to that step through its environment or GitHub Actions' `GITHUB_ENV` mechanism. Keep secret values out of logs and source control.
5. Merge a pull request into the configured branch. The workflow authenticates to EOS with a short-lived GitHub OIDC identity and submits the commit and selected runtime values.

You can use GitHub Actions secrets if that is your chosen secret store, but they are not required. EOS receives values from the running workflow; it does not read secret values back from GitHub's settings. The configured names must match the submitted values. Other saved EOS variables are retained.

In pipeline mode, merge webhooks do not start a second deployment. A successful **Submit to EOS** step means the request was queued; follow the actual build in EOS. Update the generated workflow after changing the target branch or variable names. Fork-originated pull requests can be subject to GitHub Actions permission restrictions; check that the workflow can obtain its OIDC identity and run its configuration-loading step.

These are **runtime** variables. They are not injected into compilation or frontend bundles. An explicit **Deploy now from current GitHub repository** uses saved EOS values, even in pipeline mode; it does not execute your workflow to retrieve new values.

## Use the CLI

Requires **EOS CLI 5.4.1** or later. Run `eos update`, sign in, and select the intended workspace. `APP` accepts an app name or numeric ID.

```sh
eos app github create partner-portal --variables-file runtime-variables.json
eos app github connect partner-portal
eos app github repositories partner-portal --json
eos app github branches partner-portal REPOSITORY_ID --json
```

`connect` opens the app's GitHub tab. Complete authorization in the browser with the same EOS account as the CLI. This keeps GitHub consent and browser authentication interactive; an API token alone does not authorize a GitHub repository. Use `--json` to return the browser URL without opening it.

Save a configuration file such as `github.json`:

```json
{
  "repository_id": "123456789",
  "branch": "main",
  "root_directory": ".",
  "mode": "merge",
  "enabled": true,
  "variable_names": []
}
```

Replace the example repository ID with one returned by `repositories`.

```sh
eos app github configure partner-portal github.json
eos app github deploy partner-portal
eos app github show partner-portal --json
```

`configure` saves settings; `deploy` explicitly queues the saved branch's current state using saved EOS variables. `show` returns the connection and recent requests. For pipeline mode, set `mode` to `pipeline`, list the expected names in `variable_names`, and download its workflow:

```sh
eos app github workflow partner-portal --output eos-deploy.yml
eos app github disconnect partner-portal
```

Move the downloaded workflow to `.github/workflows/eos-deploy.yml` after review. `--output` refuses to overwrite an existing file. Configuration and runtime-variable JSON inputs also accept `-` for standard input. Keep variable files private and outside source control.

## API and troubleshooting

Management endpoints are scoped to an EOS workspace and require the same permissions as the dashboard:

| Method                 | Path                                                     | Purpose                                                                         |
| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `POST`                 | `/api/access/github/apps`                                | Create an app with optional saved runtime variables, without deploying it.      |
| `GET`, `PUT`, `DELETE` | `/api/access/apps/{id}/github`                           | Read, save, or disconnect configuration.                                        |
| `POST`                 | `/api/access/apps/{id}/github/connect`                   | Begin browser-bound GitHub authorization.                                       |
| `GET`                  | `/api/access/apps/{id}/github/repositories`              | List repositories accessible through the user's current GitHub authorization.   |
| `GET`                  | `/api/access/apps/{id}/github/branches?repository_id=ID` | List branches for an authorized repository.                                     |
| `POST`                 | `/api/access/apps/{id}/github/deploy`                    | Queue the saved branch's current state; send the saved connection's `revision`. |
| `GET`                  | `/api/access/apps/{id}/github/workflow`                  | Retrieve the generated workflow for pipeline mode.                              |

Use the workspace URL prefix `/workspace/{workspace_id}` or the supported workspace header for management calls. See the current [EOS OpenAPI specification](https://eos.stacksync.com/openapi.json) for request schemas. The webhook, OAuth callback, and pipeline-submission endpoints use their respective GitHub authentication mechanisms; they are not ordinary personal-token deployment endpoints.

* **A repository is missing:** check GitHub installation access and your own repository permissions, then return to EOS. Renew expired authorization by reconnecting.
* **A merge did not deploy:** check the saved target branch, automatic-deployment setting, installation access, and selected mode. Pipeline mode also requires its workflow to complete submission.
* **Manual deployment was rejected after changing settings:** save or reload the configuration and retry. EOS checks its revision to avoid deploying with stale settings.
* **The build failed:** inspect **Deployments** and confirm the application directory, manifests, start command, and use of the supplied `PORT`.
* **Source retrieval failed:** check installation access and repository size. Git submodules and Git LFS files are not supported by this GitHub source flow.