Skip to content

Developers · Setup

Development Workflow

Last updated 18 November 2026

This guide covers the recommended development workflow for building and deploying Insites applications. A good workflow saves time, reduces errors, and gives your team confidence that what goes to production has been properly tested.

Environments

Insites uses a multi-environment setup that separates development from production. You create and manage sites through the Console.

  • Local codebase - Your working copy of the project on your machine. This is where you write and edit code. Changes are synced to a development site in real time using the CLI.
  • Staging site - A testing environment that mirrors production. Use it for QA, client review, or user acceptance testing (UAT). Emails on staging sites are suppressed, so you can safely test workflows without emailing end users. To receive them yourself, add recipients in your Site Admin under Settings > Site Configuration > Email Notifications.
  • Production site - The live environment that your users interact with. Only deploy code here after it has been tested on staging.

Note

If you have a larger development team, consider setting up multiple staging sites so each developer can work independently. You can add a shared integration site where developers merge code to resolve conflicts, and a separate UAT site for client testing.

The Development Cycle

A typical development cycle follows this flow:

  1. Write code locally. Edit Liquid templates, GraphQL queries, schema definitions, and assets in your local codebase.
  2. Sync to your development site. Run to push changes to your site in real time. The sync command watches for file changes and sends them to the server as they happen. It feels like working on localhost.
  3. Test on staging. When you have a release candidate, deploy to your staging site using . Run through your test plan, verify workflows, and get client sign-off if needed.
  4. Deploy to production. Once staging is verified, deploy the same codebase to your production site. Run first to see what will change. A full deploy removes files that are not in your release.

Note

Use sync only for staging environments. Pushing changes immediately to production can be dangerous. Always use for production deployments.

Developing with an AI Assistant

Instead of syncing with the CLI, you can have an AI assistant write and deploy your code. The environments above stay the same: you point your AI at the site you want to work on, and it deploys there through Insites CloudShell.

  1. Describe the change. Tell your AI what you want. With the Insites Logic Engine, it writes code that follows Insites conventions.
  2. Deploy to your site. Your AI selects the site and deploys the files, then checks the deploy status and logs.
  3. Use GitHub for version control. Connect a repository and your AI commits its work instead. Every push to the watched branch deploys automatically, and any commit can be reverted.

See Getting Set Up with Insites and AI for the full setup.

Version Control

We recommend using a version control system like Git, though it is not required. All you need to work with Insites is your codebase and a site to sync or deploy to.

If you use Git, a common workflow is:

  • Each developer works on their own branch and syncs to their own development site.
  • Feature branches are merged into the main branch after review.
  • The main branch is deployed to staging for testing, then to production for release.

This approach keeps production-ready code separated from work in progress and makes it easy to roll back if something goes wrong.

The CLI has no command for comparing or rolling back. Git and the commands below do these jobs.

Get an Existing Site into Git

downloads the site's whole folder. Modules come separately, one each. Pull only your project's own modules, not the Insites modules every site has.

insites-cli pull staging -p app.zip
unzip -o app.zip && rm app.zip
insites-cli modules list staging
insites-cli modules pull staging my_module
git init && git add app modules && git commit -m 'Code as it is on staging'

Run once for each of your own modules, then unzip the file it saves. To check the result, run . It should report nothing to upsert or delete.

Compare Two Environments

To see what a deploy would change, use a dry run. It compares your release with the site, file by file.

insites-cli deploy production --dry-run --verbose

To compare the code on two environments line by line, pull both and let Git compare them:

mkdir -p /tmp/a /tmp/b
insites-cli pull staging -p /tmp/a/app.zip
insites-cli pull production -p /tmp/b/app.zip
(cd /tmp/a && unzip -oq app.zip) && (cd /tmp/b && unzip -oq app.zip)
git diff --no-index /tmp/a/app /tmp/b/app

Roll Back a Deploy

A full deploy replaces the site's code with your release. So deploying the previous Git tag puts the previous code back.

git checkout v1.4.2
insites-cli deploy production --dry-run --verbose
insites-cli deploy production
git checkout -

Data is not rolled back, and neither are migrations. A migration that ran stays run. If the release you are leaving changed data, write a new migration that changes it back. If your site is connected to GitHub, CloudShell can also revert a commit for you.

Debugging

During development, you can watch your site in real time with . It streams server-side logs to your terminal, including Liquid errors, GraphQL responses, and background job output. Add to show only errors, or to get one JSON object per entry. Use the Liquid tag in your code to output custom debug information to this log stream.