Skip to content

README.md

Latest commit

 

History

History
165 lines (120 loc) · 5.49 KB

README.md

File metadata and controls

165 lines (120 loc) · 5.49 KB

Cognitive Code Analysis GitHub Action

Composite GitHub Action that runs Cognitive Code Analysis (phpcca) in pull-request workflows. Install via PHAR or Composer, analyse changed PHP files, and optionally publish Markdown PR comments, workflow annotations, artifacts, and SARIF uploads.

Repository: Phauthentic/cognitive-code-analysis-github-action

This repository is separate from the main cognitive-code-analysis package (issue #29).

Quick start

Add this workflow to your repository (.github/workflows/cognitive-code-analysis.yml):

name: Cognitive Code Analysis

on:
  pull_request:
    paths:
      - '**/*.php'

permissions:
  pull-requests: write
  contents: read

jobs:
  analyse:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: Phauthentic/cognitive-code-analysis-github-action@v1
        with:
          install-mode: phar
          post-comment: true
          upload-artifact: true
          emit-annotations: true

When cca.yaml exists in your project root, phpcca loads it automatically. See the main CI integration guide for manual workflow snippets.

Inputs

Input Default Description
install-mode phar phar or composer
phar-version 1.11.0 Release tag to download from Phauthentic/cognitive-code-analysis
phar-url (empty) Override PHAR download URL (for forks/testing)
composer-command vendor/bin/phpcca Path to phpcca when install-mode=composer
config (empty) Config file path; empty = auto cca.yaml in CWD
php-version 8.4 PHP version via shivammathur/setup-php
analyze-changed-files-only true Diff PR base...head for .php files; if false, use paths
paths src Space-separated paths when not using changed-files mode
post-comment true Post Markdown report as PR comment via actions/github-script
upload-artifact true Upload report files as artifact
artifact-name cca-report Artifact name
emit-annotations true Run --report-type=github-actions and print to stdout
upload-sarif false Generate SARIF and upload via github/codeql-action/upload-sarif
fail-on-threshold false Fail job if methods exceed threshold (JUnit report)
token ${{ github.token }} Token for PR comments / SARIF upload

Outputs

Output Description
has-report true when a Markdown or SARIF report was generated
changed-files-count Number of PHP files analysed
report-path Path to the Markdown report file, if generated
sarif-path Path to the SARIF report file, if generated

Permissions

Grant only the permissions you need:

permissions:
  contents: read                    # always required
  pull-requests: write              # post-comment: true
  security-events: write            # upload-sarif: true

Install modes

PHAR (default)

Downloads phpcca.phar from GitHub Releases. No Composer install step required in your workflow.

- uses: Phauthentic/cognitive-code-analysis-github-action@v1
  with:
    install-mode: phar
    phar-version: '1.11.0'

Composer

Install dependencies first, then point the action at your binary:

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.4'
    tools: composer

- run: composer install --prefer-dist --no-ansi --no-interaction --no-progress

- uses: Phauthentic/cognitive-code-analysis-github-action@v1
  with:
    install-mode: composer
    composer-command: vendor/bin/phpcca

Feature toggles

Each report type requires a separate phpcca invocation (one --report-type per run). The action runs only the passes you enable:

Toggle Report type Behaviour
post-comment or upload-artifact markdown Writes cca-report.md
emit-annotations github-actions Prints ::warning / ::error lines to the log
upload-sarif sarif Writes cca-results.sarif and uploads to Code Scanning
fail-on-threshold junit Writes cca-junit.xml; fails when failures > 0

fail-on-threshold is off by default. Enable it when you want the job to fail on threshold violations.

Examples

See examples/minimal.yml for a PHAR workflow with PR comments, and examples/full-featured.yml for all toggles documented.

Local / path reference

Pin a stable release (recommended):

- uses: Phauthentic/cognitive-code-analysis-github-action@v1

Test the action from the default branch before a release:

- uses: Phauthentic/cognitive-code-analysis-github-action@master

Or reference a checkout of this repo:

- uses: ./path/to/cognitive-code-analysis-github-action
  with:
    analyze-changed-files-only: 'false'
    paths: src/
    post-comment: false

Development

shellcheck scripts/**/*.sh

The ci.yml workflow runs Shellcheck and a dogfood job against fixtures/.

License

GPL-3.0-only — see LICENSE.