Grav Release Process

With the release of Grav 1.7, we have taken the opportunity to move from Travis to GitHub Actions for the creation of our release packages. Our original workflow included the packaging of Grav, the tests runner on each commit/PR and the regeneration of all the official Grav Skeletons - all within the same workflow.

This process was bearable at the beginning but over time Travis, which has served us extremely well over the years, has started imposing stricter waiting queues for free and ORG plans and on top of that, our Skeletons count has been growing.

To put it in perspective, performing a release for Grav was taking a good 8-10 minutes, after a 2-3 hours wait in the queue. Now imagine the unfortunate situation of having re-release right away...

Welcome, GitHub Actions

GitHub Actions, from GitHub, fully integrates with our repository and has simplified substantially the way workflows work and get maintained in general. It has clear documentation, is easy to understand, and is available for anyone to use. GitHub Actions has been used by many people for all kind of automations, from Pull Requests validity, to performing tests on commits, from automating issues responses, to notifications on chat services such as Slack/Discord.

The best part of all is that GitHub Actions allows developers to create their own Actions and then share them in the Marketplace so that anyone can use them!

Re-evaluating Grav's Continuous Integration

It was time for us to leave Travis behind and move over our workflow to GitHub Action. The first thing we did was to ensure we only focused the workflow with regard to Grav releases. This meant generating the 3 official packages available for download (Grav, Grav + Admin, Grav Update) and completely leave Skeletons out of the picture.

This didn't take long, and while perhaps not apparent to everyone, we have been generating our new packages with this new workflow with the first Grav 1.7 release. We also quickly added a separated workflow for the tests, which have been running ever since.

We now had split one workflow into two, with each one focused on their own tasks, and let me tell you this has given us a massive improvement in release timing! Releasing Grav now takes about 1.5 minutes, running tests on a matrix of 3 PHP versions (7.3, 7.4, 8.0) takes about 35 seconds. Impressive.

Now the only thing left to address were the Skeletons.

Skeletons Build Automation

With the flexibility GitHub Actions offers, and now the total separation of the Skeletons workflow from the rest of the Grav continuous integrations, we had the great opportunity of rethinking how we wanted the whole build process to work. The easy way would have been to just port over what we had originally and call it a day, but what if we could make this accessible to the rest of the community?

We decided to create an official Skeleton Builder Action, and it's incredibly simple for any Theme developer to now create and maintain their Grav Skeletons. This new system can also automatically create 2 packages, one that includes Admin and one that does not.

How to use the Skeleton Builder Action

A workflow in GitHub Actions is a collection of steps. Each steps runs one single action and one after another the workflow will reach its execution end. If everything goes right it will succeed, otherwise it will fail and provide a message of doing so.

You can access your workflows at any time in your GitHub repository from the main tabs bar, by clicking Actions.

Setup workflow

The first thing needed is to create a new workflow. You can do so by clicking on the New workflow button in the Actions section on GitHub, and then click on Skip this and set up a workflow yourself ➝.

Change the autogenerated workflow name from main.yml to build-skeleton.yml, and then replace the content entirely with the following magic formula:

name: Build Skeleton

on:
  release:
    types: [ published ]
  workflow_dispatch:
    inputs:
      tag:
        description: 'Target tag for re-upload'     
        required: true
        default: ''
      version:
        description: 'Which Grav release to use'
        required: true
        default: 'latest'
      admin:
        description: 'Create also a package with Admin'
        required: true
        default: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Extract Tag
        run: echo "SKELETON_VERSION=${{ github.event.inputs.tag || github.ref }}" >> $GITHUB_ENV
      - name: Generate Skeleton Packages
        uses: getgrav/skeleton-builder@v1
        with:
          version: ${{ github.event.inputs.version || 'latest' }}
          admin: ${{ github.event.inputs.admin || true }}
      - name: Upload packages to release
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ env.SKELETON_VERSION }}
          file: dist/*.zip
          overwrite: true
          file_glob: true

Click on the Start commit button and then Commit. You should now have your workflow created and if you go to the root of your repository, you should see a new folder created .github/workflows that contains the file build-skeleton.yml we created above.

How to use

The workflow in combination with the Skeleton Builder Action supports the creation of Skeleton packages in two ways:

• Automatically: every time a new release of your skeleton is published on GitHub, the workflow will run, generate the packages and upload them on your just published release.

• Manually: if you don't have anything to release, but you want to rebuild the packages to use the latest version of Grav or any of your Skeleton dependencies, you can use this way.

To use the automatic mode, you don't have to do anything other than follow the standard procedure of GitHub release. Once a new Release is created, the workflow will spin off.

The Manual mode, instead, can be reached in GitHub under Actions ➝ Build Skeleton ➝ Run workflow, where you will have to specify the release tag version you are targeting to rebuilt.

Assuming your latest Skeleton release is v1.0.0, but a new version of Grav was released and you want to update your packages, you would run the Manual workflow and type v1.0.0 as target tag.

All the existing packages from that version will get now overwritten and will contain the latest version of Grav and the Skeleton dependencies.

Input options

This workflow and action comes with a set of useful input parameters that can be used for customizing the build.

• version (default: latest): The Grav version to utilize for building the Skeleton package. There is no reason for using anything but latest unless you are testing something.
• admin (default: true): Whether a second package should be created that includes Admin. Note that when this is set to true this will generate 2 packages, one with admin and one without.
• exclude (default: <empty>): A space separated list of file/folder names to be excluded from getting packaged (ie, README.md C* *private/*). [check out also the built-in exclusions.]
• filename_version (default: true): By default the packages get created with the version of the release appended to the filename. If this is not desired, disabling this will omit the version.
• verbose (default: false): Will output everything happening in the action, useful for debugging.

Successful run, what's next?

Once the build job has successfully finished running, you will see two packages attached to your Release in GitHub, named as <repo>-<version>.zip and <repo>+admin-<version>.zip (ie, grav-skeleton-blog-site+admin-2.0.0.zip). These packages will get picked up by GPM automatically.

If you run the workflow manually, it will overwrite the packages of your latest Skeleton release, these packages will be be part of GPM right away and you won't need to wait for the next cycle.

Under the Skeletons Downloads section on the Grav website, your Skeleton will now show both download links to your packages.

Wrap-up

We hope you will enjoy this new workflow for your Skeleton! If you have been building them manually before, you know exactly how time-consuming of a process this has been in the past. With this new setup you will now be able to fully delegate this process.