Deploy with Hostsmith

Every kit site has the deploy workflow .github/workflows/hostsmith.yml. Once it's set up:

• a push to main builds the site and deploys it to the production site;
• a push to any other branch deploys it to the preview site, so the client can see a change before it goes live;
• the repository's deployments list links each deploy to its site.

What you need

• A Hostsmith plan with two sites, one for production and one for previews: Pro or above. On Free and Starter, which have one site, set up production only, and branch pushes only build.
• For the client's own domain: Pro or above.
• For the EU data partition: Agency or Premium.
• The organization's owner to create the API tokens.

See Pricing for the plans.

1. Create the two sites

1. In the Hostsmith dashboard, open Sites and click Add.
2. Pick the data partition, enter a subdomain, such as acme, and pick a domain. Under Files, add a placeholder page, such as an index.html that says "Coming soon": the workflow's first deploy replaces it. Click Add.
3. Add a second site for previews the same way, such as acme-preview.
4. In the sites list, open each site with Edit site. The card at the top shows its Site ID: copy it with the button beside it, and keep both ids for the next steps.

2. Name the production site

Set the production site's id in hostsmith.json, at the root of the repository, and commit it:

"site": { "id": "PRODUCTION-SITE-ID" }

3. Create two API tokens

Each target gets its own token, restricted to its site, so a branch can never deploy to production.

1. In the dashboard menu, open API Tokens and click New token.
2. Give it a name, such as acme production deploys.
3. Under permissions, pick Custom, and check sites:read and files:write.
4. Under sites, pick Only selected sites, and check the production site.
5. Pick an expiry, click Create token, and copy the token. It's shown once.
6. Create a second token the same way for the preview site.

API tokens explains the permissions and how to revoke a token.

4. Set up the repository

In the GitHub repository's Settings, under Environments:

1. Create the environment production. Add the secret HOSTSMITH_TOKEN with the production token. Under deployment branches, allow only main, so other branches can't use this token.
2. Create the environment preview. Add the secret HOSTSMITH_TOKEN with the preview token, and the variable HOSTSMITH_PREVIEW_SITE_ID with the preview site's id.

Private repositories on GitHub Free have no environment secrets. There, create one token restricted to both sites, add it as the repository secret HOSTSMITH_TOKEN, and add HOSTSMITH_PREVIEW_SITE_ID as a repository variable.

The workflow also reads these variables, in the repository or an environment:

5. Deploy

Push a branch:

git switch -c first-preview
git push -u origin first-preview

The workflow's Hostsmith run checks the settings first, and names any that are missing. Then it checks the styles, builds, and deploys to the preview site. Open the run's deployment link to see the site.

A push to main, such as merging the branch, deploys to the production site the same way. To deploy without a push, run the workflow from the repository's Actions tab and pick the target.

6. Move to the client's domain

1. Check the old site's URLs first, if the site replaces one: see Keep old URLs.
2. Add the domain to the production site, as Custom domains explains, and wait until it's active.
3. Set url in src/site.config.ts to the domain, such as https://www.example.com. The site's canonical links and sitemap use it.
4. Delete the variable SITE_NOINDEX, or set it to false, and push to main.
5. Check the live site against the old URLs:

   npm run check:urls -- --live https://www.example.com
   

The kit's README has the workflow's settings in one table.

Another host

A kit site builds to static files in dist/, and any static host can serve them: build with npm run build and deploy dist/ as that host documents. The deploy workflow is the only part of the site that names Hostsmith.