Implementing a Robust Deployment Workflow with GitHub Actions

Introduction

This document outlines the steps involved in setting up a static website built with 11ty (Eleventy) and deployed using GitHub Pages and GitHub Actions. It aims to provide a clear and concise guide for developers who want to automate their deployment process and host their 11ty sites on GitHub Pages.

Prerequisites

Before proceeding, ensure you have the following:

• A GitHub account
• Node.js and npm installed
• Git installed and configured
• VS Code (or your preferred code editor)
• GitHub Desktop (optional, but recommended)
• Basic understanding of HTML, CSS, and JavaScript
• Basic understanding of 11ty

Steps

Project Setup (11ty)

If you haven't already, set up your 11ty project with the following file structure:

prespedro-portfolio/
├── src/          (11ty source files)
│   └── index.njk
├── .eleventy.js   (11ty configuration)
├── .gitignore
├── CNAME           (custom domain file)
├── package-lock.json
└── package.json

Configure your .eleventy.js file to use src as the input directory and _site as the output directory:

module.exports = function (eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "_site",
    },
  };
};

Create a .gitignore file to exclude node_modules and _site from version control:

node_modules
_site

Create a CNAME file in the root directory with your custom domain (e.g., presidentpedro.com).

Install your project dependencies using npm install.

Branching Strategy

Establish a branching strategy with three key branches:

• development Branch: Used for local development. Contains all source files, configuration files, and node_modules (excluded from version control).
• src Branch: Mirrors the development branch. Used by GitHub Actions for building the site.
• build Branch: Used by GitHub Pages to serve the static site. Initially, only contains the CNAME file.

GitHub Actions Workflow

Automate your deployment process using GitHub Actions:

1. Create a .github/workflows directory in the src branch.
2. Create a deploy.yml file in the workflows directory with the following content:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - src

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build 11ty site
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site
          publish_branch: build
          cname: presidentpedro.com

GitHub Pages Setup

Configure GitHub Pages to serve your site:

• Go to your repository's "Settings" tab.
• Click on "Pages" in the left sidebar.
• Under "Build and deployment," set "Branch" to "build" and the folder to "/(root)".
• Enter your custom domain in the "Custom domain" field.
• Configure your DNS settings with A records pointing to GitHub Pages IP addresses.

Repository Settings

Ensure that GitHub Actions has the necessary permissions:

• Go to your repository's "Settings" tab.
• Click on "Actions" > "General" in the left sidebar.
• Ensure that "Read and write permissions" is selected in the "Workflow permissions" section.

Deployment Process

Deploy your site by following these steps:

• Make changes to your 11ty site in the src branch.
• Commit and push your changes to the src branch.
• GitHub Actions will automatically build the site and deploy it to the build branch.
• GitHub Pages will serve the site from the build branch.

Troubleshooting

Address common issues:

• Permission Errors: Ensure that "Read and write permissions" are enabled for GitHub Actions in your repository settings.
• Build Errors: Check the GitHub Actions workflow logs for error messages.
• Deployment Errors: Verify your GitHub Pages settings and DNS configuration.
• Node Modules: Remember to run npm install on both the development and src branches.

Benefits

This workflow provides several benefits:

• Automated deployment process
• Consistent and reliable deployments
• Improved workflow efficiency
• Easy collaboration with others

This document should serve as a valuable resource for you and anyone else who wants to set up GitHub Pages with GitHub Actions and 11ty. Feel free to add more details or customize it to fit your specific needs.

Sources

The following resources were helpful in developing this workflow:

• https://github.com/AlwaysOnTV/AlwaysOnTV
• https://juejin.cn/post/7317152128104955940
• https://medium.com/@nathvichea/github-action-to-deploy-docusaurus-8c297eaf1514
• https://github.com/KakaoCup/Kakao

Integrating GitHub Desktop (Optional)

GitHub Desktop can simplify Git operations:

Install GitHub Desktop

If you don't have it already, download and install GitHub Desktop from desktop.github.com.

Add Your Repository

Open GitHub Desktop and add your repository.

Branch Management

Use GitHub Desktop to easily switch between branches, create new branches, view history, and manage merges.

Using GitHub Desktop with the Workflow

Perform the following steps visually:

• Switching Branches: Easily switch between the src and build branches.
• Committing Changes: Stage and commit changes with clear descriptions.
• Pushing Changes: Push your commits to the remote repository.
• Viewing History: Inspect your commit history and branch structure.
• Resolving Conflicts: Handle merge conflicts if they arise.

Workflow with VS Code

Combine VS Code and GitHub Desktop:

• VS Code for Editing: Use VS Code to edit your 11ty files.
• GitHub Desktop for Git Operations: Use GitHub Desktop to manage Git.
• Terminal for Server and Commands: Use the VS Code terminal for npx @11ty/eleventy --serve and npm run build.

Revised Workflow Steps (with GitHub Desktop)

Here's the workflow using GitHub Desktop:

Repository Restructuring (using GitHub Desktop):

• Create src branch: In GitHub Desktop, create a new branch named src.
• Move files: In VS Code, move all source files into the src folder and move `.gitignore`, `CNAME`, `package.json`, `package-lock.json`, and `.eleventy.js` back to the root.
• Update .eleventy.js: Update the input directory to "src".
• Create build branch: In GitHub Desktop, create a build branch. Delete all files and copy the CNAME file into the build branch.
• Commit and push: In GitHub Desktop, commit and push changes to the src branch.

GitHub Actions Workflow (using VS Code and GitHub Desktop):

• Create .github/workflows/deploy.yml: In VS Code, create the deploy.yml file.
• Commit and push: In GitHub Desktop, commit and push the deploy.yml file to the src branch.

Monitor GitHub Actions:

• Go to your GitHub repository's "Actions" tab to monitor progress.

Benefits of Using GitHub Desktop:

• Visual Interface: Makes Git operations intuitive.
• Simplified Workflow: Reduces reliance on the command line.
• Error Prevention: Helps prevent Git mistakes.
• Improved Collaboration: Facilitates collaboration.

By using GitHub Desktop, you can focus on code in VS Code while GitHub Desktop handles Git, streamlining your workflow.