GitHub

Goal

Integrate codee with GitHub to automatically run static analysis over your source code.

Prerequisites

Ensure you have:

codee installed and accessible in your GitHub runners.

Create a GitHub Actions workflow

GitHub Actions can be used to run codee checks automatically on pull requests and ensure that all contributions do not include bugs in their Fortran code.

In your repository, create the following directory structure if it does not exist:

mkdir
mkdir -p .github/workflows/

Then, create a new workflow file:

touch

touch .github/workflows/codee-checks.yml

Define the GitHub actions workflow

1. Generate status report

GitHub Actions can be used to produce Codee HTML reports to summarize the detected quality and security issues found throughout the entire codebase.

This example uses the MATMUL Fortran code of the codee-demos repository.

Add the following content to your .gitlab-ci.yml file, but first remember to enable GitHub Pages (Settings > Pages)on your repository:

name: Codee HTML Report

on:
  push:
    branches:
      - main

jobs:
  codee-report:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

      - name: Build project
        run: |
          cd Fortran/MATMUL
          cmake . -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -G "Ninja" -B build

      - name: Run Codee and generate HTML
        run: |
            cd Fortran/MATMUL
            codee screening -p build/compile_commands.json --html htmlOUT

      - name: Upload pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: Fortran/MATMUL/htmlOUT

  deploy:
    needs: codee-report
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub pages
        id: deployment
        uses: actions/deploy-pages@v4

How it works

The workflow runs whenever changes are updated to the main branch.
It runs codee to generate the screening and checks reports on HTML format.
Now you can access to your GitHub Pages site to visualize the HTML report. You can also find it in the artifacts section.

2. Verify critical checkers

Warning

A Fatal/Error checker is a user-defined analysis rule that flags high-severity issues in the code. These checkers are explicitly defined by the user using the --check-id flag when running Codee.

GitHub Actions can be used to run codee checks automatically on pull requests and ensure that all contributions do not include bugs in their Fortran code.

This example uses the MATMUL Fortran code of the codee-demos repository. In this case, the pipeline will be stopped if Codee triggers PWR072 or PWR079.

Add the following content to .github/workflows/codee-checks.yml:

name: Codee Checks

on:
  pull_request:

jobs:
  static-analysis:
    name: Run Codee checks
    runs-on: self-hosted

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

      - name: Get modified Fortran files
        id: modified-files
        run: |
          MODIFIED_FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD -- '*.f90' '*.F90' '*.f' '*.F')
          echo "MODIFIED_FILES=$MODIFIED_FILES" >> $GITHUB_ENV

      - name: Run Codee checks
        if: env.MODIFIED_FILES != ''
        run: |
          echo "Generate compile_commands.json"
          cd Fortran/MATMUL && cmake . -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -G "Ninja" -B build
          echo "Running Codee checks on modified files: $MODIFIED_FILES"
          codee checks \
            --check-id PWR072,PWR079 \
            --verbose \
            -p build/compile_commands.json \
            $MODIFIED_FILES --json > codee_output.json

      - name: Fail if critical checkers were found
        if: env.MODIFIED_FILES != ''
        run: |
          ISSUE_COUNT=$(jq '.Checks | length' Fortran/MATMUL/codee_output.json)
          if [ "$ISSUE_COUNT" -gt 0 ]; then
            echo "Codee detected $ISSUE_COUNT critical issues."
            exit 1
          else
            echo "No critical issues found by Codee."
          fi

How it works

The workflow runs whenever a pull request is opened or updated.
It runs codee checks if there are modified Fortran source files in the current branch.
If codee triggers a PWR072 or a PWR079 checker, the GitHub action will fail.

3. Warning on nice-to-have checkers

Similar to the previous example we can use GitHub Actions to execute codee checks and notify the user about the presence of non-critical checkers. To do this we can use the --no-check-id Codee flag to filter-out the critical checkers. In this case the pipeline, it will only raise a warning and an artifact with the Codee output in JSON format (note the --json Codee flag) will be generated so it can be reviewed.

This example uses the MATMUL Fortran code of the codee-demos repository.

Add the following content to .github/workflows/codee-checks.yml:

name: Codee Checks

on:
  pull_request:

