Integrate with GitHub Actions

Declared a .github/workflows/git-read.yml file to configure steps necessary to leverage GitHub actions.

The desired outcome is to publish a git-read-generated website to that project’s gh-pages branch.

To achieve this, execute the following steps upon a git push origin/main:

clone the host project’s entire source code history with fetch-depth: 0 to
install Ruby into the Action’s container
install NodeNJS into the Action’s container
clone and install the git-read project into the container
execute bin/git-read to generate a website from the host project’s Git History
deploy the output to the host project’s gh-pages branch

In support of deploying to a GitHub pages, we’ll also need to add support for nesting the output under a subdirectory. Since the output HTML has a potential to be served under a path (for example, https://seanpdoyle.github.io/git-read), read from the PATH_PREFIX environment variable, then prefix all sitemap URLs with that prefix.

Installation Script

Introduce the script/install file to execute the necessary commands to configure the project to be executable. Mainly, install its RubyGems dependencies and its Yarn dependencies.

Test Suite

While the .github/workflows/git-read.yml file serves as an example of how to integrate git-read into a project’s GitHub Actions, the .github/workflows/ci.yml declares its own GitHub Action to run the project’s test suite, ensuring that the tool behaves as expected, and that future revisions won’t introduce regressions.

.github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..d8c3463
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,26 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "2.6.6"
+        bundler-cache: true
+    - uses: actions/setup-node@v2
+      with:
+        node-version: "12.x"
+
+    - run: |
+        git config --global user.email "ci@example.com"
+        git config --global user.name "GitHub Actions"
+
+        bundle install --jobs 4 --retry 3
+        yarn install
+
+    - run: bundle exec rake

.github/workflows/git-read.yml

diff --git a/.github/workflows/git-read.yml b/.github/workflows/git-read.yml
new file mode 100644
index 0000000..0aa27eb
--- /dev/null
+++ b/.github/workflows/git-read.yml
@@ -0,0 +1,36 @@
+name: git-read
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "2.6.6"
+        bundler-cache: true
+
+    - uses: actions/setup-node@v1
+      with:
+        node-version: "12.x"
+
+    - name: Build documentation from Git History
+      run: |
+        script/install
+        bin/git-read --git-dir ./ --build-dir ./build --path-prefix "/$(basename $GITHUB_REPOSITORY)"
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        personal_token: ${{ secrets.PERSONAL_TOKEN }}
+        commit_message: ${{ github.event.head_commit.message }}
+        publish_dir: ./build

Gemfile

diff --git a/Gemfile b/Gemfile
index 2d4c808..805a6cc 100644
--- a/Gemfile
+++ b/Gemfile
@@ -13,4 +13,5 @@ group :test do
   gem 'capybara', require: 'capybara/minitest'
   gem 'climate_control'
   gem 'minitest-around', require: 'minitest/around/unit'
+  gem 'rake'
 end

Gemfile.lock

diff --git a/Gemfile.lock b/Gemfile.lock
index 134f225..b899381 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -110,6 +110,7 @@ GEM
     rack (2.2.2)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
+    rake (13.0.3)
     rb-fsevent (0.10.3)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
@@ -155,9 +156,10 @@ DEPENDENCIES
   middleman-inline_svg
   middleman-syntax
   minitest-around
+  rake
   redcarpet
   tzinfo-data
   wdm (~> 0.1)
 
 BUNDLED WITH
-   2.2.3
+   2.2.6

bin/git-read

diff --git a/bin/git-read b/bin/git-read
index d1ed809..1b2afd4 100755
--- a/bin/git-read
+++ b/bin/git-read
@@ -5,6 +5,7 @@ set -e
 ARGS=( "$@" )
 
 VERBOSE="--no-verbose"
+PATH_PREFIX=""
 
 for i in "${!ARGS[@]}"; do
   case "${ARGS[i]}" in
@@ -22,18 +23,25 @@ for i in "${!ARGS[@]}"; do
       GIT_DIR="${ARGS[i+1]}"
       unset 'ARGS[i+1]'
       ;;
+    -p|--path-prefix)
+      PATH_PREFIX="${ARGS[i+1]}"
+      unset 'ARGS[i+1]'
+      ;;
     -v|--verbose)
       VERBOSE="--verbose"
       ;;
     -h|--help)
       cat <<-HELP
