Deploy Middleman with GitHub Actions
Tags: middleman, github, actions, deploy
Published: 2020-08-07 21:44:03

This is the final step to get the app live using [Github Pages](https://pages.github.com/)!

Thanks for sticking with me until the end of this series :) .

Read about how to set up Middleman, either locally or inside a Docker container, in the previous blog posts.

Setting up [GitHub Actions](https://github.com/features/actions) is really easy and it just requires you to create a path named `./github/workflows` in your repository root directory, inside which all workflow configuration files will be. 

I’ll show you how to achieve making continuous deployments of a dockerized Middleman app to GitHub Pages in just a few steps, but know that you can also configure it to make deployments to AWS or any other server you’d prefer. 

You can find all sorts of predefined actions in [GitHub’s marketplace](https://github.com/marketplace?type=actions).

In this case, because we are using GitHub Pages, make sure to push your repository to GitHub, make it public, and create a [`‘gh-pages’` branch](https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site#creating-a-repository-for-your-site).

Open your repository’s settings and you should see GitHub Pages was automatically enabled after the new gh-pages branch was created and pushed:

![Screenshot of a GitHub's repository configuration page](https://raw.githubusercontent.com/pmallol/middleman-webpack-demo/master/screenshots/screenshot-3.jpg)

Awesome! Thanks GitHub.

Now create a `deploy.yaml` file inside the `.github/workflows` directory with the following content: 

{% gist https://gist.github.com/pmallol/529fe67cb9d18830503d5709b2735201 %}

Commit this change inside the `‘master’` branch and push it to your repository. This will generate the `GITHUB_TOKEN` needed by the [GitHub Pages action](https://github.com/marketplace/actions/github-pages-action). 

![Screenshot of a GitHub's repository Action tab log page](https://raw.githubusercontent.com/pmallol/middleman-webpack-demo/master/screenshots/screenshot-4.jpg)

_This first workflow run will probably fail, that’s ok!_

You can monitor workflows navigating to the [‘Actions’ tab](https://github.com/pmallol/middleman-webpack-demo/actions) of your GitHub repository.

Now it’s the perfect time to modify [Middleman’s build configuration](https://middlemanapp.com/advanced/configuration/#environment-specific-settings). When Middleman is built with the command `$ bundle exec middleman build`, a new build folder is created. The asset files previously located inside the `.tmp/dist` folder will be bundled and moved inside the `./build` folder in the process.

Also, because of the way [relative links are generated in GitHub Pages](https://github.blog/2016-12-05-relative-links-for-github-pages/), we will need to set a `http_prefix` with the name of the repository so that it is added as a prefix to all links in the application.

Let’s edit the `config.rb` file and add a build environment configuration to ensure relative links and paths for `.css` and `.js` files are set properly:

{% gist https://gist.github.com/pmallol/9c9d47b23d01b83b49cfa1b2397428c8 %}

Commit and then push the changes to `master`. This time, the GitHub Actions workflow shouldn’t take as long as the first one because we’ve configured the gems and packages to be [cached](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows).

If your workflow ran successfully, open up your GitHub Page and see what it looks like. It will most likely be located at `https://your-gh-username.github.io/your-gh-repo`.

Check out the demo: [https://pmallol.github.io/middleman-webpack-demo/](https://pmallol.github.io/middleman-webpack-demo/). 

If you inspect the site, you should see assets are properly linked, like so:

```
<head>
   ...
   <link href="/middleman-webpack-demo/style.css" rel="stylesheet">
   <script src="/middleman-webpack-demo/site.min.js"></script>
</head>
```

![Screenshot of Middleman app in GitHub Pages with dev tools open inspecting the head tag of the HTML](https://raw.githubusercontent.com/pmallol/middleman-webpack-demo/master/screenshots/screenshot-5.jpg)

## Final touches

Alright, so we now have a really nice app with continuous deployment.

What’s missing, I believe, is adding a bit of content. As a final step we’re going to add an About page and link it from the Home page.

When using Middleman, all new content should be located inside the `/source` folder. You can read more about how Middleman manages its directory structure in their [docs](https://middlemanapp.com/basics/directory-structure/). 

So, create an `/about` folder inside `./source` and inside this `/about` folder, create a file named `index.html.erb`. This will be our new About page.

Add some kind of content and a link to the Home page:

{% gist https://gist.github.com/pmallol/a5ef8b5cac2700d99b72d21d5b46ddcd %}

And next, as the last step, let’s make this About page accessible from the Home page. Open up the Home page file located inside the `./source` directory also named `index.html.erb`, and add a link to the About page at the very bottom:

{% gist https://gist.github.com/pmallol/176c419e4adfed5a0355863e16a18d75 %}
 
And, that’s it!

We should see the new About page working properly either locally and on the GitHub Page.

![Screenshot of an About page of a Middleman app in GitHub Pages](https://raw.githubusercontent.com/pmallol/middleman-webpack-demo/master/screenshots/screenshot-6.jpg)

Hope these series were useful and please don’t hesitate to drop me a line if you have any questions or comments.

### Special thanks

Huge thanks to [@fnbellomo](https://github.com/fnbellomo) who helped me figure out a lot of things throughout the process of making this demo!