Forem: Viktor Tiulpin

Develop, test, and deploy your extensions for all popular CIs from a single codebase

Viktor Tiulpin — Sun, 18 Jun 2023 15:09:12 +0000

💡 The feature image shows a typical CI/CD pipeline in action partly drawn by OpenAI DALL-E, but in this article, we are going to develop something beneficial

Table of Contents

Start from the official templates
- GitHub Actions
- Azure Pipelines
Create the monorepo
Share code between actions and tasks
Build and publish
CircleCI?

This is a relatively short tutorial on how to develop, test, and deploy your CI extensions for GitHub Actions, Azure Pipelines, and CircleCI from a single monorepo and is based on the experience of creating the Qodana CI extensions.

Start from the official templates

Let's pick the technology stack for our CI extensions.

OK, I will not pick. I'll just tell you why I used TypeScript and node.js for the extensions.

Pros for using JS-based actions:

More flexible than bash/Dockerfile-based approaches
- Different libraries (like actions/toolkit and microsoft/azure-pipelines-task-lib) with more accessible and easy-to-use APIs are available out-of-box
Writing tests is relatively simple

Cons

JavaScript

So let's write a TypeScript-based action!

GitHub Actions

I found the GitHub actions documentation easier to read than Azure, so I would recommend starting writing and testing your extensions on GitHub by using the official template actions/typescript-action. The mentioned template provides a good starting point; I won't repeat the steps here. Play with it, write some simple stuff, and then return here for the next steps.

Azure Pipelines

GitHub Actions are built on Azure infrastructure, so porting your GitHub action to Azure Pipelines should be relatively easy.

So,

the "action" becomes the "task"
it's packed a bit differently, distributed, and installed the other way

And the definition of a task task.json is the same as the action one action.yml.

For example, having the following action.yml:

name: 'Your name here'
description: 'Provide a description here'
author: 'Your name or organization here'
inputs:
  milliseconds: # change this
    required: true
    description: 'input description here'
    default: 'default value if applicable'
runs:
  using: 'node16'
  main: 'dist/index.js'

"Easily" translates to the following Azure task:

{
  "$schema": "https://raw.githubusercontent.com/Microsoft/azure-pipelines-task-lib/master/tasks.schema.json",
  "id": "822d6cb9-d4d1-431b-9513-e7db7d718a49",
  "name": "YourTaskNameHere",
  "friendlyName": "Your name here",
  "description": "Provide a description here",
  "helpMarkDown": "Provide a longer description here",
  "author": "Your name or organization here",
  "version": {
    "Major": 1,
    "Minor": 0,
    "Patch": 0
  },
  "instanceNameFormat": "YourTaskNameHere",
  "inputs": [
    {
      "name": "milliseconds",
      "type": "string",
      "label": "label name here",
      "defaultValue": "default value if applicable",
      "required": true,
      "helpMarkDown": "input description here"
    }
  ],
  "execution": {
    "Node10": {
      "target": "index.js"
    }
  }
}

From such a simple example, one can see why I suggested starting with GitHub Actions. But let's continue.

To start developing your new shiny Azure Pipelines task, I suggest just copying the action directory and then implementing steps from the official Azure documentation – it's pretty straightforward.

Create vss-extension.json
Create task.json and place it into your dist directory (actually better to name it after the task name)
If you used any methods from @actions/core or @actions/github in your action, you need to replace them with the corresponding methods from azure-pipelines-task-lib (e.g. core.getInput -> tl.getInput)

