TICS GitHub Action

The TICS GitHub action integrates the TICS code quality framework into your workflows. This allows you to effectively measure and monitor the software code quality of all your projects and their branches.

The incorporated Quality Gating feature can be used for Pull Request and Commit approvals. It can also decorate your pull request so the quality data is easily available. Furthermore, the changed files are annotated with findings from the TICS analysis, so it is clear where the issues are and thus where they need to be addressed.

There are two types of analysis modes available:

Reference runs using TICS QServer (See section QServer). Reference points with code quality metric data are created that are used for the qualification runs. Intended for base branches of pull requests, e.g. main.
Qualification runs using TICS Client (See section Client). Compares a set of changed files from a commit or pull request to the reference point for qualification, using a Quality Gate. Intended for pull requests and branches like feature or bug-fix branches.

Before you start

Prerequisites

A TICS Viewer (version 2022.4 or higher) running somewhere on the network that is HTTP(S) accessible by the runner on which you want to execute the action.
The connected runner should have Git installed.

Supported Platforms

Linux and Windows based runners, both GitHub-hosted and self-hosted, are supported.

Action Restrictions

It is not working for forked repositories.
It is not working for TICS installations using the legacy deployment architecture.
macOS runners (GitHub-hosted or self-hosted) are not yet supported.

Setup

Add the TICS GitHub Action to your workflow to launch TICS code analysis and post the results of Quality Gating feature as part of your pull request. Below are some example of how to include the TICS GitHub Action step as part of your workflow.

Client (default)

The default mode to run is TICS Client. In this mode, the commit or pull request will be evaluated. The Quality Gate determines wether the commit or pull request qualifies for delivery. The quality gate and measurement results are reported in your action summary and optionally the pull request can be decorated.

Below is an example of the minimum configuration that needs to be created in the workflow to enable TICS Client analysis:

on: [pull_request]

jobs:
  TICS:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TICS GitHub Action
        uses: tiobe/tics-github-action@v3
        with:
          viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config
          ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}
          installTics: true

Action triggers and events

The most common use case to trigger a workflow running TICS Client is typically on pull_request. Depending on the applied way of working, other events may be also applicable. Please consult Github documentation for triggering a workflow and events that trigger workflows for more information.

Basic parameters

The following inputs are recommended or required for this action:

Input	Description	Required
`viewerUrl`	A URL pointing to the "cfg" API endpoint of the TICS Viewer. It contains the name of the TICS Analyzer Configuration or "-" in case of the default configuration. Example: viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config	true
`ticsAuthToken`	Authentication token to authorize the plugin when it connects to the TICS Viewer (Only required if a token is needed to run TICS). It is highly recommended to store these tokens in GitHub Secrets and use the secrets inside your workflow instead. Example: ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}	false
`project`	Name of the TICS project present in the TICS Viewer. If not given it will use project `auto` when running Client. Is required for QServer.	false
`installTics`	Boolean parameter to install TICS command-line tools on a runner before executing the analysis. If not specified, TICS should be installed manually on the machine that runs this job, default value is `false`.	false

Advanced parameters

The following options allow to instrument TICS Client more specifically:

Input	Description	Default
`calc`	Comma-separated list of metrics to be calculated. The `GATE` metric is supported for TICS Viewer versions higher than 2022.2.x.	`GATE`
`recalc`	Comma-separated list of metrics to be recalculated. The `GATE` GATE metric is supported for TICS Viewer versions higher than 2022.2.x.	-
`nocalc`	Comma-separated list of metrics to not be calculated.	-
`norecalc`	Comma-separated list of metrics to not be recalculated.	-
`filelist`	Path to a file containing a list of files (newline separated) to run TICS for. This can be an absolute or relative (to workspace) path, and can also be `.` to analyze the whole project. This has to be set when the action is run outside of a pull request.	-
`cdtoken`	A custom client-data token for the purpose of the Client Viewer functionality. This provides a static URL that is updated with every analysis.	-
`branchname`	Name of the branch in TICS.	-
`codetype`	Allows you to pick which specific types of code you want to analyze with the TICS client. Options are `PRODUCTION`, `TESTCODE`, `EXTERNAL` and `GENERATED`.	`PRODUCTION`
`excludeMovedFiles`	Exclude moved and renamed files from analysis completely. By default these are included if there are modifications in the file.	`false`
`showBlockingAfter`	Show the blocking after violations in the changed files window. Options are `true` or `false`.	`true`
`tmpdir`	Location to store debug information.	-

