GitHub Pages & Releases

Quick Summary

GitHub Pages hosts static websites (docs, portfolios, project sites) for free directly from your repository. Releases let you package and distribute versioned snapshots of your project with changelogs, binaries, and release notes.

---

GitHub Pages

Setup Methods

Deploy from Branch

1. Go to Settings → Pages
2. Under Source, select Deploy from a branch
3. Choose main branch and /docs folder (or root /)
4. Click Save

Your site will be live at https://username.github.io/repository/

Deploy via Actions

# .github/workflows/deploy-pages.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci && npm run build

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

      - id: deployment
        uses: actions/deploy-pages@v4

Custom Domain

1. Add a CNAME file to your repository root:

   docs.example.com

2. Configure DNS: Add a CNAME record pointing to username.github.io
3. In Settings → Pages, enter your custom domain
4. Enable Enforce HTTPS

---

Releases

Creating a Release

Via GitHub Web

1. Go to Releases (right sidebar) → Draft a new release
2. Choose or create a tag (e.g., v2.0.0)
3. Write release title and notes
4. Attach binary files if needed
5. Click Publish release

Via Git CLI

# Create an annotated tag
git tag -a v2.0.0 -m "Release version 2.0.0"

# Push the tag to GitHub
git push origin v2.0.0

# Push all tags
git push --tags

Via GitHub CLI

# Create a release with auto-generated notes
gh release create v2.0.0 --generate-notes

# Create with custom notes
gh release create v2.0.0 --title "Version 2.0.0" --notes "Major update with new features"

# Create and attach files
gh release create v2.0.0 ./dist/app.zip ./dist/app.tar.gz

Semantic Versioning

MAJOR.MINOR.PATCH

v2.1.3
│ │ └── Patch: bug fixes (backward compatible)
│ └──── Minor: new features (backward compatible)
└────── Major: breaking changes

Change Type	Version Bump	Example
Bug fix	v1.0.0 → v1.0.1	Fix login crash
New feature (backward compatible)	v1.0.1 → v1.1.0	Add dark mode
Breaking change	v1.1.0 → v2.0.0	Remove deprecated API

Auto-Generated Release Notes

GitHub can automatically create release notes from merged PRs:

1. Create .github/release.yml:

changelog:
  categories:
    - title: "🚀 Features"
      labels: ["feat", "feature"]
    - title: "🐛 Bug Fixes"
      labels: ["fix", "bug"]
    - title: "📚 Documentation"
      labels: ["docs"]
    - title: "🔧 Maintenance"
      labels: ["chore", "refactor"]

2. When creating a release, click Generate release notes — PRs are automatically grouped by label.

---

Best Practices

• Use GitHub Actions for Pages deployment — more control than branch-based
• Tag every release with semantic versioning
• Write clear release notes — users and collaborators depend on them
• Automate release notes with PR labels and .github/release.yml
• Pin dependencies in release builds — ensure reproducible builds

What's Next

1. Security Features — Dependabot, code scanning, and secret scanning
2. Advanced Git — Rewrite history and automate with hooks