The API of azure-pipelines-task-lib is similar to @actions/core and other @actions/* libraries. For example, we have a method for obtaining the input parameters:

export function getInputs(): Inputs {
  return {
    milliseconds: core.getInput('milliseconds'),
  }
}

And the same for Azure Pipelines:

export function getInputs(): Inputs {
  return {
    milliseconds: tl.getInput('milliseconds'),
  }
}

For more real cases, feel free to explore our Qodana GitHub Actions codebase utils and Azure Pipelines task utils.

Create the monorepo

We are going to use npm workspaces to manage the monorepo.
Place your action and task code into subdirectories (e.g. github) of your newly created monorepo. And then create a package.json file in the root directory.

{
  "name": "@org/ci",
  "version": "1.0.0",
  "description": "Common code for CI extensions",
  "license": "Apache-2.0",
  "workspaces": [
    "github",
    "azure"
  ],
  "devDependencies": {
    "typescript": "latest",
    "eslint": "latest",
    "eslint-plugin-github": "latest",
    "eslint-plugin-jest": "latest",
    "prettier": "latest",
    "ts-node": "latest"
  }
}

So the monorepo structure looks like this:

...
├── action.yaml
├── github/
├── azure/
└── package.json

After implementing the workspace setup, you can run tasks and actions from the root directory. For example, to run the build task from the github directory, you can use the following command:

npm run -w github build

Share code between actions and tasks

The most valuable part from using the monorepo approach starts here: you can share the code between your actions and tasks.

We are going to do the following steps:

Create a common directory in the root of the monorepo, a subproject for shared code
Update tsconfig.json compiler configurations from all sub-dirs for proper project builds

At first, let's create the base tsconfig – tsconfig.base.json with the base settings that are going to be used in all subprojects:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "composite": true
  },
  "exclude": ["node_modules", "**/*.test.ts", "*/lib/**"]
}

Then create a simple tsconfig.json in the project root:

{
  "references": [
    { "path": "common" },
    { "path": "azure" },
    { "path": "github" }
  ],
  "files": []
}

Then common/tsconfig.json:

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "."
  },
  "files": ["include your files here or use typical include/exclude patterns"]
}

And finally, update the tsconfig.json files in the subprojects (they are basically the same, e.g. github/tsconfig.json):

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../common" }
  ]
}

Now you can use the shared code from the common directory in your actions and tasks. For example, we have a qodana.ts file in the common directory that contains function getQodanaUrl that returns the URL to the Qodana CLI tool. And we use it in both actions and tasks.

Build and publish

You already have GitHub workflows from the template configured to publish your actions to your repository releases.
For automated releases, we use GH CLI, and we have a simple script that publishes a changelog to the repository releases:

#!/usr/bin/env bash
previous_tag=0
for current_tag in $(git tag --sort=-creatordate)
do

if [ "$previous_tag" != 0 ];then
    printf "## Changelog\n"
    git log ${current_tag}...${previous_tag} --pretty=format:'* %h %s' --reverse | grep -v Merge
    printf "\n"
    break
fi
previous_tag=${current_tag}
done

And the GitHub workflow that runs it:

name: 'Release'
on:
  push:
    tags:
      - '*'
permissions:
  contents: write

jobs:
  github:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - run: |
          ./changelog.sh > changelog.md
          gh release create ${GITHUB_REF##*/} -F changelog.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For Azure Pipelines task releases, you can use the official approach from Azure. Still, also you can do the same on GitHub actions infrastructure as their publisher tool can be installed anywhere. So, in our case, it's solved by a simple GitHub workflow job:

  azure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set Node.js 12.x
        uses: actions/setup-node@v3.6.0
        with:
          node-version: 12.x
      - name: Install dependencies
        run: npm ci && cd vsts/QodanaScan && npm ci && npm i -g tfx-cli
      - name: Package and publish
        run: |
          cd vsts && npm run azure
          mv JetBrains.qodana-*.vsix qodana.vsix
          tfx extension publish --publisher JetBrains --vsix qodana.vsix -t $AZURE_TOKEN
        env:
          AZURE_TOKEN: ${{ secrets.AZURE_TOKEN }}

With this set up, each release happens automatically on each tag push.

git tag -a v1.0.0 -m "v1.0.0" && git push origin v1.0.0

CircleCI?

Ah, yes, this article mentioned the CircleCI orb also... CircleCI setup is straightforward but does not support TypeScript extensions, so you have to pack your code into a Docker image or a binary and run it there. The only reason it's included in this post is that we build our orb with the monorepo approach, which works well.