jobs:
  static-analysis:
    name: Run Codee checks
    runs-on: self-hosted

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

      - name: Get modified Fortran files
        id: modified-files
        run: |
          MODIFIED_FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD -- '*.f90' '*.F90' '*.f' '*.F')
          echo "MODIFIED_FILES=$MODIFIED_FILES" >> $GITHUB_ENV

      - name: Run Codee checks
        if: env.MODIFIED_FILES != ''
        run: |
          echo "Where I am?"
          echo "$(pwd)"
          echo "Generate compile_commands.json"
          cd Fortran/MATMUL && cmake . -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -G "Ninja" -B build
          echo "Running Codee checks on modified files: $MODIFIED_FILES"
          cd ../..
          codee checks \
            --no-check-id PWR072,PWR079 \
            --verbose \
            -p Fortran/MATMUL/build/compile_commands.json \
            $MODIFIED_FILES --json > codee_output.json

      - name: Warn if non-critical checkers were found
        if: env.MODIFIED_FILES != ''
        run: |
          WARN_COUNT=$(jq '.Checks | length' codee_output.json)
          if [ "$WARN_COUNT" -gt 0 ]; then
            echo "Codee detected $WARN_COUNT non-critical issues."
            cat codee_output.json
          else
            echo "No critical issues found by Codee."
          fi

      - name: Upload Codee output as artifact
        if: env.MODIFIED_FILES != ''
        uses: actions/upload-artifact@v4
        with:
            name: codee-output
            path: codee_output.json

How it works

The workflow runs whenever a pull request is opened or updated.
It runs codee checks if there are modified Fortran source files in the current branch.
If codee finds non-critical checkers, it will warn the users and create an artifact with the codee output for review.

4. Apply Autofixes

Warning

Be cautious when using Codee Autofixes to apply automatic changes to your codebase. Always review the proposed modifications before merging, as they might introduce unintended side effects.

GitHub actions can also be used to automatically apply codee rewrite to fix Fortran code if there are Autofixes available for certain checkers.

Add the following content to .github/workflows/codee-rewrite.yml:

name: Codee autofixes

on:
  pull_request:

permissions:
  contents: write
  pull-requests: write

jobs:
  autofix:
    name: Apply autofix if possible
    runs-on: self-hosted

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}

      - name: Get modified Fortran files
        id: modified-files
        run: |
          MODIFIED_FILES=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }}...HEAD -- '*.f90' '*.F90' '*.f' '*.F')
          echo "MODIFIED_FILES=$MODIFIED_FILES" >> $GITHUB_ENV

      - name: Run `codee checks` and export JSON
        if: env.MODIFIED_FILES != ''
        run: |
          echo "Generate compile_commands.json"
          cd Fortran/MATMUL && cmake . -DCMAKE_Fortran_COMPILER=gfortran -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -G "Ninja" -B build
          codee checks \
            --check-id PWR007,PWR008,PWR068,PWR003 \
            --verbose \
            -p build/compile_commands.json \
            $MODIFIED_FILES --json > codee_output.json

      - name: Apply autofixes if available
        if: env.MODIFIED_FILES != ''
        run: |
          echo "Checking for autofixes..."
          cd Fortran/MATMUL
          jq -r '.Checks[] | select(."Auto-fix" != null) | ."Auto-fix"[]' codee_output.json > autofix_commands.txt
          if [ ! -s autofix_commands.txt ]; then
            echo "No autofixes found."
            exit 0
          fi
          applied=0
          while IFS= read -r fix_cmd; do
            echo "Applying: $fix_cmd"
            eval "$fix_cmd"
            applied=$((applied + 1))
            done < autofix_commands.txt
          echo "Total autofixes applied: $applied"

      - name: Commit changes if autofixes were applied
        if: env.MODIFIED_FILES != ''
        run: |
          if ! git diff --quiet; then
            # Push with the github-actions user. More information at:
            # https://github.com/actions/checkout?tab=readme-ov-file#push-a-commit-using-the-built-in-token
            git commit -c user.name="github-actions[bot]" -c user.email="41898282+github-actions[bot]@users.noreply.github.com" -am "Apply Codee autofixes"
            git push --set-upstream origin ${{ github.head_ref }}
          else
            echo "No changes from autofixes."
          fi

How it works

The workflow runs whenever a pull request is opened or updated.
It runs codee checks to check if the checkers appear in the code; in this case it is configure to trigger PWR007, PWR008, PWR068 and PWR003.
If there is an Autofix available it will automatically apply it and commit the changes.
It won't block branch merges.

Troubleshooting

If the action does not trigger, verify the on: section.
If formatting does not apply, check if your files match the specified glob patterns (*.f90, *.F90, etc.).

Prerequisites​

Create a GitHub Actions workflow​

Define the GitHub actions workflow​

1. Generate status report​

How it works​

2. Verify critical checkers​

How it works​

3. Warning on nice-to-have checkers​

How it works​

4. Apply Autofixes​

How it works​

Troubleshooting​

Prerequisites

Create a GitHub Actions workflow

Define the GitHub actions workflow

1. Generate status report

How it works

2. Verify critical checkers

How it works

3. Warning on nice-to-have checkers

How it works

4. Apply Autofixes

How it works

Troubleshooting