Development Workflow

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 instances 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 instance in real time using the CLI.
• Staging instance - A testing environment that mirrors production. Use it for QA, client review, or user acceptance testing (UAT). Emails on staging instances are suppressed, so you can safely test workflows without emailing end users. To receive them yourself, add recipients in your Instance Admin under Settings > Instance Configuration > Email Notifications.
• Production instance - The live environment that your users interact with. Only deploy code here after it has been tested on staging.

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 instance. Run to push changes to your instance 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 instance 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 instance. Run first to see what will change. A full deploy removes files that are not in your release.

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 instance 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 instance. Your AI selects the instance 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 an instance 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 instance.
• 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 Instance into Git

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

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 instance, file by file.

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

Roll Back a Deploy

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

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 instance is connected to GitHub, CloudShell can also revert a commit for you.

Debugging

During development, you can watch your instance 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.