Just implement the official orb template and place it in your monorepo, so the structure looks like this:

...
├── action.yaml
├── github/
├── azure/
├── src/            # orb source code here
└── package.json

And don't forget to commit .circleci/ directory to your repository to make CircleCI lint, test, and publish your orb.

If this post gets ten reactions here, I'll add a second part about publishing and testing Azure Pipelines and CircleCI orbs

Announcing the Preview for Qodana Cloud, a One-Stop-Shop for All Your Code Quality Insights!

Viktor Tiulpin — Thu, 08 Dec 2022 13:20:36 +0000

A public preview is now open for Qodana Cloud – a centralized cloud-based solution that collects and displays data from different Qodana linters under one roof. You can use Qodana Cloud to manage your code quality checks in a variety of contexts, ranging from one-person projects to large development teams.

Qodana Cloud is still in development, and to iron out some wrinkles we are calling for the support of the community. If you want to become an early adopter of our new features, read on to learn how to get started with Qodana Cloud.

TRY QODANA CLOUD

How Qodana Cloud can complement your projects

Do you want to run static analysis in multiple projects or repositories? Is your codebase distributed across several servers and virtual private networks? Do your teams work independently, and are they not always on the same page when it comes to code quality? In any of these scenarios, if you wanted to ensure that your code is clean and secure, you previously would need to switch between different linters or Qodana instances to see the results for different projects.

The need to switch between linters can make the code review process convoluted and inefficient, and we’ve developed Qodana Cloud to address precisely this problem. Qodana Cloud collects all the data from different Qodana linters in a single place and allows you to drill down into particular issues with interactive dashboards.

Here is how you can benefit from Qodana Cloud:

Get deeper insights into your projects’ trends

With the ability to aggregate reports from different sources in one view, you can discover trends and patterns in your code across all projects and get a better understanding of how your project or the whole team is performing. This way, developers will no longer code in silos, instead seeing the same list of issues. This also makes it easier for managers to track progress for the whole organization.

You can create separate organizations, teams, and projects in Qodana Cloud and assign a single team to several projects for convenient navigation. In addition, you achieve more transparency thanks to widgets updating in real time.

In each project, you can also see a history of previous results and compare the results of quality checks between commits. You can examine the absolute number of problems detected or compare the number of problems against a baseline – a snapshot of the codebase problems taken during a specific Qodana run.

Open problems detected by Qodana in your favorite IDE

If you are already a Qodana user, you might know that you can open issues spotted by Qodana right in your IDE. And now this feature works for Qodana Cloud, too! This means you can fix server-side errors in the editor the same way you work with other suggestions given by the IDE.

Here’s how it works:

What’s especially important about Qodana being bundled with JetBrains IDEs is that you run resource-intensive checks outside of your development environment without hurting your IDE’s performance. In the example above, Qodana spotted a chance that a variable could be null and cause a runtime exception. This is a severe issue, but users tend to switch off such inspections for the sake of saving resources.

In fact, that’s one of the reasons why we at JetBrains created Qodana, to ensure that you no longer have to choose between code quality and IDE performance!

Plan your work better

Split big projects into small steps! Switching to a newer version of a language or framework, or getting rid of a certain utility or pattern, can be a cumbersome task – especially if you are working on a big project involving many developers and QA engineers.

In Qodana Cloud, you can build a report to evaluate all pieces of code requiring modification and select issues to add to the baseline – otherwise known as the technical debt section. This way, the whole team can see the same list of issues and monitor progress with an interactive Qodana dashboard.

Choose the dark or the light side

In the design world, dark mode is the new black. Who are we to ignore that? To ensure you have a good experience with Qodana Cloud, we’ve provided the option to manually choose the dark or the light theme or have the UI sync automatically with your system preferences.

What’s coming next?

