You must already know about GitHub specially if you are a Software Engineer. Ok, that’s great to know that you know. Now let’s talk about as a PHP developer how we can use GitHub actions or workflows (group of actions) to automate our CI job. It was very much expected feature from GitHub.

What is GitHub actions & workflow?

You got me right. I need to tell you this first otherwise this article seems useless to you unless you have some basic understanding about GitHub actions and workflow.

Well, GitHub actions is a specific action that you want to perform each time anything changes in your repository ( codebase). And GitHub workflows is actually a procedures or tasks consists of multiple actions.

For example, you developed a PHP library or application. You are pushing code there alone or you are working with other team members. But it’s very difficult to check every commit about who is working what or who pushed some bad codes in your repository. It’s really difficult. So you want to run some automated tests on every commit pushed to your GitHub repository.

Do you want to do that manually. Hey John, just write me in Slack that you pushed something so I can test. It’s not a good idea. So you want some automated stuff. That we called CI (continuous integration). You need to make sure that if something goes wrong you will know that first and upfront.

Most of the CI tools does that job for you. You define all the steps about what should be done and in which case it will inform you about failure or success. If all are OK, you can sleep well at night at least by knowing that your codebase is growing large without any issue from anybody.

So GitHub brought this complete CI automated system for every GitHub user. You can define actions and you can define workflow with a group of actions. You can define trigger and GitHub will run all those actions or workflow for you. If anything bad happens you will know that. Just keep writing code.

Sample GitHub workflow for PHP project

I have created a small PHP hello world repository for demonstrating purpose. You can explore that from https://github.com/shahariaazam/hello-world-for-demo . In that repository you will see there is a directory called .(dot)github.

Go to that “.github” directory then go to “workflows” directory. You will see a file called ‘workflow.yml’. All the naming are based on GitHub rules. Now let’s see what’s inside in our workflow.yml file.

# Name of the workflow
name: Basic-CI

# When someone will push or make PR to this repository, this workflow will start
on: [push, pull_request]

jobs:
  tests:

    # This workflow task will run on Ubuntu machine
    runs-on: ubuntu-latest

    # Steps that should be performed to check whether tests task was successful or not
    steps:
      - name: "Checkout latest revision"
        uses: actions/checkout@v2

        # We are using shivammathur/setup-php@v1 public GitHub actions for keeping things easier
      - name: "Install PHP with extensions"
        uses: shivammathur/setup-php@v1
        with:
          # This job will be running on php7.4 version
          php-version: '7.4'

          # For PHPUnit code coverage, we need xdebug
          coverage: xdebug

          # If we want to enable any other PHP extension we can add here
          extensions: xdebug, intl, pdo_mysql, pdo

      # We need to install composer.phar first in the system
      - name: Install composer
        run: curl --show-error --silent https://getcomposer.org/installer | php

      # Run composer to install all dependencies
      - name: Install composer dependencies
        run: php composer.phar install

      # Now run the PHPUnit tests
      - name: Run PHPUnit tests
        run: ./vendor/bin/phpunit --configuration=phpunit.xml --coverage-clover ./build/coverage/log/coverage.xml

      # For code coverage report we are uploading our code coverage report to scrutinizer
      - name: Downloading scrutinizer ocular.phar
        run: wget https://scrutinizer-ci.com/ocular.phar

      # Uploading reports for analysis
      - name: Uploading code coverage to scrutinize
        run: php ocular.phar code-coverage:upload --format=php-clover ./build/coverage/log/coverage.xml

First, take two minutes to read the file and don’t miss to read the comments. Then resume your reading.

In that file I defined a job name “tests” and defined all the steps to be done successfully. Every steps has a name and the associated command. I want to run PHPUnit tests on every pull and PR request I receive in this repository.

Once I push some commit there, this workflow will start running automatically. See the screenshot below.

GitHub Workflow Log page

Here you will see that all the steps I defined in my “workflow.yml” file finished running. You can collapse any specific steps to see the details output.

GitHub Workflow Details Output of Step

That’s it. So you defined steps in your workflow. It will start running on your pre-defined triggering point. In this project I set that “on: [push, pull_request]” event.

If all steps finishes running successfully meaning your commit passed your workflow meaning all the steps it passed. If anything goes wrong you will see failed icon and you can see that in your commit history that commit broke something that didn’t pass your test.

So if it doesn’t pass all the workflow you can see details and can decide what you want to do with that commit.

So this is it for now. As a PHP developer you can simply take my “workflow.yml” file to kick start configuring GitHub workflow for your PHP project. If you face any trouble, don’t hesitate to let me know. Until then, keep writing good code and setup your workflow that will ultimately lead a better sleeping night for you.

Share this article with others if you think they also should know about how GitHub workflow/actions work.

Also if you are interested to learn about how GitLab CI works for PHP application. You can read that article from here.