Making GitHub CI Logs Readable: Structured Output with Phanalist

Have you ever been in a situation where you made a PR or MR and waited for a couple of seconds for the output of the CI pipeline? But something went wrong, and you can't see the issue in the blink of an eye. And you get annoyed that you must read a few logs to discover the problem?

It's a scenario that many of us have likely encountered at some point.

This article teaches how to improve your CI output. I will use Github.

This article is part of a series about a static analysis tool I've worked on for over a year. It's called Phanalist. Please check it out and hit the star button. Thank you.

How can I improve the CI output in Github? When running your CI tools, you probably output everything to STDOUT and view the content in the log viewer.

Something like this:

The output format text in Phanalist is not so bad. It's readable because of the table layout. But why stop there?

Microsoft is not so evil anymore, and Github has solved that problem I've already. What we will be using is what they call SARIF. It stands
for Static Analysis Results Interchange Format. It's a specification for understanding the output of static analysis tools. That is how the tools can display information in the code scanning section under the security tab on a repository.

For Phanalist to have a chance to be adopted by more people, this is a must feature that should be implemented first. Then, I can focus on adding more rules to the tool.

For context, Phanalist consists of rules implemented by the contributors. Every rule has a detailed explanation of what you are doing wrong and guides you in the right direction so you can fix it.

The tools under the code scanning section use a Github action called github/codeql-action/upload-sarif. This action uploads a .sarif file to GitHub. Remember that you will need the right permissions to upload a file from the Github workflow. After uploading, Github will validate the file's content, and if there are any errors, they will be displayed in the logs. If everything goes well, you will have more issues to fix under the security tab.

The tools you use should have a Sarif output. At the time of writing, I do not know if the popular static analysis tools in the PHP ecosystem support Sarif, but if not, you can help them with that.

But Phanalist supports that format. It can output information in three formats: text, json, and sarif.

phanalist --src=. --output-format=sarif

Enter fullscreen mode Exit fullscreen mode

The output will be something like this:

{"version": "2.1.0","$schema": "http://json.schemastore.org/sarif-2.1.0-rtm.4","runs": [
    {
      "tool": {
        "driver": {
          "name": "Phanalist",
          "informationUri": "https://github.com/denzyldick/phanalist",
          "rules": [
            {
              "id": "e0009",
              "shortDescription": {
                "text": "Method is too complex"
              },
              "properties": {
                "category": "phanalist"
              }
            }
          ]
        }
      },
      "artifacts": [
        {
          "location": {
            "uri": "src/complex.php"
          }
        }
      ],
      "results": [
        {
          "level": "warning",
          "message": {
            "text": "Method is too complex."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/complex.php",
                  "index": 0
                },
                "region": {
                  "startLine": 1,
                  "startColumn": 5
                }
              }
            }
          ],
          "ruleId": "no-unused-vars",
          "ruleIndex": 0
        }
      ]
    }]}

Enter fullscreen mode Exit fullscreen mode

I won't explain Sarif in detail in this article; the people behind it have already done an excellent job.

The next step is to upload this output to Github using the github/codeql-action/upload-sarif.

on:push:
    branches:
      - "main"name: Sarifjobs:upload-sarif:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rust toolchain
        uses: actions-rs/[email protected] #@v1
        with:
          profile: minimal
          toolchain: stable
          override: true
      - run: cargo run --release -- --src=. --output-format=sarif | tee results.sarif
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Enter fullscreen mode Exit fullscreen mode

After executing this workflow, the result will be displayed in the security tab under code scanning.

The rules in Phanalist also consist of detailed explanations written in Markdown, which are backed into the executable binary. This comes in very handy when scanning code. In Sarif, you can specify a Markdown for the result found when you ran your tool.

If I click and open one of the warnings, I will be greeted with a detailed explanation. Including the file and location that is causing the issue.

I hope you learned something useful and can now improve your CI output.