In future releases, we will add role-based access control so that you can grant different permissions based on a user’s responsibilities. For example, perhaps your legal team only needs the ability to view reports about licenses used in a product, or your security team needs to see a list of vulnerabilities in the codebase. You will be able to create custom roles for them with permissions that are specific to their tasks. We are also working on implementing more security controls and allowing quick-fixes for certain types of issues.

A sneak peek of what’s coming next in Qodana Cloud.

How to get started with Qodana Cloud

To get started, go to qodana.cloud and log in with your JetBrains Account. Alternatively, as a non-registered user, you can explore demo projects that were already analyzed by Qodana Cloud to see it in action.

To pull your inspection reports from other Qodana instances into the cloud, Qodana Cloud will generate a token for you to set into your project in your CI tool. For detailed instructions, see our documentation.

Project setup

Setting up a project in Qodana Cloud takes five simple steps:

Trigger the first run. First, Qodana analyzes your project using vital checks only. It will identify the number of files and folders containing problems, the languages used, and other important info about your project.
Customize your analysis. Next, Qodana offers you the option to enable extra inspections that might be critical for your analysis.
Narrow the analysis down. You can then exclude certain files and folders from the analysis.
Create technical debt. Our favorite part is the ability to add detected problems to the baseline, allowing you to get back to them when you have time.
Apply the inspections throughout the project. To apply the selected settings to your project, download qodana.yaml and qodana.sarif.json, put them in the root folder, and restart Qodana.

That’s all for now! If you have any suggestions for future blog topics or if you want to learn more about how Qodana can help you and your business, post a comment here, tag us on Twitter, or contact us at qodana-support@jetbrains.com.

Happy developing, and keep your code clean!

Qodana 2022.3 EAP Is Out: Qodana for .NET and Go and 100+ New Inspections

Viktor Tiulpin — Wed, 02 Nov 2022 11:22:28 +0000

We’re delighted to announce the release of Qodana 2022.3 EAP. This version of the platform brings support for NET. and Go, and over 100 new inspections for cleaner code. However, please, note that Qodana 2022.2 images are more stable, as Qodana 2022.3 EAP is still in its infancy.

Read on to learn more and become an early adopter of some exciting new features!

GET STARTED WITH QODANA

Our brand new linters bring all of the smarts from Rider and GoLand to enable you to spot anomalous code and potential bugs, eliminate dead code, improve the overall code structure, and introduce coding best practices across all of your .NET and Go projects!

Qodana for .NET

Qodana supports almost all .NET inspections provided by Rider. Since there’s a long list of them, check out the Rider documentation to learn more about all of the inspections. Meanwhile, a few examples of the .NET inspections that Qodana can run are below.

Inconsistent lock ordering

One of the main issues when using locks to achieve thread safety is avoiding deadlocks, i.e. when threads simultaneously block each other from continuing execution, so no progress is made. With this new inspection, Qodana will highlight cycles leading to possible deadlocks at runtime.

Access to modified captured variable

Qodana for .NET detects access to the captured variable from an anonymous method when the variable is modified externally.

Avoid using ‘async’ lambda when delegate type returns ‘void’

This inspection spots the usage of ‘async’ lambda expressions: any exceptions unhandled by the lambda will never affect the caller thread and will not be caught with the catch clause.

Type check and casts can be merged

The type-testing is operator in its classical form (Expression is Type) returns true only when the runtime type of Expression is compatible with Type and the result of Expression is not null.

When we use is to check the compatibility before casting, like in the example below, we encounter at least two problems:

We perform the type check twice for no reason, which can affect performance if we do it inside a loop.
The fact that the program execution will not get into the if statement if obj is null is not immediately clear to those who read this code.

Qodana will spot this issue and suggest you fix it right in Rider.

Lambda expression/anonymous method should not have captures of the containing context

The lambda expression/anonymous method passed to a parameter annotated by the ‘[RequireStaticDelegate]’ attribute must not have captures of the containing context (local variables, local functions, ‘this’ reference) to avoid heap allocations.

To configure the linter for .NET and run analysis, please refer to the Qodana documentation.

Qodana for Go

