Deployments
Sveltia CMS is a headless CMS, so it doesn’t involve any specific deployment process. The two required CMS files, index.html and config.yml, can be hosted on any web server or static hosting service. This enables the project to be deployed like any other website using any preferred hosting service or platform.
CI/CD Integration
In most cases, you may want to automatically deploy your website whenever content is saved in your Git repository via Sveltia CMS. This can be achieved by integrating with a CI/CD (Continuous Integration/Continuous Deployment) service that monitors your Git repository for changes and triggers a build and deployment process.
All the supported Git backends offer their own CI/CD solutions or can be easily integrated with popular third-party CI/CD services. Here are some examples:
- Building: GitHub Actions, GitLab CI/CD, Gitea Actions, Forgejo Actions, Cloudflare Pages, Netlify, Vercel, CircleCI, Travis CI, Jenkins, etc.
- Hosting: GitHub Pages, GitLab Pages, Cloudflare Pages, Netlify, Vercel, Amazon EC2, Firebase Hosting, DigitalOcean Droplets, etc.
Your choice of CI/CD service may depend on factors such as ease of use, pricing, performance and integration with your existing workflow. Some services only host completely static sites, while others can handle dynamic applications as well. Refer to the documentation of your chosen CI/CD and hosting providers for specific instructions on how to set up the deployment process.
Deploy Previews
A connected CI/CD provider does more than publish your site: it reports each build back to your Git repository, and Sveltia CMS reads those reports. Editors get a link straight to the page they just worked on and can see whether the build carrying their change has finished.
This works in both production workflows. With Editorial Workflow, an unpublished entry links to the preview built for its pull request, so a draft can be reviewed before it goes live. With Simple Workflow, the entry links to the live site and the CMS reports whether the latest build is done.
Nothing needs to be turned on. Set a preview_path on the collections you want entry links for. Without it, only the root of a deploy preview is linked.
See Deploy Previews for which providers are recognized and how the links behave while a build is running.
Disabling Automatic Deployments
You may already have a CI/CD tool set up on your Git repository to automatically deploy changes to production. Sometimes you make so many content changes that you quickly reach your CI/CD provider’s (free) build limits. Or you may just not want a build triggered for every small change.
With Sveltia CMS, you can disable automatic deployments by default and manually trigger deployments at your convenience. This is done by adding the [skip ci] prefix to commit messages. This convention is supported by GitHub Actions, GitLab CI/CD, CircleCI, Travis CI, Netlify, Cloudflare Pages and others.
No build, no preview
A skipped commit produces no build, so there’s nothing for Deploy Previews to report and the entry keeps its plain live-site link. This applies to Editorial Workflow saves too, where the prefix is added to the pull request’s commits. Deletion commits are never skipped.
Configuration
Here are the steps to use this feature:
Add the
skip_ciproperty to yourbackendconfiguration with a value oftrue:yamlbackend: name: github repo: owner/repo branch: main skip_ci: truetoml[backend] name = "github" repo = "owner/repo" branch = "main" skip_ci = truejson{ "backend": { "name": "github", "repo": "owner/repo", "branch": "main", "skip_ci": true } }js{ backend: { name: "github", repo: "owner/repo", branch: "main", skip_ci: true, }, }Commit and deploy the change to the config file and reload the CMS.
Now, whenever an entry or asset is saved,
[skip ci]is automatically added to each commit message. However, deletions are always committed without the prefix, so that deleted data doesn’t unexpectedly stay on the site.To deploy a new or updated entry, along with any other unpublished entries and assets, click the arrow next to the Save button in the Content Editor, then select Save and Publish. This omits
[skip ci]and so triggers CI/CD.
If you set skip_ci to false, the behavior is reversed. CI/CD is triggered by default, and a Save without Publishing option adds [skip ci] to that one commit only.
Deprecation Notice
The automatic_deployments option has been deprecated in favor of the more intuitive skip_ci option. It will be removed in Sveltia CMS v1.0.0.
If you are upgrading from an older version, update your configuration:
automatic_deployments: falseis equivalent toskip_ci: true.automatic_deployments: trueis equivalent toskip_ci: false.
Unpublished vs. Drafts
Unpublished entries and assets are not drafts. Once committed to your repository, those changes can be deployed any time another commit is pushed without [skip ci], or when a manual deployment is triggered.
Manual Deployment Trigger
If the skip_ci property is defined, you can manually trigger a deployment by clicking the Publish Changes button on the application header. To use this feature:
GitHub Actions
Without any configuration, Publish Changes will trigger a repository_dispatch event with the sveltia-cms-publish event type. Update your build workflow to receive this event:
on:
push:
branches: [$default-branch]
repository_dispatch:
types: [sveltia-cms-publish]GitLab CI/CD
Without any configuration, Publish Changes will create a new pipeline on the configured branch with the signed-in user’s access token. A pipeline created this way runs even when the latest commit has the [skip ci] prefix, so there’s no deploy hook URL to set up.
The user needs the Developer role or higher on the project, and if the branch is protected, permission to push or merge to it.
The pipeline has api as its CI_PIPELINE_SOURCE. If your .gitlab-ci.yml only runs on push, GitLab refuses to create the pipeline and the CMS shows an error. Allow the api source as well:
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "api"Other CI/CD Providers
To use Publish Changes with a CI/CD provider other than GitHub Actions or GitLab CI/CD, you need to set up a webhook in your CI/CD provider that triggers a build when called. Check your provider’s documentation for instructions on how to create a deploy hook URL. Here are some examples:
Then, configure Sveltia CMS to use this URL:
- Select Settings under the Account button in the top right corner of the CMS.
- Select the Developer tab.
- Enter the deploy hook URL for your provider.
- Configure the CSP if necessary.
Why Deploy Hook URL Is Stored in User Settings
Deploy hook URLs are confidential, so they can’t be stored in the CMS configuration file, which is usually readable on a public website. Sveltia CMS works entirely in the frontend, so it has no other secure place to store such credentials. That’s why they are managed in the user settings, which are stored securely in the browser’s local storage.
When the user signs out, the deploy hook URL and its authorization header are removed from the browser, along with the API keys for other integrations. They need to be entered again after signing back in.
In the future, we may provide a way to manage credentials for all users via an edge function called Sveltia CMS Additions.