Pattern one: direct publish from a workflow

The simplest arrangement. A workflow triggered by a push to the main branch uploads the site directory to the host. There is no build step, no artefact and no intermediate environment.

This is the right pattern for a small brochure site maintained by one or two people where the content changes rarely and every change is reviewed before merge. Its weakness is that the deployed thing and the reviewed thing are only the same by convention: nothing verifies it.

Pattern two: build artefact, then deploy

One job produces an artefact; a separate job publishes it. The artefact is the unit of deployment, so what was tested is exactly what ships, and a rollback is a redeploy of an earlier artefact rather than a revert-and-rebuild.

The cost is a slightly longer pipeline and a storage retention policy to think about. The benefit is that "roll back" stops being a euphemism for "build the old commit and hope".

Build once, deploy the artefact

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate JSON configuration
        run: |
          for f in config/*.json content/**/*.json; do
            python -m json.tool "$f" > /dev/null
          done
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: .

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: site
          path: site
      # publish ./site to the host

Pattern three: preview environment per pull request

A temporary environment is created when a pull request opens and destroyed when it closes. Reviewers get a URL rather than a diff.

This is the pattern that changes team behaviour most. Non-technical stakeholders can review content and design without a local toolchain, which removes the single biggest bottleneck on a corporate website: waiting for someone to describe a change in words when they could simply have looked at it.

Note

Preview environments are public URLs unless you configure otherwise. If a pull request contains unannounced information — a product launch, a price change, a staff departure — treat the preview as published.

Pattern four: staging slot with promotion

A long-lived staging environment receives every merge to main; production is updated by an explicit promotion step, usually gated by an approval.

This suits organisations where publication is a governed act — regulated firms, public bodies, anywhere a communications or compliance team must sign off. It is the heaviest pattern, and it is frequently adopted by teams who do not need it, which produces a staging environment that nobody looks at and an approval that nobody reads.

Comparing the four

Pattern Best for Main cost Rollback
Direct publish Small sites, one or two maintainers No verified artefact Revert and rebuild
Build then deploy Most corporate sites Artefact retention Redeploy an artefact
Preview per PR Teams with non-technical reviewers Previews are public by default As per underlying pattern
Staging and promotion Governed publication Process weight, drift Promote a known-good build

How to choose

Ask what actually goes wrong on this site. If the answer is "someone publishes a typo", you need review, which means previews. If it is "we cannot tell what is live", you need artefacts. If it is "legal found out after publication", you need promotion. If nothing goes wrong, direct publish is not negligence, it is proportion.

Watch out

The most expensive mistake is adopting the heaviest pattern for a site that changes four times a year. Process that is not exercised decays, and a decayed process gives you the cost of governance with none of the assurance.

What we do by default

For a corporate website built on this framework we use pattern two with pattern three layered on top: build an artefact, deploy previews for pull requests, and publish the artefact on merge. It is enough structure to make review real, and little enough that a content change still reaches production the same morning.