GitHub codebase connectivity

GitHub codebase connectivity lets you connect a personal account or organization, choose the repository Alloy should work in, and configure the workspace so live previews can install, boot, and refresh correctly.

What is GitHub codebase connectivity?

GitHub codebase connectivity lets Alloy work against a real repository instead of a captured prototype. Connect a GitHub account or organization, pick a repository, and Alloy will open a live workspace where you can make and preview changes in real time.

If you don't have a repository ready, start from the github-integration-template. It's a full-stack starter with a Next.js frontend, a Fastify REST API, and a workspace config you can paste straight into Alloy.

Connect GitHub to your workspace

Open your workspace settings and follow the GitHub connection flow.

Open the settings dropdown in your Alloy workspace.

Opening the settings dropdown in Alloy

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

Workspace GitHub settings pane

Selecting a GitHub account or organization

Select the repositories you want to make available to Alloy.

GitHub repository selection screen

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

Selecting the active repository in Alloy workspace settings

Configure the workspace

Paste the environment config so Alloy knows how to install and start your app.

{
  "homeUrl": "/",
  "services": [
    {
      "name": "site",
      "start": "cd site && npm run dev",
      "install": "cd site && npm install"
    },
    {
      "name": "api",
      "start": "cd api && npm run dev",
      "install": "cd api && npm install"
    }
  ]
}

The frontend must run on port 8080. The preview environment only exposes this port. The integration template handles this automatically — if you're bringing your own repository, configure your frontend dev server to listen on port 8080.

Workspace config field in Alloy

Add environment variables (if needed)

If your app requires secrets or API keys to boot, add them before starting the preview.

Open the environment variables section in workspace settings.
Add each variable your app expects, using the exact names from your .env.example or deployment config.
Save and restart the preview so the running services pick up the new values.

If you're using the integration template as-is, you likely won't need any extra variables to get started.

Make your first change

Once the preview is running, describe a change in the prompt box and Alloy will apply it to the live workspace.

Making a change in the Alloy prompt box

Common questions

What if the repository doesn't appear in the picker? Check that you connected the correct account or organization, and that you granted Alloy access to the repository during the GitHub authorization step. If your organization requires admin approval for third-party app installs, ask an org owner to approve it. After changing GitHub permissions, refresh the repository list in Alloy.

My frontend isn't loading in the preview. Confirm the frontend dev server started and is listening on port 8080. If you added or changed an environment variable, restart the preview — running processes don't reload automatically.

What is the GitHub integration template? It's a full-stack demo app at Index-Technologies/github-integration-template with a Next.js frontend (site) and a Fastify REST API (api) backed by SQLite. It includes auth, a dashboard, project management, and an activity feed. Default login: admin / password. Demo accounts: jane / jane123 (Designer) and john / john123 (Developer).

Do I need environment variables for the integration template? No — the template runs without any extra variables out of the box.

Can I use my own repository structure? Yes. Adjust the services config to match your directory names and start commands. The only hard requirement is that the frontend runs on port 8080.