QServer

As of v3, the option to run TICSQServer analyses has been made available. With TICSQServer, persistent measurement points are created which are stored in your Quality Database. These measurement points are used by the TICS Client to determine how the code quality evolved from that point. TICSQServer can also compare the last obtained results with the previous run and apply Quality Gating.

on:
  push:
    branches:
      - main

jobs:
  TICS:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TICS GitHub Action
        uses: tiobe/tics-github-action@v3
        with:
          mode: qserver
          project: project-name
          viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config
          branchdir: ${{ GITHUB_WORKSPACE }}
          ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}
          installTics: true

Action triggers and events

The most common use case to trigger a workflow running TICSQServer is typically on push to main, or any other branch from which other branches are derived. Other examples are release and develop branches. Please consult Github documentation for triggering a workflow and events that trigger workflows for more information. When triggering on multiple branches, please make sure to provide the correct project or branchName value, corresponding to the TICS branch QServer will be running on.

Basic parameters

The following inputs are recommended or required for this action:

Input	Description	Required
`mode`	Set `mode` to `qserver` run the action in TICSQServer mode. Options are `client` or `qserver` for an analysis run and `diagnostic` for a diagnostic run to test the setup. The default is `client`.	true
`project`	Name of the TICS project present in the TICS Viewer.	true
`viewerUrl`	A URL pointing to the "cfg" API endpoint of the TICS Viewer. It contains the name of the TICS Analyzer Configuration or "-" in case of the default configuration. Example: viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config	true
`branchdir`	Root directory of the source files for the branch. TICS stores the last used branch directory in the database and uses this last known directory if this property is not set. It is `recommended` to set this variable. Example: branchdir: ${{ GITHUB_WORKSPACE }}	false
`ticsAuthToken`	Authentication token to authorize the plugin when it connects to the TICS Viewer (Only required if a token is needed to run TICS). It is highly recommended to store these tokens in GitHub Secrets and use the secrets inside your workflow instead. Example: ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}	false
`installTics`	Boolean parameter to install TICS command-line tools on a runner before executing the analysis. If not specified, TICS should be installed manually on the machine that runs this job, default value is `false`.	false

Advanced parameters

The following options allow to instrument TICSQServer more specifically:

Input	Description	Default
`calc`	Comma-separated list of metrics to be calculated.	`ALL`
`recalc`	Comma-separated list of metrics to be recalculated.	-
`nocalc`	Comma-separated list of metrics to not be calculated.	-
`norecalc`	Comma-separated list of metrics to not be recalculated.	-
`branchname`	Name of the branch in TICS.	-
`excludeMovedFiles`	Exclude moved and renamed files from analysis completely. By default these are included if there are modifications in the file.	`false`
`showBlockingAfter`	Show the blocking after violations in the changed files window. Options are `true` or `false`.	`true`
`tmpdir`	Location to store debug information.	-

Other features

Action parameters

Below are some special parameters that can be used to control how the GitHub Action posts its results:

Input	Description	Default
`postAnnotations`	Show the TICS violations in the changed files window. Options are `true` or `false`.	`true`
`postToConversation`	Post the summary to the conversation page of the pull request.	`true`
`pullRequestApproval`	Set the plugin to approve or deny a pull request, by default this is false. Options are `true` or `false`. Note that once a run that added a reviewer has been completed, this reviewer cannot be deleted from that pull request. (Always the case on versions between TICS GitHub Action 2.0.0 and 2.5.0).	`false`