-usage: git read [--help] [-v|--verbose] [-g|--git-dir <path>]
+usage: git read [--help] [-v|--verbose] [-g|--git-dir <path>] [-p|--path-prefix <path>]
                 [-s|--server|--serve] [-o|--output-dir <path>]
 
 Generate HTML from your project's Git history
 
 OPTIONS
 
+      --path-prefix
+          specify the prefix to prepend to URLs. For example, the name of the GitHub Page's subdirectory the output will be served under
+
       --output-dir
           specify the directory where the site will be built
 
@@ -59,11 +67,12 @@ done
 build_site() {
   git_dir="${1}"
   output_dir="${2}"
-  target="${3}"
-  verbosity="${4}"
+  path_prefix="${3}"
+  target="${4}"
+  verbosity="${5}"
   tool_dir="$(dirname "${BASH_SOURCE[0]}")/../"
 
-  export GIT_DIR=$git_dir
+  export GIT_DIR=$git_dir PATH_PREFIX=$path_prefix
 
   mkdir -p $output_dir
   cd $tool_dir
@@ -79,5 +88,6 @@ build_site() {
 build_site \
   $(realpath ${GIT_DIR-./}) \
   $(realpath ${OUTPUT_DIR-./build/}) \
+  "${PATH_PREFIX}" \
   "${TARGET}" \
   "${VERBOSE}"

config.rb

diff --git a/config.rb b/config.rb
index 2d57184..7cbade4 100644
--- a/config.rb
+++ b/config.rb
@@ -7,6 +7,7 @@ include UrlHelpers
 # https://middlemanapp.com/advanced/configuration/#configuring-extensions
 
 config[:mode] = (ENV.fetch("MODE") { build? ? "build" : "server" }).to_sym
+config[:path_prefix] = ENV.fetch("PATH_PREFIX") { "" }
 
 activate :aria_current
 activate :external_pipeline,
@@ -159,3 +160,7 @@ end
 #   activate :minify_css
 #   activate :minify_javascript
 # end
+
+configure :build do
+  activate :relative_assets
+end

helpers/url_helpers.rb

diff --git a/helpers/url_helpers.rb b/helpers/url_helpers.rb
index 3db5e7b..8a8292f 100644
--- a/helpers/url_helpers.rb
+++ b/helpers/url_helpers.rb
@@ -1,17 +1,17 @@
 module UrlHelpers
   def commit_path(commit)
-    "/commits/#{commit.sha}/index.html"
+    "#{config[:path_prefix]}/commits/#{commit.sha}/index.html"
   end
 
   def tag_path(tag)
-    "/tags/#{tag.name}/index.html"
+    "#{config[:path_prefix]}/tags/#{tag.name}/index.html"
   end
 
   def root_path(root = nil)
     if root.respond_to? :name
       tag_path(root)
     else
-      "/index.html"
+      "#{config[:path_prefix]}/index.html"
     end
   end
 end

script/install

diff --git a/script/install b/script/install
new file mode 100755
index 0000000..754d413
--- /dev/null
+++ b/script/install
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+PROJECT_ROOT=$(dirname "${BASH_SOURCE[0]}")/../
+GEMFILE="${PROJECT_ROOT}/Gemfile"
+gem install bundler --conservative
+bundle check || bundle install \
+  --without "test" \
+  --jobs 4 \
+  --retry 3 \
+  --gemfile $GEMFILE
+
+yarn install

test/application_system_test_case.rb

diff --git a/test/application_system_test_case.rb b/test/application_system_test_case.rb
index a90ca46..b7e4e37 100644
--- a/test/application_system_test_case.rb
+++ b/test/application_system_test_case.rb
@@ -2,12 +2,14 @@ require "test_helper"
 
 require_relative "../helpers/url_helpers"
 require "git_helpers"
+require "middleman_helpers"
 
 class ApplicationSystemTestCase < ActiveSupport::TestCase
   include Capybara::DSL
   include Capybara::Minitest::Assertions
   include UrlHelpers
   include GitHelpers
+  include MiddlemanHelpers
 
   def around(&block)
     with_git_directory(&block)

test/middleman_helpers.rb

diff --git a/test/middleman_helpers.rb b/test/middleman_helpers.rb
new file mode 100644
index 0000000..526da7a
--- /dev/null
+++ b/test/middleman_helpers.rb
@@ -0,0 +1,11 @@
+require "middleman/rack"
+
+module MiddlemanHelpers
+  def application
+    @application ||= Middleman::Application.new
+  end
+
+  def config
+    application.config
+  end
+end