GitHub codebase connectivity

What is GitHub codebase connectivity?

GitHub codebase connectivity lets Alloy work against a real repository instead of only a captured prototype. Once GitHub is connected, Alloy can open a live workspace, run automatic Workspace Setup, and preview changes against your actual codebase.

The current path forward is Docker Compose. Workspace Setup creates a pull request that adds the runtime files Alloy needs, usually docker-compose.alloy.yaml and .alloy/environment.json. After that pull request is merged, the checked-in environment file becomes the source of truth for how Alloy boots the repository.

Connect GitHub and choose a repository

1. Open the settings dropdown in your Alloy workspace.

2. Go to the GitHub section in workspace settings and select Connect GitHub.

3. Sign in to GitHub and choose the personal account or organization Alloy should access.

4. Select the repositories you want to make available to Alloy.

5. Back in Alloy, select the repository you want to work on from the list.

Screenshot placeholder: Add the latest repository picker screenshot here once the updated flow is finalized.

Run Workspace Setup

After choosing a repository, run Workspace Setup. Alloy opens a setup workspace, inspects the app, identifies the commands and services needed to run it, and iterates on a Docker Compose configuration until the app can render in an Alloy preview.

When setup finishes, Alloy opens a pull request for you to review. The expected output is:

• A pull request that contains the generated workspace configuration.
• A checked-in compose file. In most new setups this will be docker-compose.alloy.yaml, but it can be another repo-relative path if that is the better fit.
• A checked-in .alloy/environment.json file that points to that compose file and, when needed, tells Alloy which frontend port to proxy.

Example .alloy/environment.json:

{
  "dockerComposePath": "./docker-compose.alloy.yaml",
  "frontendPort": 3000,
  "homeUrl": "/"
}

For compose-based setups, dockerComposePath is required. Add frontendPort when the app listens on a port other than 8080; if it is omitted, Alloy assumes the frontend is already available on 8080 and skips the preview proxy. Add homeUrl when the app should open somewhere other than /, and add loginScript only when the preview needs a scripted login step.

Screenshot placeholder: Add the Workspace Setup CTA screenshot here.

Screenshot placeholder: Add the Workspace Setup session result screenshot here.

Checked-in environment config becomes the source of truth

When Alloy sees a checked-in .alloy/environment.json, the Environment configuration section in GitHub settings becomes read-only. This prevents the checked-in repo config and the database copy from drifting apart.

The settings pane will show a subdued message explaining that Alloy found .alloy/environment.json in the repository. Alloy also syncs the contents of that file back into the stored environment_config value so previews and backend jobs stay aligned.

If the checked-in file is invalid JSON, Alloy keeps the section locked and shows an error until the file is fixed or removed from the repository.

Screenshot placeholder: Add the locked Environment configuration section screenshot here.

Gotchas

• Modal's Docker-in-Sandboxes support is still in alpha. See Docker in Sandboxes and the broader Sandboxes docs.
• Docker daemon state is not preserved in Modal filesystem snapshots. If a workspace depends on Docker, the daemon may need to start again when a sandbox resumes.
• Alloy sandboxes enable Docker through Modal's Docker-in-Sandboxes support, but Docker validation can still need a daemon started with flags like dockerd --iptables=false --bridge=none.
• That daemon workaround is only for sandbox reliability. Your checked-in compose file may still need network_mode: host if the repository's runtime requires it.
• If your compose setup needs secrets or API keys, add them in Alloy's Secrets section before expecting the preview to boot cleanly.

Common questions

What if my repository already has a compose file? Reuse it if it is the right setup for Alloy previews. The important part is that .alloy/environment.json points to the actual checked-in compose path relative to the repo root.

What if the repository does not appear in the picker? Check that you connected the correct personal account or organization, and that Alloy has access to the repository in GitHub. If your org requires admin approval for GitHub Apps, ask an org owner to approve the install and then refresh the repository list in Alloy.

Can I still type JSON into Environment configuration manually? Yes, but only when .alloy/environment.json is not present. Once the checked-in file exists, Alloy treats it as canonical and locks manual editing.

What keys can .alloy/environment.json include? Use dockerComposePath for the repo-relative compose file path, optional frontendPort for the port Alloy should proxy, homeUrl for the first route to open, and loginScript only when Alloy needs a scripted login step. Omit frontendPort when the app already serves on 8080.

The schema is:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["dockerComposePath"],
  "properties": {
    "dockerComposePath": {
      "type": "string",
      "description": "Repo-relative path to the checked-in Docker Compose file, for example docker-compose.alloy.yaml."
    },
    "frontendPort": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "description": "Optional port where the user-facing frontend listens inside the sandbox, for example 3000, 5173, or 8000. Omit this when the frontend already listens on 8080."
    },
    "homeUrl": {
      "type": "string",
      "description": "Path-only route to open after the stack starts, such as /, /auth/login, or /api/dev/auth."
    },
    "loginScript": {
      "type": "string",
      "description": "Optional JavaScript injected once into the proxied app page when needed to reach a usable logged-in state."
    }
  }
}

Do I still need services or images in the environment config? No for new setups. Docker Compose is the forward path, so new Workspace Setup flows should use dockerComposePath instead.