Git Deploys

Using git and continuous deployment is our recommended way to deploy to our serverless platform. It gives you the most seamless and consistent experience. Git deploys work with GitHub, GitLab, and Bitbucket - you can connect your account directly from the Webslice Console for a streamlined setup, or configure deploy keys and webhooks manually for self-hosted providers.

Git deploys support two deployment strategies: versioned (default) which is atomic and creates a new full copy for each deploy, or live which uses incremental hash-based syncing. See Deploy Strategies for details on how each strategy handles file persistence.

Connecting Your Repository

The fastest way to connect a repository is with a git connection. This links your GitHub, GitLab, or Bitbucket account to your Webslice team so you can select repositories and branches directly from the console - no deploy keys or webhooks to configure manually.

Git Connections

1. Navigate to your website’s Deploys or Settings page in the Webslice Console.
2. Choose your git provider (GitHub, GitLab, or Bitbucket) and follow the prompts to connect your account. For GitHub this installs the Webslice GitHub App; for GitLab and Bitbucket this authorizes via OAuth.
3. Once connected, select a repository from the list and pick your branch or tag - webhooks and access are configured automatically.

A git connection is created at the team level, so once a provider is connected, any team member can link repositories from that provider to their websites without reconnecting.

Manual Setup (Advanced)

If you use a self-hosted git provider, or prefer to manage access yourself, you can connect a repository manually using SSH deploy keys and webhooks. Webslice supports webhook events from GitHub, GitLab, and Bitbucket for manual connections.

1. You will need the address of the repository, something like git@example.com:user/project.git.
2. You will also need access to configure Deploy Keys and Webhooks on that repository. This usually requires write or admin access.
3. Follow the instructions in the connection form in the Webslice Console to add the deploy key and webhook to your repository.

Deploy Keys & Webhooks

Adding a deploy key and webhook is safe, and you can control how much access you give to Webslice. We would recommend read-only access in most situations.

Your git provider should have instructions on how to add these, but they are usually found under Repository Settings > Deploy Keys and Repository Settings > Webhooks.

Deploy Triggers

Webslice can either watch a specific branch, or pattern match tags. This is helpful for you to control when a deploy is triggered. This setting can be changed at any time.

Deploy by Branch

Configure deployments to trigger on commits to a specific branch such as main means all commits pushed to the main branch will create a new deployment.

Deploy by Tag

Configure deployments to trigger only on Git tags, for example v*, will mean only tags matching the pattern (e.g., v1.0.0, v2.1.3) will create deployments.

Deploy Modes

Deploys can be triggered automatically or manually based on your choice.

Automatically Deploy

A push to your git repository on the watched branch or tag creates a new deploy and automatically pushes the update live to your website. This option is powerful and easy to use but requires good testing and processes.

Use this when:

• Deploying from a production branch with tested code
• You want fast updates to your live site
• Your team follows strict merge/review processes

Add to List for Manual Deployment

A push to your git repository on the watched branch or tag creates a new deploy but waits for you to manually trigger the deployment when ready from the Webslice Console.

Use this when:

• You want to review or test the build before going live
• Coordinating deployments with other changes
• Deploying during specific maintenance windows

Deploy Strategies

Git deploys support two strategies that determine how your code is deployed and stored. This setting can be changed at any time from the website settings in the Webslice Console.

Versioned (Default)

Versioned deploys are atomic. Each deployment creates a new, complete copy of your application in a versioned directory (e.g., /mnt/data/website/Deploy-abc123). A live symlink points to the currently active version.

Characteristics:

• Atomic: full copy of your application created each deploy
• Previous versions retained for instant rollback
• Higher storage usage (one full copy per deploy)
• Any modifications made outside of git will not persist between deployments
• Use persistent storage for files that need to be retained

Use this when:

• You need instant rollback capability
• Storage usage is not a concern
• You want complete isolation between deployments

Live

Uses a single persistent deploy directory with incremental syncing. Instead of creating full copies, only files that have changed since your last build are updated. Files modified outside of your build (e.g. via SFTP or a CMS admin panel) are left untouched unless they also changed in the build output. See How Live Deploys Work for a detailed breakdown.

Characteristics:

• Single deploy directory that persists between deploys
• Only changed files are synced (faster deploys for large codebases)
• Lower storage usage (no version history)
• Files not tracked by git will persist between deployments
• Files modified on the live site are preserved unless they also changed in the build
• File permissions are tracked and updated alongside content
• Rollback requires a new deployment from a previous commit

Use this when:

• You have a large codebase with frequent, small changes
• Storage efficiency is important
• You want runtime-generated files to persist without using shared storage
• You use SFTP or a CMS to make occasional edits on the live site
• You don’t need instant rollback to previous versions

Switching Strategies

When switching from versioned to live strategy, a new deploy directory is created and the live symlink is updated to point to it. When switching back to versioned, new versioned directories will be created for subsequent deploys. This allows zero-downtime transitions between strategies.

How Live Deploys Work

The live deploy strategy compares the output of each build to the previous one and only applies the differences to your live site.

Incremental Syncing

When a live deploy runs, your deploy commit is checked out and your build script runs (if configured). Once the build is complete, the build output is compared to the previous build. Only files that have changed are copied to the live site — unchanged files are left as-is. File permissions are also tracked, so permission changes are applied without needing to re-upload the file content.

This comparison also handles new and deleted files:

• New files — Files that appear in the current build but not the previous one are added to the live site.
• Deleted files — Files that were in the previous build but are no longer present are removed from the live site.

Preserving Live Site Changes

A key benefit of the live strategy is that it respects changes made directly on the live site. If someone modifies a file via SFTP or a CMS admin panel, and that file has not changed in the build output, the live version is left in place. Only files that have changed in your build are updated.

This means you can safely make small edits on the live site (such as content tweaks through a CMS) without worrying that the next deploy will overwrite them — as long as the same file hasn’t also changed in your repository.

Note

The comparison tracks files in the build output, not just files tracked by git. If your build process generates files (compiled assets, optimized images, etc.), those are included and subject to the same incremental syncing logic.

Deployment Logs

While there are no detailed logs for the deploy action itself, you can view the logs from your your build and release scripts at any time by clicking on either the Website Deployment or Website Release Phase entries under Activity when viewing your website.

These logs can be helpful for debugging failed deployments or verifying your build/release process.

Deployment Workflow

If you’re curious how deploys actually work on Webslice and the order things will happen in this is for you:

1. Commits are pushed to your git repository on branch main
2. The webhook is triggered to Webslice, letting us know there’s new commits
3. A new deploy is triggered by checking out the entire repository
4. If configured to, your build script runs to install dependencies and build your site
5. The deploy goes live, with your latest code and starts serving traffic
6. If configured to, your release script runs for post-deployment tasks