From 193c9d6bc411d5ca04db63c0e1774adbcf52b8f8 Mon Sep 17 00:00:00 2001 From: tiobeacj <134622351+tiobeacj@users.noreply.github.com> Date: Thu, 11 Jun 2026 12:55:24 +0200 Subject: [PATCH] Revise README to stress out differences between server and client run Updated README to stress out differences between server and client run --- README.md | 102 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 33c0810d..4bf9155d 100644 --- a/README.md +++ b/README.md @@ -35,16 +35,18 @@ Linux and Windows based runners, both GitHub-hosted and self-hosted, are support 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) +## Step 1: QServer (for reference runs) -The default mode to run is [TICS Client](https://ticsdocumentation.tiobe.com/latest/docs/#doc=user/enduser.html). In this mode, the commit or pull request will be evaluated. The `Quality Gate` determines whether 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: +As of v3, the option to run [TICSQServer](https://ticsdocumentation.tiobe.com/latest/docs/#doc=admin/admin_A3_qserverref.html) 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. ```yaml name: TICS Github Action -on: [pull_request] +on: + push: + branches: + - main jobs: TICS: @@ -53,9 +55,11 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 - - name: TICS Analysis + - name: TICSQserver Analysis uses: tiobe/tics-github-action@v3 with: + mode: qserver + project: project-name viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }} installTics: true @@ -63,9 +67,10 @@ jobs: ### 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. +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](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-a-single-event) and [events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/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 @@ -73,28 +78,27 @@ 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 | | `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 | +| `project` | Name of the TICS project present in the TICS Viewer. If absent the repository name will be used. | false | +| `branchdir` | Root directory of the source files for the branch. By default this is set to `github.workspace`, which is the root of the repository. | 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](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) 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: +The following options allow to instrument TICSQServer more specifically: -| Input | Description | Default | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | -| `calc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be calculated. The `GATE` metric is supported for TICS Viewer versions higher than 2022.2.x. | `GATE` | -| `recalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be recalculated. The `GATE` GATE metric is supported for TICS Viewer versions higher than 2022.2.x. | - | -| `nocalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be calculated. | - | -| `norecalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be recalculated. | - | -| `filelist` | Path to a file containing [a list of files](https://ticsdocumentation.tiobe.com/latest/docs/#doc=user/clientusecases.html%23client-file-list) (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 files from analysis even if there are modifications in the file. | `false` | -| `showAnnotationSeverity` | Show TICS violations with at least the specified severity in the changed files window (will also show up in `outputs.annotations`). Options are `blocking`, `blocking-after` or `issue`. This feature requires TICS Viewer 2025.1.8 or later. | `blocking-after` | -| `tmpdir` | Location to store debug information. | - | +| Input | Description | Default | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | +| `calc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be calculated. | `ALL` | +| `recalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be recalculated. | - | +| `nocalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be calculated. | - | +| `norecalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be recalculated. | - | +| `branchname` | Name of the branch in TICS. | - | +| `createProject` | Create the project in the TICS Viewer if it does not exist already (requires a viewer of version 2026.1.2 or higher). | `false` | +| `showAnnotationSeverity` | Show TICS violations with at least the specified severity in the changed files window (will also show up in `outputs.annotations`). Options are `blocking`, `blocking-after` or `issue`. This feature requires TICS Viewer 2025.1.8 or later. | `blocking-after` | +| `tmpdir` | Location to store debug information. | - | #### Deprecated parameters @@ -102,18 +106,17 @@ The following options allow to instrument TICS Client more specifically: | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------ | | `showBlockingAfter` | !Will not be used if `showAnnotationSeverity` is set! Show the blocking after violations in the changed files window. Options are `true` or `false`. | `true` | `showAnnotationSeverity` | -## QServer -As of v3, the option to run [TICSQServer](https://ticsdocumentation.tiobe.com/latest/docs/#doc=admin/admin_A3_qserverref.html) 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. +## Step 2: Client for qualification runs + +The default mode to run is [TICS Client](https://ticsdocumentation.tiobe.com/latest/docs/#doc=user/enduser.html). In this mode, the commit or pull request will be evaluated. The `Quality Gate` determines whether 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: ```yaml name: TICS Github Action -on: - push: - branches: - - main +on: [pull_request] jobs: TICS: @@ -122,11 +125,9 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 - - name: TICSQserver Analysis + - name: TICS Analysis uses: tiobe/tics-github-action@v3 with: - mode: qserver - project: project-name viewerUrl: https://domain.com/tiobeweb/TICS/api/cfg?name=config ticsAuthToken: ${{ secrets.TICSAUTHTOKEN }} installTics: true @@ -134,10 +135,9 @@ jobs: ### 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. +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](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-a-single-event) and [events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/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 @@ -145,27 +145,28 @@ 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 | | `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 | -| `project` | Name of the TICS project present in the TICS Viewer. If absent the repository name will be used. | false | -| `branchdir` | Root directory of the source files for the branch. By default this is set to `github.workspace`, which is the root of the repository. | 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](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) 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 TICSQServer more specifically: +The following options allow to instrument TICS Client more specifically: -| Input | Description | Default | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -| `calc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be calculated. | `ALL` | -| `recalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be recalculated. | - | -| `nocalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be calculated. | - | -| `norecalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be recalculated. | - | -| `branchname` | Name of the branch in TICS. | - | -| `createProject` | Create the project in the TICS Viewer if it does not exist already (requires a viewer of version 2026.1.2 or higher). | `false` | -| `showAnnotationSeverity` | Show TICS violations with at least the specified severity in the changed files window (will also show up in `outputs.annotations`). Options are `blocking`, `blocking-after` or `issue`. This feature requires TICS Viewer 2025.1.8 or later. | `blocking-after` | -| `tmpdir` | Location to store debug information. | - | +| Input | Description | Default | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | +| `calc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be calculated. The `GATE` metric is supported for TICS Viewer versions higher than 2022.2.x. | `GATE` | +| `recalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to be recalculated. The `GATE` GATE metric is supported for TICS Viewer versions higher than 2022.2.x. | - | +| `nocalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be calculated. | - | +| `norecalc` | Comma-separated list of [metrics](https://ticsdocumentation.tiobe.com/latest/docs/index.html#doc=user/clientoptions.html%23MetricAliases) to not be recalculated. | - | +| `filelist` | Path to a file containing [a list of files](https://ticsdocumentation.tiobe.com/latest/docs/#doc=user/clientusecases.html%23client-file-list) (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 files from analysis even if there are modifications in the file. | `false` | +| `showAnnotationSeverity` | Show TICS violations with at least the specified severity in the changed files window (will also show up in `outputs.annotations`). Options are `blocking`, `blocking-after` or `issue`. This feature requires TICS Viewer 2025.1.8 or later. | `blocking-after` | +| `tmpdir` | Location to store debug information. | - | #### Deprecated parameters @@ -173,6 +174,7 @@ The following options allow to instrument TICSQServer more specifically: | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------ | | `showBlockingAfter` | !Will not be used if `showAnnotationSeverity` is set! Show the blocking after violations in the changed files window. Options are `true` or `false`. | `true` | `showAnnotationSeverity` | + ## Other features ### Action parameters