Developers · Build with AI
Insites GitHub App
Last updated 18 November 2026
Connect a GitHub repository to your Insites site so every push to the watched branch deploys automatically.
The Insites GitHub App connects a GitHub repository to your Insites site. Once it is connected, every push to the branch your site watches is deployed automatically, and every change made on the site itself is committed back to the repository, so your code lives in version control with a full history you can review and undo. It works through Insites CloudShell. You can set it up by asking your AI assistant, or from the site's page in the Console.
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 files back as they were.
- Changes on the site are kept too. A page edited in the Site Admin, or a file your AI deploys directly, is committed to the repository as well, so the repository always matches the site.
Connecting a Repository
- Ask your AI. With CloudShell connected and your site selected, ask:
Connect GitHub to my instance.If you name a repository the app already sees, for exampleConnect the repository acme/website to this instance, the link is made straight away. Otherwise your AI replies with a one-time link. It expires after one hour, so ask for a new one if you need it. If it has already been used, it says so. - Choose or add the repository. The link opens a page that lists the repositories the app already sees for your account. Pick one, or choose Add a repository on GitHub to 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 site. A repository that is already selected on the app can be connected to another site the same way.
- Confirm the repository. CloudShell confirms the repository and the branch it will watch: the repository's default branch.
- Check the connection. Ask your AI:
Which repository is connected?
Important
Choose Only select repositories and a single repository. If you give the app access to all repositories, it may pick the wrong one and you will need to correct it.
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.
From the Console
Open the site in the Console. The Repository card on its Overview tab shows the linked repository, the watched branch, when it was linked, whether deploy on push is on, and the last deployment. Choose Link repository to connect an existing repository the app already sees, to add one on GitHub, or to create a new repository on a GitHub organization. A new repository starts with the site's current code. After you give Insites access on GitHub, the page returns to the Console and closes. Creating a repository on a personal GitHub account is not available yet; create it on an organization, or connect an existing repository.
A site has one link. To move it to another repository, unlink it first, then link again. Linking again offers your account's repositories.
How a Push Becomes a Deploy
- Someone pushes. You, a teammate, or your AI pushes one or more commits to the watched branch. Every site that watches that branch, with deploy on push turned on, is deployed. A push made up only of a site's own commits is skipped for that site, so a change saved on the site is not deployed back onto it.
- 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.
- The deploy is queued. Deploys for a site run one at a time, in the order the pushes arrived. If a deploy fails, CloudShell tries it again after 60 seconds, up to three attempts in all.
- CloudShell fetches and builds. It reads the whole repository as it was at that commit. If the repository has a
package.jsonfile at its root, CloudShell runsnpm installandnpm run buildfirst. - The files are deployed. The files are deployed to your site, and the result is recorded in the site's deployment history.
What Gets Deployed
- Your repository mirrors your site. 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.jsonat the root, CloudShell deploys the contents of thedistfolder your build produces instead. Make your build write its output intodistusing the Insites folder structure. - Deploy on push can be turned off. The Repository card in the Console has a Deploy on push setting. With it off, pushes are not deployed, but changes on the site are still committed to the repository, so the repository stays a record of the site.
Changes on the Site Are Committed Back
Once a repository is linked, the repository follows the site as well as the other way round. When a page, partial or other file is created, updated, deleted or renamed in the Site Admin, CloudShell commits that change to the watched branch. A file your AI deploys directly, syncs or deletes through CloudShell is committed in the same way.
- Each commit says where it came from. A commit made from the site carries a note naming the site, so you can tell it apart from a commit a person or an AI pushed.
- It does not deploy back. A push that contains only the site's own commits is not deployed to that site, so an edit in the Site Admin is saved once, not deployed again. Another site watching the same branch still receives it.
- If the branch moved while the commit was being made, CloudShell tries the commit again, up to three times.
- Change each file through one route where you can. If two people change the same file at the same moment, one in GitHub and one in the Site Admin, the later change wins, as it would with any shared repository.
Tip
Keep secrets such as API keys out of your repository. Store them as environment variables instead: ask your AI to set one, and read it in your code from the site.
Working with Branches
- One watched branch. Your site watches one branch, and only pushes to that branch deploy. A new connection watches the repository's default branch on GitHub. If you want a different branch, change the watched branch straight after connecting. Several sites can watch the same branch, and a push to it deploys every one of them.
- 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.The branch protection moves to the new branch. If the watched branch is deleted or renamed on GitHub, nothing deploys until you change the watched branch.
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.
Important
A revert restores the whole repository to the moment before the chosen commit. If you revert an older commit, the changes from every commit after it are removed too. To undo one change from the middle of the history, ask your AI to make a new commit that reverses just that change instead.
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 site's full deployment history, alongside deploys made directly through CloudShell.
Disconnecting
Ask your AI: Disconnect GitHub from this instance. Or open the site in the Console and choose Unlink on the Repository card. CloudShell removes the link and the branch protection it added, pushes stop deploying, and changes on the site stop being committed.
If the Insites CloudShell app is uninstalled from GitHub, every site linked through that installation stops: the Console shows that backup and deploy on push have stopped, and the link stays in place until you unlink it or install the app again.
Who Can Do What
| Action | Lowest role needed by default |
|---|---|
| See the connection, browse files, list commits and deploys | Viewer |
| Push to another branch, change the watched branch | Editor |
| Connect or disconnect, push to the watched branch, revert, turn deploy on push on or off | Developer |
Related Pages
- Getting Set Up with Insites 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.