CI/CD leveraging Github actions

[Tyrsson]

Ok, so, let us talk a minute about CI/CD. What it is, how it can benefit you and how to to incorporate it into your existing workflow.

Topic 1.
What it is.
Continuous Integration / Continuous Deployment
Well, what it is, kinda depends on what you need lol... I'm not trying to be sly here, it really is that simple. How much automation, as far as, code analysis/testing do you want to automate in your project? I was very fortunate in the fact that Laminas makes it very easy to incorporate Ci/Cd into your pipeline using some of the tools they have developed for their own projects! They have provided Github actions for several things. PhpCodesniffer and Psalm is just two that comes to mind. I however do not use Psalm, I use Phpstan for static analysis. But, guess what. The action still just works . So, back to what it is. Ci/Cd is a generic terminology that is used for automating part of your development operations. Such as when your contributors (or in house team members) open pull request against a target repo.
What if you could provide a given set of tools that would run against the repo instead of teaching each new contributor/developer how to setup and configure each tool on their local development server instance? Well, this is exactly what the Github actions do for you. You can configure said action to do so many things. As an example, say you want to test that your app will run on php 7.4, 8.0, 8.1 and 8.2. Well, you can do that.
What if, you want the code to meet your coding standard, as is its formatting, before you allow a pull request to be merged? Well, you can do that too.
What if, you want to run Phpstan or Psalm against the entire repo, and it pass, before you merge that contributor / developer pull request? Well, yes, you can do that as well.

Matter of fact, you can do all of these things in a single streamlined manner using Github actions!!!

In my next post I will post up a general approach for how to integrate the github actions into your workflow, some example actions etc.

 

[Tyrsson]

Part 2 (bare in mind that I will review this post several times and correct any mistakes I find if any, and I am sure I will leave some things out lol)

You have to enable actions in the repo you want to use them in.

So I guess the first part of this is where I need to give a brief introduction to how Github actions for CI/CD work. Well, in all honesty, I can not answer every aspect as to how they work outside of Php. It will vary I'm sure. In respect to this post we are discussing Php and its ecosystem. So how does it work for Php? Most commonly it will achieve its results via pulling containers/images and using technology such as Docker to build a runtime for your application. It will then (if configured) run the composer install based on your dependencies. Composer.json and composer.lock. I should also mention that I use the actions designed and built by the Laminas team. I use Laminas, so why wouldn't I? So, based on your chosen action and its config it will download and build your environment and it will/can run the "jobs" you have setup. I guess this is where some examples would help.

in your repo you will need this:
/.github/workflows/continuous-integration.yml (or something similar)

You have several things set up by this file. When the action will be triggered and on which branch. In this example its on push and pull_request against the master branch. It can also be triggered manually. The jobs will be run in a Ubuntu-Latest environment (server OS) and it uses:
laminas/laminas-ci-matrix-action@v1 as for the action.

continuous-integration.yml

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "master" branch
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  matrix:
    name: Generate job matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.matrix.outputs.matrix }}
    steps:
      - name: Gather CI configuration
        id: matrix
        uses: laminas/laminas-ci-matrix-action@v1

  qa:
    name: QA Checks
    needs: [matrix]
    runs-on: ${{ matrix.operatingSystem }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.matrix.outputs.matrix) }}
    steps:
      - name: ${{ matrix.name }}
        uses: laminas/laminas-continuous-integration-action@v1
        with:
          job: ${{ matrix.job }}

You would also need in the root of your project a .laminas-ci.json (what you will need will depend on the action you are using) file with something similar to the following. Not all actions require a file like this one. Again, it will depend on what action and workflow you are using.

{
    "ignore_php_platform_requirements": {
        "8.0": true
    },
    "stablePHP": "8.1.10",
    "additional_checks": [
        {
            "name": "PhpStan",
            "job": {
                "php": "8.1",
                "dependencies": "latest",
                "command": "composer require --dev --ignore-platform-reqs phpstan/phpstan && vendor/bin/phpstan analyse"
            }
        }
    ]
}

Since I use Phpstan for static analysis I setup an additional check and set which deps I want it to run against "latest". I also pass it the commands it needs to run the composer install for phpstan and the command to kick off the run by phpstan. Now, with this in place it will check for the root config files for the preset jobs (if anyone is interested then I will post the defaults) but they are for php_codesniffer and PhpUnit. Of course they need to be in the require dev section of your composer.json etc. It will vary from repo to repo and from core framework or codebase as to how you need to set up the related tools so their configs, baseline files, etc etc can be found by your action. You will need to read the docs for the particular action you are using.

Another key g0tcha here is that for nearly ALL github actions you will need to create tokens (aka Github Secrets), import ssh keys etc into your github account for use within the actions. This is how you grant the action permission to run against the repo. Without those the run will fail so be sure to set those up. Grant only the bare min permissions that are required to run the jobs.

What is the benefit to all of this? Well, it insures that your baseline QA requirements, as in your formatting, testing and analysis must be met, and your codebase stays consistent even when accepting pull request from outside of your core team. It will insure that your code testing guidelines are met and that you introduce fewer bugs during your release cycles because EVERYONE must have a passing run before the pull request can be merged (each request should also be reviewed by someone other than the authors when possible). I use the same workflow even in private workflows when I am the sole person commiting code. It has saved me many many hours in the long run.

 

[Tyrsson]

I guess it would be nice if I showed you what to expect during this would it not?

Once you have everything set up and working. This is what you can expect (or similar) under the action tab of the repo just after push or pull_request. The two attached screenshots are from an actual run. One shows the job matrix generation and the other shows after all jobs have ran, and 1 failed.