The Sacred Deployment

Deployment strategies, GitHub Pages and semantic versioning

What is deployment?

Deployment is the process that makes your application available to users. As long as your code stays in a Git repository, nobody can use it. Deployment takes that code and puts it online, on a server, on a website - where people can access it.

If CI (continuous integration) verifies that your code works correctly, CD (continuous deployment) ensures it reaches its destination.

Deployment environments

Before deploying directly to production, we use several environments that serve as safety nets. Think of these as successive rooms a scroll passes through before reaching the Great Library.

Development (dev)

This is your local environment. Where you write, test and experiment. Nothing you do here is visible to others.

# You work locally - this is the development environment
git add .
git commit -m "New feature"

Staging (pre-production)

An environment that mimics production but isn't public. It's the preparation outpost - where you verify everything works under real conditions before the big day.

• Same configuration as production
• Test data (no real user data)
• Accessible only to the team

Production (live)

The real environment, the one users see and use. This is the Great Library. Every error here is visible to everyone.

Deployment strategies

Like a general choosing a battle formation, an engineer chooses a deployment strategy. Each has its advantages and risks.

1. Manual deployment

The simplest method: you connect to the server and copy the files yourself.

# Simplified example - copying files to a server
scp -r ./my-site/ user@server:/var/www/html/

• Advantage: Simple to understand
• Disadvantage: Prone to human error, not reproducible

2. Automatic deployment on merge

Every time a merge is done on the main branch, deployment launches automatically. This is the foundation of continuous deployment (CD).

# Deployment triggers when pushing to main
on:
  push:
    branches: [main]

• Advantage: Fast, reliable, reproducible
• Disadvantage: Requires a good test suite (otherwise you deploy bugs)

3. Blue-Green

You maintain two identical production environments: Blue (current) and Green (new). You deploy to Green, test, then switch traffic from Blue to Green.

                    +----------------+
Users -------------->|    Blue        |  (current version)
                    +----------------+
                    +----------------+
   (standby)        |    Green       |  (new version)
                    +----------------+

After validation:

                    +----------------+
   (standby)        |    Blue        |  (old version)
                    +----------------+
                    +----------------+
Users -------------->|    Green       |  (new version)
                    +----------------+

• Advantage: Instant rollback (switch back to Blue)
• Disadvantage: Doubled cost (two environments)

4. Canary

You deploy the new version to a small percentage of users first. If everything goes well, you gradually increase to 100%.

Canary deployment - progression:

  5% --> New version    (initial test)
 95% --> Old version

 25% --> New version    (going well)
 75% --> Old version

100% --> New version    (full deployment)

• Advantage: Minimal risk, early problem detection
• Disadvantage: More complex to set up

5. Rolling

You update servers one by one instead of all at once. During the update, some servers run the old version and others the new one.

Server 1: v2 +  (updated)
Server 2: v2 +  (updated)
Server 3: v1    (waiting)
Server 4: v1    (waiting)

• Advantage: No downtime
• Disadvantage: Two versions coexist temporarily

GitHub Pages - Deploy a site from Git

GitHub Pages is the simplest way to deploy a static website directly from a Git repository. It's free and built into GitHub.

How does it work?

GitHub takes the content of your repository (HTML, CSS, JavaScript) and publishes it at a URL like:

https://your-username.github.io/repo-name/

Enable GitHub Pages

Deploy from a branch

The simplest. Select the main branch and the root folder / (or /docs if you prefer to isolate the site files).

Deploy with GitHub Actions

More powerful. You write a workflow that builds the site and deploys it. This is what we'll do in the exercise.

Custom domain

You can even use your own domain name instead of github.io. You just need to configure a CNAME file in your repository and update your domain's DNS records. For now, this is not necessary.

Environment protection rules

Production environments are precious. GitHub lets you define protection rules to prevent accidental deployments.

Configure a protected environment

In the Settings of your repository, section Environments:

• Required reviewers: one or more team members must approve the deployment
• Wait timer: mandatory delay before deployment (e.g.: 5 minutes)
• Deployment branches: only certain branches can trigger deployment

Use an environment in a workflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production    # <-- protected environment
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: echo "Deploying to production..."

When the workflow reaches this job, it waits for approval before continuing (if reviewers are required).

Rollback - Going back

Sometimes, despite all precautions, a deployment introduces a bug. You need to be able to return to the previous version quickly. That's a rollback.

Strategy 1 - Revert commit

Create a new commit that undoes the changes of the problematic commit:

# Identify the problematic commit
git log --oneline

# Create a commit that undoes its changes
git revert abc1234

# Push the revert - the pipeline redeploys automatically
git push

The advantage: the history stays clean and you can clearly see that a rollback happened.

Strategy 2 - Redeploy a previous version

If you use version tags, you can simply redeploy the previous tag:

# Go back to tag v1.0.0
git checkout v1.0.0

# Or in a workflow, trigger deployment of a specific tag

Strategy 3 - Blue-Green rollback

With the Blue-Green strategy, rollback is instant: just switch traffic back to the old environment.

Complete deployment workflow

Here is an example GitHub Actions workflow that deploys a static site to GitHub Pages when pushing to main:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Retrieve the code
        uses: actions/checkout@v4

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

Workflow anatomy

Semantic versioning and tags for releases

When you deploy, it is essential to number your versions to know exactly what is in production.

Semantic versioning (SemVer)

The format is vMAJOR.MINOR.PATCH:

v1.0.0
| | |
| | +-- PATCH: bug fix (backward compatible)
| +---- MINOR: new feature (backward compatible)
+------ MAJOR: incompatible change (breaking change)

Create a version tag

# Lightweight tag
git tag v1.0.0

# Annotated tag (recommended for releases)
git tag -a v1.0.0 -m "First stable version"

# Push tags to GitHub
git push --tags

Create a release on GitHub

Releases are useful for users: they offer a clear download point and a changelog.

Hands-on exercise - Prepare the sacred deployment

Step 1 - Create the repository

mkdir sacred-deployment
cd sacred-deployment
git init -b main

Step 2 - Create the static site

Create an index.html file:

cat > index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>The Kingdom's Chronicles</title>
  <style>
    body { font-family: Georgia, serif; max-width: 800px; margin: 40px auto; padding: 0 20px; }
    h1 { color: #2c3e50; }
    .version { color: #7f8c8d; font-size: 0.9em; }
  </style>
</head>
<body>
  <h1>The Kingdom's Chronicles</h1>
  <p>Welcome to the Great Library.</p>
  <p class="version">Version 1.0.0</p>
</body>
</html>
EOF

git add index.html
git commit -m "Create the site homepage"

Step 3 - Write the deployment workflow

Create the folder structure for GitHub Actions:

mkdir -p .github/workflows

Create the workflow file:

cat > .github/workflows/deploy.yml << 'EOF'
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Retrieve the code
        uses: actions/checkout@v4

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4
EOF

git add .github/workflows/deploy.yml
git commit -m "Add the GitHub Pages deployment workflow"

Step 4 - Tag the first version

git tag -a v1.0.0 -m "First stable version - initial deployment"

Verify the tag exists:

git tag

You should see v1.0.0 in the list.

Step 5 - Run the verification

bash verifier.sh

.\verifier.ps1

Command summary

Concept summary