Pantheon and GitHub Actions: and all the Goodies in 2022

Building and deploying to Pantheon using GitHub Actions

At Bluecadet, we have been using Pantheon’s Build tools and Circle CI to deploy projects for a few years now. We have also customized the CircleCi jobs for our own agency needs. It has made the development process more robust by giving us tools to manage different environments as well as run tasks like accessibility checks and visual regressions. But a CI Process also posed a maintenance burden on our clients, some of whom do not have internal DevOps or development staff. With an eye toward making the handoff to our clients easier and more accessible, we started investigating Github Actions as a potential continuous integration alternative.

First, I want to give a shout out to Tyler Fahey and his article from 2020. This got me started and I think there are some significant updates I wanted to address, hence this article.

Why do we use CI? We have two main needs for CI. First, running Composer so we do not have to commit module and library dependencies to our project repository. Second, we use Node (and Gulp) to compile all our custom front end CSS and JS, and checking in these assets can cause merge conflicts. After that, depending on the project we run some tests (mainly visual regression — but that is a different article). Using Pantheon’s Build Tools to setup a new site, Composer actions are built into the setup and adding in the Node processing was easy to add into the CircleCi config.

Another thing that is worth pointing out, as an organization, we like to have our canonical repo live on our GitHub account, to take advantage of Github Issues and ultimately as a backup for the codebase. When we first started using Pantheon, we would actually push our changes to both our GitHub repo and the Pantheon repo. We typically have small teams so this was not a huge burden, but it still required developers to remember to push up to both remotes. Having a CI process that triggered on a push to Github and then pushed to Pantheon on its own made our internal dev/deploy process more consistent.

In recent years though, Pantheon has been adding some cool new features that we wanted to learn about and take advantage of.

1. Integrated Composer (basically, able to run composer install on Pantheon platform). Very cool! We now do not need CI for this process. But we still need it for our Node and Gulp processing.
2. Upstreams, which really is not new, but allows for one-click updates in the Pantheon dashboard. As a developer, one-click updates scare me, but after handing off a project to a client, it is pretty handy.
3. Autopilot, which seems like a great feature, runs automatic updates, and visual regression! To be honest, I do not know much about this feature, but want to continue to look into it. AGAIN, With an eye toward making the handoff to our clients easier, this seems like a great feature when we hand off a project to our clients.

With the existing Build Tools setup, we do not have access to those features (as far as I understand it, maybe there are some workarounds?). We also need to update our CI process. We did a lot of customization, and the result is hard to maintain. I had too much fun learning and playing with all the possibilities CI provided. At this point in time, it is allowing us to take a good look at GitHub Actions and so far seems to be a great solution that fits our needs.

Step 1: Starting

The first step to get started now would be to read Tyler Fahey’s article. He really does a great job of explaining the process in the article, and anything here would just be a copy/paste of that article anyways.

Step 2: Adding in Integrated Composer

OK, now that you have read that, the next step for me would be how to add in Integrated Composer. Most of this happens on the Pantheon side when we create the project. Through Pantheon’s UI, create a new Drupal 9 site with Integrated Composer. You can do WordPress too, there are just a few more steps. Read the Docs on Integrated Composer. Once you push code, Pantheon will do the rest.

So here is my Github Workflow (This should look extremely familiar if you read Tyler’s article):

Step 2B: Deploy to any branch

We can update this slightly so we can push to any branch. Just be careful how you name your branches due to Pantheon’s environment naming conventions.

We changed:

• the ‘on’ trigger to build on any branch
• the git push command to push to the correct branch

Step 3: Adding in Node and Gulp

Next, we want to add in Node and the relevant node commands. Our typical process uses Gulp, so you will see commands related to that, but you should be able to substitute it with whatever you need.

Let us walk through what we added. First, I borrowed a lot from Pantheon’s build tools to help me understand what needed to happen and how to do it. They have some nice helpful functions and I imagined I could accomplish everything we needed to without it, but it seemed easier just to add it in here for the moment. Lines 16–23 we are installing Terminus and the build tools plugin. What I ended up really needing was this function to cut the .gitignore file. In our “local” repo, we ignore the production assets that Gulp builds (css, js, etc). But we do not want to ignore those files on Pantheon, because otherwise styles and javascript will be missing. Lines 25–27 are running the command to modify the .gitignore file.

If you are familiar with Pantheon Build Tools process, you will know that there is always this one “Build Assets” commit that is on Pantheon’s repo which is usually huge and contains everything built from Composer as well as Gulp. We basically are replicating that, but now we only need the production assets from our Gulp build.

Next (lines 29–46), we are adding in all of our Node stuff. We are going to install Node first. Restore any cache for node packages to help speed up the action. Then, finally run the needed commands to build out our Front End assets.

Now that we have all these new files, we need to get them to Pantheon. Previously, we just pushed to Pantheon, but now we need to create that “Build Assets” commit and then push. The deploy step is updated to handle this.

Congrats!! We are now using Pantheon’s upstream, and Integrated Composer, GitHub Actions AND Node!

Read on if you are interested in another use case we ran into…

BONUS CONTENT: Ignoring files only on the Pantheon Repo

An issue we ran into (and a number of users from what I am told from Pantheon) is if Composer changes files that are not really supposed to be modified from a Composer change, it causes the process to fail on Pantheon. So no CMS! Not good. Also, this was a hard error to understand, but if you think everything is working but your changes are not updating on your build, check the “View log” for that push in your Pantheon dashboard. At the end there will be some errors.

Our use case is that we are using a handy little plugin, joachim-n/composer-manifest, which creates a small yaml file, composer-manifest.yml, indicating exact versions of each composer package installed. This keeps a nice log in your git history for when a package updates, but you did not explicitly change your composer.json file. You could read the lock file, but that is just insane!

In order to bypass this problem I basically need exactly the opposite of what the Build Tools does in cutting the .gitignore file. And after a little trial and error, I also realized we need to remove those files from being tracked in the repo! So I created a new ignore file, .gitignore-panth. As a standalone file, this has no effect on anything as far as I can tell. If it messes with git in any way, we can rename it. We can then use this file to define files or directories we want to ignore on Pantheon, just like any other .gitignore file. Here is the deploy step now with the 2 new lines we need.

- name: deployer
      env:
        pantheon_repo: '${{ secrets.PANTHEON_REPO }}'
      run: |
        BASE_BRANCH=${GITHUB_REF##*/}
        git remote add pantheon $pantheon_repo
        git config user.mail "bc-bot@bluecadet.com"
        git config user.name "Bluecadet Bot"
        git rm `cat .gitignore-panth | sed 's/^\///g'`
        cat .gitignore-panth >> .gitignore
        git add .
        git commit -q -m 'Build assets for dev.'
        git push --force pantheon HEAD:refs/heads/$BASE_BRANCH

First, we delete the files with the git rm command, then we simply add the contents of the .gitignore-panth to the real .gitignore file with the cat command.