Building this blog, part 5 of 5

The checks that run on every pull request to this blog

Nazmul Hasan Robin Avatar

10 min read

Blog banner "Eight checks on every PR" with a terminal window showing eight passed checks and a green checkmark icon.

Every change to this blog’s code goes through a pull request, and eight small checks run on it before I merge. This post lists each check, the part of the workflow that runs it, and what it has caught so far.

This post is part of the series on how this blog is built. It builds on how the blog’s code is kept in git and deployed and on publishing posts from Markdown files.

Why a one-person project needs them

I am the only one who writes this code, and the only one who reviews it. Nobody else will notice a deploy script that deletes the wrong folder, or a token pasted into a file.

A push to the production branch goes straight to the live server. So the checks do the part of a review that a second person would do: read every line, every time, without getting tired.

All of them live in one file, .github/workflows/checks.yml, which starts like this:

name: Checks

on:
  pull_request:

jobs:

Each section below is one check in that file. Most of them are steps of one job, checks, which runs on PHP 8.2; the end of the post says why they are not a job each.

PHP syntax, on three versions

The plugin says it needs PHP 7.4. The server ran 8.2 when I set this up, and runs 8.5 now. Every tracked PHP file is checked on all three: on 8.2 in the checks job, and on the other two in a small job of their own:

  php:
    name: PHP syntax and tests (${{ matrix.php }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: [ "7.4", "8.5" ]

    steps:
    - uses: actions/checkout@v4

    - uses: shivammathur/setup-php@v2
      with:
        php-version: ${{ matrix.php }}
        coverage: none

    - name: Check every tracked PHP file
      run: git ls-files '*.php' | xargs -n 1 php -l

git ls-files lists only what is in the repo, so the plugins Composer installs are not checked. They are not my code.

WordPress coding standards

PHPCS with the WordPress standard reads the plugin, the theme and the must-use plugins. Besides code style, that standard has the rules I care about most: output is escaped, input is sanitized, and a form handler checks its nonce.

    - name: Install PHPCS with the WordPress standard
      run: |
        composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
        composer global require --no-interaction wp-coding-standards/wpcs:^3.1

    - name: Run PHPCS with phpcs.xml.dist
      run: phpcs

The settings are in phpcs.xml.dist at the repo root. It names the folders, the text domain and the prefix every global name has to start with:

<config name="minimum_wp_version" value="6.7"/>
<!-- Warnings are reported but only errors fail the check. -->
<config name="ignore_warnings_on_exit" value="1"/>

<rule ref="WordPress.WP.I18n">
    <properties>
        <property name="text_domain" type="array">
            <element value="myblog"/>
        </property>
    </properties>
</rule>

<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
    <properties>
        <property name="prefixes" type="array">
            <element value="myblog"/>
        </property>
    </properties>
</rule>

One false positive needed its own setting. My LinkedIn form handlers did not call check_admin_referer() themselves. They called one helper that checks the nonce and the user’s capability together:

function myblog_linkedin_check_admin( $action ) {
    check_admin_referer( $action );

    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( esc_html__( 'You are not allowed to manage the LinkedIn connection.', 'myblog' ), 403 );
    }
}

PHPCS does not look inside the helper, so it reported every handler as reading $_POST without a nonce check. The rule has a property for exactly this:

<rule ref="WordPress.Security.NonceVerification">
    <properties>
        <property name="customNonceVerificationFunctions" type="array">
            <element value="myblog_linkedin_check_admin"/>
        </property>
    </properties>
</rule>

That is better than a phpcs:ignore comment on every handler. A new handler that forgets the helper is still reported.

Tests

The site plugin has PHPUnit tests for the parts where a mistake is easy to make and hard to see: the Markdown parser, the reactions endpoint, the views route and the “reading now” count. There are 63 so far. They run with WP_Mock, which stands in for WordPress’s functions, so no database or WordPress install is needed. Like the syntax check, they run on all three PHP versions, as two more steps of the same jobs:

    # PHPUnit has its own composer.json in tests/, apart from the packages that are deployed.
    - name: Install PHPUnit
      run: composer install --working-dir=tests --no-interaction

    - name: Run the tests
      run: composer test --working-dir=tests

PHPUnit has its own composer.json in tests/ for the same reason as PHPCS below: the root vendor folder is copied to the live site.

Composer packages

    - name: Validate composer.json and composer.lock
      run: composer validate

    - name: Look for known vulnerabilities in the locked packages
      run: composer audit --locked

composer validate fails when composer.json was edited and the lock file was not updated with it. composer audit compares the locked packages with the published security advisories.

The scripts and the workflows

    - name: Check JavaScript syntax
      run: git ls-files '*.js' ':!:*/admin/*' | xargs -n 1 node --check

    - name: Check the deploy and staging scripts
      run: shellcheck deploy.sh staging.sh

    - name: Check the workflows
      run: |
        bash <(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
        ./actionlint -color

shellcheck failed on its first run, on this line of the deploy script:

rm -rf "$WP_PATH/$dir"

If WP_PATH were ever empty, that line would delete /wp-content/plugins/... from the root of the server. The fix it asked for is three characters:

rm -rf "${WP_PATH:?}/$dir"

With :? the shell stops with an error when the variable is empty or not set, and deletes nothing. The script had worked on every deploy until then. The check found a problem that only shows on the day something else goes wrong.

actionlint reads the workflow files themselves. A typo in a key name there is otherwise only found when the workflow runs, and for a deploy that is the wrong moment.

The admin app’s build

One wp-admin screen of the site plugin is a React app. The server has no Node, so the built files are committed. This check makes sure they belong to the source next to them:

    - name: The committed build matches the source
      run: |
        npm run build
        if [ -n "$(git status --porcelain admin/build)" ]; then
          echo "::error::admin/build is out of date. Run npm run build and commit the result."
          git status --short admin/build
          exit 1
        fi

It builds the app again and fails if git sees any difference. A step before it runs ESLint on the source.

A scan for secrets

The scan is a step of the checks job, so that job’s header carries what the scan needs:

  checks:
    name: Checks (8.2)
    runs-on: ubuntu-latest
    # gitleaks reads the pull request's list of commits.
    permissions:
      contents: read
      pull-requests: read

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    # ... the other checks ...

    - uses: gitleaks/gitleaks-action@v2
      env:
        GITHUB_TOKEN: ${{ github.token }}

gitleaks looks through the branch’s commits for things shaped like keys and tokens. fetch-depth: 0 gives it the full history; the default checkout has one commit.

This check also failed on its first run, and not because of a secret. On my private repo the workflow’s token could not read the pull request, and gitleaks needs the pull request’s list of commits. The permissions block fixed it.

A new version and a changelog entry

Every deploy of this blog is a numbered release. The last check makes sure a pull request that changes deployed code also raises the version and says what changed:

    - name: Deployed code needs a new version and a changelog section
      env:
        BASE: origin/${{ github.base_ref }}
      run: |
        plugin=wp-content/plugins/myblog/myblog.php

        if git diff --quiet "$BASE...HEAD" -- wp-content composer.json composer.lock deploy.sh staging.sh; then
          echo "No deployed code changed."
          exit 0
        fi

        version=$(sed -n 's/^ \* Version: *//p' "$plugin")
        before=$(git show "$BASE:$plugin" | sed -n 's/^ \* Version: *//p')

        if [ "$version" = "$before" ]; then
          echo "::error file=$plugin::Deployed code changed but Version is still $version."
          exit 1
        fi

        if ! grep -q "^## $version " CHANGELOG.md; then
          echo "::error file=CHANGELOG.md::CHANGELOG.md has no section for $version."
          exit 1
        fi

A pull request that only edits the README passes without a new version. One that touches anything the deploy copies does not.

After a deploy, the deploy workflow reads the same version, creates the git tag v1.2.3 and a GitHub release, and uses that version’s changelog section as the release notes. So the check on the pull request is what keeps the list of releases complete.

The posts have their own check

The posts are in a second repo, and a pull request there runs one Ruby script. It checks each file’s name, that the front matter is valid YAML with a title, a date and an excerpt, that the category is on the allowed list, and that a link to another post points at a post that exists.

The front matter check is there because of one title. It had a colon followed by a space in it and no quotes:

title: Claude Code tip: two accounts on one machine

My own sync reads each line with a regular expression and was happy with it. GitHub reads the block as YAML, could not parse it, and showed an error where the file’s preview should be. The script now parses the block the way GitHub does:

begin
  meta = YAML.safe_load(front, permitted_classes: [Date, Time])
rescue Psych::Exception => e
  fail_with.call("the front matter is not valid YAML (#{e.message.lines.first.strip}). Put a value containing a colon and a space in double quotes.")
  next
end

Things that caught me

  • PHPCS cannot go into composer.json here. Composer’s vendor folder in this repo is copied to the live site with the plugin. So the workflow installs PHPCS globally, and locally I use any PHPCS that has the WordPress standard.
  • File names clash with the standard. The standard wants class-my-thing.php. My classes are loaded by Composer’s PSR-4 autoloader, which wants MyThing.php. Those two file name rules are excluded in phpcs.xml.dist, with a comment saying why.
  • Warnings do not fail the check. Only errors do. Otherwise one warning I disagree with would teach me to ignore a red check.
  • Each job costs at least a minute. GitHub bills a private repo’s Actions by the minute, rounded up for each job, and the free plan has 2,000 minutes a month. At first every check was a job of its own, twelve with the PHP versions, and each one took seconds but counted as a minute. That used most of a month’s minutes in October. Now the checks are steps of three jobs, and a pull request that only changes Markdown or docs/ skips them. The cost of that: a failed step stops its job, so a check after it shows its result on the next push.
  • A red check does not stop a merge. Branch protection on a private repo needs a paid GitHub plan. For now the rule is mine to keep: no merge while a check is red.

Next to the checks

Two more workflows run outside this file. Lighthouse measures the staging copy after each deploy to it, the home page and the newest post, and prints the scores. And Claude reviews each pull request that changes code and writes what it finds as comments. Neither blocks a merge; both are second opinions.

Eight checks, one workflow file, and two of them failed on their first run for good reasons.

Was this useful?
Nazmul Hasan Robin Avatar

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

Your first comment is reviewed before it appears. After that, your comments appear straight away.