Qodana 2022.3 is designed to support all inspections provided by GoLand. To see the exhaustive list, please refer to the GoLand documentation. Below are examples of some of the Go inspections that Qodana now supports.

Placeholder argument ‘d.DeletedCount’ has the wrong type ‘int64’ (%s)

This inspection reports incorrect usages of fmt.Printf, fmt.Println, and similar formatting and printing functions.

In their format strings, formatting functions use formatting verbs, like %s, %d, %v, and others.

If formatting verbs are used incorrectly, the result of a formatting function will contain an error.

Unhandled error

This inspection reports calls to functions and methods that do not handle the call result of the error type.

An API of such functions imply that their execution might finish unsuccessfully and they would return an error. Calls that do not handle the error result could be an indication of misuse of the API.

Unused dependency

This inspection reports unused dependencies on your project. It’s good practice to scan for unused dependencies on a regular basis, as it reduces the library size of your project and improves maintainability.

To see Qodana in action and play around with these new inspections, feel free to jump into our documentation and see how to configure linters for Go.

New inspections

Besides adding new linters for .NET and Go, Qodana 2022.3 also brings you over 100 new inspections for the existing linters. Let’s take a look at the most prominent examples of inspections for Java, Kotlin, and Python.

Java and Kotlin inspections

We’ve added over 40 new inspections to Qodana for JVM Community and Qodana for JVM.

DataFlowIssue

This inspection reports code constructs that always violate nullability contracts, may throw exceptions, or are redundant, based on data flow analysis.

EscapedSpace

Java 15 introduced the string escape sequence \s to make trailing whitespace in text-blocks visible. In most other contexts, especially in regular expressions, this escape sequence can easily be confused with the \s of a regular expression meaning whitespace. In Java string literals it has to be written as "\\s" instead.

MismatchedJavadocCode

This inspection reports cases in which the Javadoc of a method obviously contradicts the method signature, such as the comment saying “returns true” when the method returns a string.

Destructure

This inspection reports declarations in Kotlin that can be destructured.

UnresolvedRestParam

Now Qodana can detect inconsistent method declarations in REST services (such as @PathParam parameters that don’t match a placeholder from the @Getannotation), as these would throw exceptions at runtime.

ReactiveStreamsThrowInOperator

This new inspection spots throw statements in Reactor/RxJava operator code instead of returning designated error values, which prevents the errors from being processed further. For example, it ignores them or replaces them with a fallback value.

Please, note that this version of Qodana also brings all of the new inspections for Android from IntelliJ IDEA 2022.3 and Android Studio – Electric Eel | 2022.1.1.

Python inspections

We’ve also added some inspections for the Google App Engine to Qodana for Python that will highlight issues before they cause failures in production environments. For example, now you can spot:

GQL queries that do not comply with restrictions for queries allowed on the Google App Engine server.
GQL queries without indexes.
Usages of Python features that are restricted by the Google App Engine sandbox.
Сases when threadsafe is not enabled with the CGI handler.

To exclude certain inspections from your analysis, you can customize your default inspection profile or create a brand new one. You may also want to enforce inspections that are important to your coding guidelines. Check out our Qodana documentation for more information.

That’s everything about Qodana 2022.3 EAP! We hope you enjoy this new release. If you have any suggestions for future blog topics or if you want to learn more about how Qodana can help you and your business, post a comment here, tag us on Twitter, or contact us at qodana-support@jetbrains.com.

Happy developing and keep your code clean!

Your Qodana team

Qodana 2022.2 Is Available: 50+ New Inspections and CircleCI Orb

Viktor Tiulpin — Fri, 05 Aug 2022 15:12:57 +0000

Qodana 2022.2 is now available, bringing new and improved code inspections for Java, Kotlin, Android, PHP, JS, and Python. Additionally, we’ve added CircleCI Orb to the Qodana integration toolset.

GET STARTED WITH QODANA

More CIs to run Qodana with

