Insites GitHub App

The Insites GitHub App connects a GitHub repository to your Insites instance. Once it is connected, every push to the branch your instance watches is deployed automatically, so your code lives in version control with a full history you can review and undo. It works through Insites CloudShell, so you set it up by asking your AI assistant.

On GitHub the app is listed as Insites CloudShell: github.com/apps/insites-cloudshell.

Why Use It

• Every change has a history. Each deploy comes from a commit, so you can see who changed what and when.
• Anyone can push. Your AI, a teammate, or your own Git tools can push to the repository, and the result deploys the same way.
• Work safely on branches. Only the watched branch deploys. Push work in progress to any other branch, and merge it when it is ready.
• Undo a change. Your AI can revert a commit and put the earlier version back.

Connecting a Repository

1. Ask your AI. With CloudShell connected and your instance selected, ask: Connect GitHub to my instance. Your AI replies with a one-time install link. It expires after ten minutes, so ask for a new one if you need it.
2. Install the app on GitHub. Open the link and install Insites CloudShell on the account or organization that owns the repository. When GitHub asks which repositories to allow, choose Only select repositories and pick the one repository for this instance.
3. Confirm the repository. If the app can see more than one repository, CloudShell shows a list so you can choose the right one. It then confirms the repository and the branch it will watch.
4. Check the connection. Ask your AI: Which repository is connected?

When the connection is made, CloudShell protects the watched branch on GitHub: nobody can force-push to it or delete it, so its history cannot be rewritten. GitHub only allows this protection where your plan supports it. On a free GitHub plan it applies to public repositories only.

How a Push Becomes a Deploy

1. Someone pushes. You, a teammate, or your AI pushes one or more commits to the watched branch.
2. GitHub tells CloudShell. GitHub sends a signed notice of the push. CloudShell checks the signature and ignores anything that did not come from GitHub, and any push to a branch it is not watching.
3. The deploy is queued. Deploys for an instance run one at a time, in the order the pushes arrived. If a deploy fails, CloudShell tries it again, up to three attempts in all.
4. CloudShell fetches and builds. It reads the whole repository as it was at that commit. If the repository has a package.json file at its root, CloudShell runs npm install and npm run build first.
5. The files are deployed. The files are deployed to your instance, and the result is recorded in the instance's deployment history.

What Gets Deployed

• Your repository mirrors your instance. Files deploy to the same paths they have in the repository, so keep your code in the standard Insites structure, such as app/views/pages/. See Codebase.
• The whole repository, every time. Each deploy sends every supported file in the repository at that commit, not just the files that changed.
• Supported file types: .liquid, .graphql, .json, .yml, .yaml, .html, .css, .js, .txt, .xml, .csv, .svg, .png, .jpg, .jpeg, .gif, .webp, .woff, .woff2, and .pdf. Other files, such as a README in Markdown, stay in the repository and are not deployed.
• Projects with a build step. If there is a package.json at the root, CloudShell deploys the contents of the dist folder your build produces instead. Make your build write its output into dist using the Insites folder structure.

Working with Branches

• One watched branch. Your instance watches one branch, and only pushes to that branch deploy. A new connection always starts by watching main. If your repository uses another name, such as master, change the watched branch straight after connecting.
• Other branches are safe. Ask your AI to push work to a feature branch, for example Push this to a branch called feature/contact-form. Nothing deploys until that work is merged into the watched branch.
• Change the watched branch. Ask your AI, for example Deploy from the staging branch from now on.

Undoing a Change

Ask your AI to revert a commit, for example Revert the last commit. It adds a new commit to the watched branch that puts the repository back exactly as it was before the commit you chose. Because that new commit lands on the watched branch, it deploys like any other push.

Checking Deploys

Ask your AI about any deploy in plain language, for example Did my last push deploy? or Show me the last five GitHub deploys. Each deploy shows its commit, its status, and when it ran. GitHub deploys also appear in the instance's full deployment history, alongside deploys made directly through CloudShell.

Disconnecting

Ask your AI: Disconnect GitHub from this instance. CloudShell removes the link and the branch protection it added, and pushes stop deploying. Uninstalling the Insites CloudShell app from your GitHub settings also disconnects the instance.

Who Can Do What

Related Pages

• Getting Set Up with Insites v6 and AI - set up your AI assistant and CloudShell first.
• CloudShell Tools - every GitHub tool your AI can use, with example prompts.
• Development Workflow - environments and the full development cycle.