Infrastructural and Security related parameters

Below, parameters are described to control infra structure and security related aspects:

Input	Description	Default
`githubToken`	Applied automatically in an action (see Authenticating with the GITHUB_TOKEN), can be overridden if needed.	`GITHUB_TOKEN`
`hostnameVerification`	Check whether the certificate matches the server. Options are `1`/`true` or `0`/`false`. Documentation on Client-side SSL/TLS.	`true`
`trustStrategy`	Check the validity of certificates. Options are `all`, `self-signed` or `strict`. Documentation on Client-side SSL/TLS.	`strict`
`retryCodes`	Status codes to retry api calls for. The default codes will be overwritten if this option is set.	`419`, `500`, `501`, `502`, `503`, `504`
`secretsFilter`	Comma-separated list of extra secrets to mask in the console output.	-
`displayUrl`	The URL that end-users need to visit the TICS Viewer. This can differ from the viewerURL if TICS Client and TICSQServer communicate via a reverse proxy, but the end-users have direct access. (e.g. https://domain.com/tiobeweb/TICS)	-

Diagnostic Analysis mode

There is also the possibility to do a so called "diagnostic" run. This mode can be enabled to test if TICS has been set up properly and can run on the machine the action is run on.

on: workflow_dispatch

jobs:
  TICS:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TICS GitHub Action
        uses: tiobe/tics-github-action@v3
        with:
          mode: diagnostic
          viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config
          ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}
          installTics: true

Action triggers and events

The most common use case to trigger the diagnostic workflow is typically on workflow_dispatch. This way one can manually execute this. Please consult Github documentation for triggering a workflow and events that trigger workflows for more information.

Basic parameters

The following inputs are recommended or required for this action:

Input	Description	Required
`mode`	Set 'mode' to `qserver` run the action in Diagnostic mode. Options are `client` or `qserver` for an analysis run and `diagnostic` for a diagnostic run to test the setup. The default is `client`.	true
`viewerUrl`	A URL pointing to the "cfg" API endpoint of the TICS Viewer. It contains the name of the TICS Analyzer Configuration or "-" in case of the default configuration. Example: viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config	true
`ticsAuthToken`	Authentication token to authorize the plugin when it connects to the TICS Viewer (Only required if a token is needed to run TICS). It is highly recommended to store these tokens in GitHub Secrets and use the secrets inside your workflow instead. Example: ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }}	false
`installTics`	Boolean parameter to install TICS command-line tools on a runner before executing the analysis. If not specified, TICS should be installed manually on the machine that runs this job, default value is `false`.	false

Migration from v2 to v3

The interface (running with parameters) has been changed to better reflect its usage. This interface is now more synchronized with TICS command line usage, and has been changed to be closer to other plugins that TIOBE provides. Parameter Changes (v2/old -> v3/new):

ticsConfiguration -> viewerUrl
viewerUrl -> displayUrl
projectName -> project
branchName -> branchname
branchDir -> branchdir
clientData -> cdtoken
tmpDir -> tmpdir

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

TICS GitHub Action

Before you start

Prerequisites

Supported Platforms

Action Restrictions

Setup

Client (default)

Action triggers and events

Basic parameters

Advanced parameters

QServer

Action triggers and events

Basic parameters

Advanced parameters

Other features

Action parameters

Infrastructural and Security related parameters

Diagnostic Analysis mode

Action triggers and events

Basic parameters

Migration from v2 to v3

Files

README.md

Latest commit

History

README.md

File metadata and controls

TICS GitHub Action

Before you start

Prerequisites

Supported Platforms

Action Restrictions

Setup

Client (default)

Action triggers and events

Basic parameters

Advanced parameters

QServer

Action triggers and events

Basic parameters

Advanced parameters

Other features

Action parameters

Infrastructural and Security related parameters

Diagnostic Analysis mode

Action triggers and events

Basic parameters

Migration from v2 to v3