Qodana already has plugins for Azure Pipelines, GitHub Actions, and TeamCity. Starting from 2022.2, we’ve prepared a CircleCI Qodana orb that allows you to set up code inspections quickly and easily with your CircleCI projects.

Also, it’s easy to set up Qodana in GitLab, Jenkins, or any other CI that supports running Docker images.

New inspections

Regular expressions

Regular expressions are widely known for their complexity, intricate syntax, and sometimes verbosity. To make life easier, we’ve added new inspections in this area. Previously these inspections were available only for Java, but we’ve now made them available for all languages.

Simplified regular expressions

A regular expression like [\wa-z\d] can be simplified to just \w since \w already includes a-z as well as the digits. It helps improve the code’s overall readability.

Suspicious backreferences

A regular expression like \1(abc) cannot match anything. This is because the \1 refers to the abc that is not yet defined when evaluating the \1. This inspection prevents simple typos in regular expressions and speeds up the editing experience.

Redundant `\d`, `[:digit:]`, or `\D` class elements

The regular expression [\w+\d] can be written as [\w+], as the \w already includes the \d. It helps improve the code’s overall readability.

Markdown support

Incorrectly numbered list items

Ordered list items like 1. 2. 4. are marked as being inconsistently numbered. In the rendered Markdown, the list is still displayed as 1. 2. 3., but the inconsistency makes editing the source code harder.

Java, Kotlin, and Android inspections

We’ve added and reorganized inspections in the categories: Javadoc, DevKit, Markdown, Kotlin language, style, architectural patterns, performance, and JUnit support. Here are a couple of examples from the JUnit set.

JUnit: Malformed Declaration

Reports the JUnit test member declarations that are malformed and are likely not to be recognized by the JUnit test framework. Declarations like these could result in unexecuted tests or lifecycle methods.

JUnit: Unconstructable TestCase

Reports JUnit test cases that can’t be constructed because they have an invalid constructor. Test cases like these will not be picked up by the JUnit test runner and will therefore not execute.

Those examples you can see live on our public TeamCity instance. Please use the Guest login to enter. Other inspections are described in our documentation.

PHP inspections

We added inspections in Probable bugs, Documentation, Style, Testing, and Laravel categories, for example:

Probable bug: Number ranges mismatch

In a function that is declared with returns int<0,10>, marks return statements that return a number outside this range. Similarly for fields, field constructors and function calls.

Documentation: Type tag without variable name

The PHPDoc snippet @param string is redundant as it doesn’t say what is a string. It should be either removed or replaced with @param string $argument, saying that argument is a string.

Blade: Parse error due to unpaired parentheses in string literals

Early detection of unpaired parentheses in string literals that are later parsed by Blade, a template engine.

To include or exclude certain inspections from your analysis, you can customize your default inspection profile or create a brand new one. You may also want to enforce inspections that are important to your coding guidelines or best practices. Check out our Qodana documentation for more information.

If you have any suggestions for future blog topics or if you want to learn more about how Qodana can help you and your business, post a comment here, tag us on Twitter, or contact us at qodana-support@jetbrains.com.

Your Qodana team

Better Late Than Never, or New Year’s Resolutions with Qodana

Viktor Tiulpin — Tue, 28 Dec 2021 12:00:00 +0000

Even before we started to work on Qodana, we knew from our own experience and user interviews that it’s hard to add static analysis to a project, which leads people to postpone this decision.

// Detect dark theme var iframe = document.getElementById('tweet-1475799581434781699-996'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1475799581434781699&theme=dark" }

If you join a project with established code quality procedures, you can just follow the rules. If you start a shiny new project, you can pick any set of rules you want. This option has its pitfalls, but at least you know that your code meets your own standards from the beginning.

In contrast, if you join or work for a project where quality gates are not yet part of the process, being pressured to implement them could be a heartbreaking experience! We’ve felt it ourselves, and heard from many users who opened up in interviews: implementing the appropriate gateways can be a bumpy road.

Most people we talked to encountered issues with the following:

Figuring out what kind of rules to apply
Determining what to do with the existing issues
Identifying how to make all of this sustainable

Our goal with Qodana has always been to provide a pleasant experience for those who decide to have quality gates, and we’ve developed two new features to further this goal:

Project setup wizard, which lets you tailor your analysis configuration further based on the initial results.
Technical debt (or baseline), which lets you mark a given state of the project as initial and track further changes.

If you have been thinking about using quality gates for your project but haven’t known where to start, this post is right for you. You don’t need to wait until the first week of January to adopt your New Year’s resolution: you can get started now, and make your life in the new year easier.

Start with a local run and create a baseline

Let’s start with your local machine. If you use a JetBrains IDE and are familiar with code inspection profiles, you can re-use them in your Qodana run. If you are unsure of what server-side analysis fits your project best, you can start with Qodana’s default options. We introduced three-phase analysis precisely for this case.

Follow these steps to run Qodana on your project:

Pick the proper Qodana linter for your project’s technology stack and pull its image:

docker pull jetbrains/qodana-<linter>

Options include qodana-jvm, qodana-jvm-android, qodana-php, and so on.

Perform the first run:

docker run --rm -it -p 8080:8080 \
  -v <project-root-directory>/:/data/project/ \
  jetbrains/qodana-<linter> --show-report

Your project’s working folder likely has all the required dependencies in place, so you don’t need to perform any additional steps for the analysis to succeed. In cases when you’ve just cloned the repository and haven’t previously worked in the editor on this machine, depending on the project technology, either Qodana will do everything on its own or you will need to take one extra step to download project dependencies. For more details about this step, please check out the corresponding section in our documentation.

After the analysis is complete, you will see an invitation to check the results. Open Qodana UI in your browser using this link: http://localhost:8080.

You will see a page that looks like the example below.

During this first run, Qodana analyzes your project using vital checks only. Non-vital checks and folders containing non-vital code, such as the Tests folder, are ignored. Qodana also reports any conditions that could affect the truthfulness or completeness of the results. For example, if your project relies on external resources or generated code that is unavailable during the analysis, the final results could be compromised. Qodana notifies you about such suspicious results. We encourage you to follow the guidance during project setup and tune the configuration. After the first run, everything you need will be at hand. You can review every problem in the left-hand panel, and you will see immediately how your adjustments affect the number of issues you need to work on.

Our favorite step is the third one – putting all the detected problems into a baseline.

Why put everything in a technical debt (baseline)? Well, bringing the number of problems in your code down to zero is quite simple, really: first, fix all existing issues; second, ensure no new problems appear over time. The second part may be easier than the first one, and by using the baseline, we set the current project state as the initial one and only track new issues that appear.

The last step in the project setup is downloading two files: qodana.yaml and qodana.sarif.json. Just place them into your project folder, and be sure to copy the suggested Docker command.

A local run with the baseline enabled

Now return to your console and run Qodana again using this command:

docker run --rm -it -p 8080:8080 \
  -v <project-root-directory>:/data/project \
  jetbrains/qodana-<linter> --show-report \ 
  --baseline=baseline.sarif.json

Please ensure you use the proper Docker image name.

You will see something similar to the example below. Qodana now treats all of the previously discovered issues as the baseline and does not report them again.

Add even more checks

At this point, you are ready for the next step – setting the quality gate in your CI. If you want to get started with that right away, feel free to jump right to the Quality gate section of this post.

But if you are feeling adventurous, you can examine the suggestions Qodana prepared for you, and perhaps enable even more checks. Use the Problem examples dialog to see the checks we suggest, as well as some examples in your codebase that need improvement according to those rules. If you find them appropriate, turn them on, download the updated qodana.yaml file to the project root folder, and run Qodana locally again to perform the same triage using even more checks.

You can repeat the previous steps again and again, thereby tailoring your configuration further.

When you are happy with what you see locally – it’s time to set a quality gate for your CI pipeline.

Quality gate for the CI pipeline

One good thing about Qodana is that you can add it to any CI platform. But since it would be hard to cover all integration-related nuances in a single blog post, we will describe its integration with GitHub Actions. The process of setting up quality gates is very similar in all other CI platforms, too, with the exception of TeamCity. In TeamCity, we would suggest you use our dedicated plugin.

So, if you use GitHub Actions as your main CI platform, follow these steps to set up quality gates:

Add qodana.yaml and qodana.sarif.json to your VCS. If you find qodana.sarif.json is too big to be placed in your VCS, you can store it anywhere it is accessible for your GitHub Actions.
Add the Qodana GitHub Action to your workflow by following the instructions in our documentation.
Set the workflow to run on pull_request events that target the main branch.

on:
  pull_request:
    branches:
    - main

Add the fail-threshold option with a value of 0 to the Qodana Action, as well as branch protection rules to any branch you want to protect. We suggest starting with the main branch.

For more information about branch protection rules, refer to the GitHub Documentation.

Now you are all set! Your changes will be checked by Qodana so they will meet your standards. You can use this action as a proper quality gate. For example, you can check incoming pull requests and merge only those whose quality is up to your standards. If your most common scenario involves developing in branches, you can add this action to make sure the whole branch is checked before being merged into the main branch. Actually, you can include a Qodana Action in any part of your pipeline and use the produced artifacts and resulting exit code as the basis for further decisions.

And if, like us, you like making New Year’s resolutions, you can make a plan to work on the issues from the baseline one step at a time in 2022. Qodana UI will help you plan out this work, e.g. you can choose issues to be fixed by category, or folder, or just one-by-one.

When you reach zero issues in the actual list and the baseline, it will be time to go to the ‘next level’. You can turn to Qodana’s suggestions for inspiration, or study the whole list of checks to add more of them to your profile.

By the way, Qodana is extensible: you can create your own checks. We will cover this topic in a dedicated blogpost at the beginning of next year.

Try it now and improve your code

Check out the website to download the version of the components that’s suitable for your technology stack. Some of them have already reached stable releases, and some are available under an Early Access Program (EAP). Don’t wait to set yourself up to meet your code quality goals in the new year. Future you will thank you!

Feedback

We would be grateful for any feedback you have, and all ideas are welcome! Contact us at qodana-support@jetbrains.com or via our issue tracker.

Your JetBrains Qodana Team

The Drive to Develop

Forem: Viktor Tiulpin

Develop, test, and deploy your extensions for all popular CIs from a single codebase

Start from the official templates

Pros for using JS-based actions:

Cons

GitHub Actions

Azure Pipelines

Create the monorepo

Share code between actions and tasks

Build and publish

CircleCI?

Announcing the Preview for Qodana Cloud, a One-Stop-Shop for All Your Code Quality Insights!

How Qodana Cloud can complement your projects

Get deeper insights into your projects’ trends

Open problems detected by Qodana in your favorite IDE

Plan your work better

Choose the dark or the light side

What’s coming next?

How to get started with Qodana Cloud

Project setup

Qodana 2022.3 EAP Is Out: Qodana for .NET and Go and 100+ New Inspections

Qodana for .NET

Qodana for Go

New inspections

Java and Kotlin inspections

Python inspections

Qodana 2022.2 Is Available: 50+ New Inspections and CircleCI Orb

More CIs to run Qodana with

New inspections

Regular expressions

Simplified regular expressions

Suspicious backreferences

Redundant \d, [:digit:], or \D class elements

Markdown support

Incorrectly numbered list items

Java, Kotlin, and Android inspections

JUnit: Malformed Declaration

JUnit: Unconstructable TestCase

PHP inspections

Probable bug: Number ranges mismatch

Documentation: Type tag without variable name

Blade: Parse error due to unpaired parentheses in string literals

Better Late Than Never, or New Year’s Resolutions with Qodana

Start with a local run and create a baseline

A local run with the baseline enabled

Add even more checks

Quality gate for the CI pipeline

Try it now and improve your code

Feedback

Redundant `\d`, `[:digit:]`, or `\D` class elements