Add Exakat To Your CI Pipeline

The Continuous Integration pipeline builds your code automatically, and runs a large number of checks. When those checks fail, the build of the application is cancelled, and the development team have a change to square everything again.

With more consistent checks, continuous integration leads to higher code quality. Exakat is a natural part of the CI pipeline : it automates highly sophisticated code reviews, and report them directly to the CI.

To integrate Exakat in your CI pipeline, Exakat has to be configured with a .exakat.ini or .exakat.yml file. These files configure the engine with the requested rules to pass over the code. Put one of them at th root of your repository, next to composer.json, for example.

With this set up, Exakat may be used in gitlab, bitbucket, travis-ci, jenkins, circleci.

Configuring Exakat For CI

Traditionally, Exakat manages all code and audits in separate folders, all put away in projects. Each folder contains the configuration file, called config.ini, the last audits and various temporary files, used for analysing and auditing the code. There is also the ‘code’ repository, which hosts the code itself. This way, Exakat always kept code and audits separated, so as to keep the source code intact.

When running Exakat for a CI, such organization is not pragmatic. Usually, only the code folder is available, and there is little access to anything else. The audit and its configuration have to happen in the same folder.

To run Exakat directly from the code folder, there must be at least one configuration file. There are two options for this file : either .exakat.ini, or .exakat.yaml. The first one is simpler to set up and has precedence over the YAML version, but also has more limited features. The Yaml version is very similar, and provides more features. It is recommended to set up the INI first, then move to the YAML version when advanced features are needed.

.exakat.ini

‘.exakat.ini’ is the alter ego of the ‘config.ini’, that is produced with the traditional Exakat installation. It uses the INI file format. You have to put it at the root of the code source. It is recommended storing it in the VCS repository.

Your code repository may look like this :

.exakat.yml
.git
.gitignore
/app
/src
/web
composer.json   
...

Here is a simple configuration file :

project      = 'angie-project';
project_name = 'angie, the audit'

project_reports[] = 'Text';

project_ruleset[] = 'Security';

project : This is the name of the project. Use a simple yet telling name, with letters, figures, underscores and dash. This is compulsory. It is used internally, by exakat, for identification.
project_name : this is the name used when building reports. It has fewer constraints than the project entry, and in case any special character is used, enclose the name in quotes. This is compulsory. You will find it in audits, as the title of HTML pages, for example.
project_reports is an array that contains the expected reports. By default, Exakat will produce the Text report, and display it to the standard output. This is suitable for CI. If you want other reports, for example Ambassador, add them here, one by line. All the reports are available in the Manual
project_themes is an array that contains the expected rule sets. By default, Exakat will run the Analyze. If you want more analysis to be run, Security, add them here, one by line. All the standard Exakat rule sets are available in the Manual. It is not possible to configure a customized rule set with the .exakat.ini configuration file.

Once the configuration file is stored, at the root of the code repository, you may call the doctorcommand to check the installation.

cd /path/to/code
php /path/to/exakat.phar doctor

Note that this command has no option -p. If all is well configured, it is not necessary. In fact, there should be a section describing the project, with the project name.

/// More lines before this section
project : 
    name                 : angie, the audit
    url                  : 
    phpversion           : 7.3
    reports              : Text
    themas               : Security
    included dirs        : 
    ignored dirs         : /test, /tests, /Tests, /Test, /example, /examples, /docs, /doc, /tmp, /version, /vendor, /js, /lang, /data, /css, /cache, /vendor, /assets, /spec, /sql
    file extensions      : php, php3, inc, tpl, phtml, tmpl, phps, ctp, module
/// More lines after this section

In particular, the .exakat.ini file may be ignored, fully or partially, if it is not a valid .INI file. When nothing appears in the project section, check your syntax.

.exakat.yaml

.exakat.yaml offers a higher level of configuration than the .exakat.ini file. It is based on the YAML format, and the same directive as the previous configuration file.

Note than when both .exakat.ini and .exakat.yaml are provided, Exakat selects first the .exakat.ini file, unless it cannot be parsed.

Here is an example of configuration, using YAML and the same values as the previous section :

project: angie-project
project_name: angie, the audit
project_reports:
    - Text
project_themes:
    - Security
ignore_dirs:
  - /assets
  - /vendor
  - /var
  - /web
rulesets:
    My_Rules: 
         "Adding Zero": Structures/AddZero
         "Multiply By One": Structures/MultiplyByOne
         "Concat Empty String": Structures/ConcatEmpty
    My_Rules2:  [Structures/AddZero, Structures/MultiplyByOne, Structures/ConcatEmpty]

project : This is the name of the project. Use a simple yet telling name, with letters, figures, underscores and dash. This is compulsory. It is used internally, by exakat, for identification.
project_name : this is the name used when building reports. It has fewer constraints than the project entry, and in case any special character is used, enclose the name in quotes. This is compulsory. You will find it in audits, as the title of HTML pages, for example.
project_reports is an array that contains the expected reports. By default, Exakat will produce the Text, and output it to the standard output. This is suitable for CI. If you want other reports, for example Ambassador, add them here, one by line. All the reports are available in the Manual
project_themes is an array that contains the expected rule sets. By default, Exakat will run the Analyze. If you want more analysis to be run, Security, add them here, one by line. All the standard Exakat rule sets are available in the Manual. It is not possible to configure a customized rule set in this file.
rulesets is an array of rule sets. Each ruleset is defined by its unique name, and a list of analysis to run. Here, you can findd the My_Rules rule set, which contains three analyses. Each analysis is configured with an optional property name, and its analysis identifiers. The property name is optional, as long as it is unique. The property names used in this example were produced with the ExakatYaml report, and include both the human readable title for the configured analysis, and their analysis identifier. Only the analysis identifier is used during execution, and the property names are here for documentation.

Analysis identifiers are available in the online Manual, and they all have a distinct name. You will also find them in the documentation.

Testing Exakat Like CI

direct installation

The direct installation is the same as previously, whatever the usage of Exakat. You can find the Installation instruction in the manual. Let’s assume that the path of the installation of Exakat is /usr/local/sbin, and that the Gremlin database is functional.

After having configured Exakat as mentioned in the previous sections, you can do the following :

> cd /path/to/code
> php /usr/local/sbin/exakat.phar project

Exakat finds the .exakat.* file, and runs the audit, and displays the result in stdout or in the same folder.

docker usage

Exakat runs also with a docker container. First, pull the image :

docker pull exakat/exakat:latest

Once the image is downloaded, and the configuration file ready, you can use the following command :

> cd /path/to/code
> docker run -it --rm -w /src -v $(pwd):/src --entrypoint "/usr/src/exakat/exakat.phar" exakat/exakat:latest project

Exakat finds the .exakat.* file, and runs the audit, and displays the result in stdout or in the same folder.

Configuring Exakat for various CI

In the following section, we’ll describe how to configure exakat to run on the following Continuous Integration systems :

gitlab
bitbucket
travis-ci
jenkins
circleci

If your favorite CI system is not available, check if some of the instructions below are not applicable. You may also join the Exakat slack

Configuring Exakat for Gitlab CI

Gitlab runs its CI pipeline, and take advantage of docker containers. Here is an exakat stage for your .gitlab-ci.yml file.

stages:
  - lint
  - exakat
  - build
  - test

exakat:
  stage: exakat
  image: exakat/exakat:latest
  script:
    - exakat project

The stages list may include any other stage. The exakat stage is based on the Exakat Docker image, and it is publicly available. It is updated with every new version.

The Exakat binary is already configured in this container : the invocation is very short. If any issue is spotted, Exakat exits with code 1, and displays the found issues. If no issue was spotted, Exakat exits with 0, and displays nothing.

Configuring Exakat for Bitbucket Cloud

Bitbucket Cloud runs its CI pipeline, and take advantages of docker container. Here is an exakat step for your bitbucket-pipelines.yml file.

image: exakat/exakat:latest

pipelines:
  default:
    - step:
       script: 
        - echo 'I start Exakat's Code Review'
        - exakat project

The steps may include any other step to be processed in your CI. The exakat step is based on the Exakat Docker image, and it is publicly available. It is updated with every new version.

The Exakat binary is already configured in this container : the invocation is very short. If any issue is spotted, Exakat exits with code 1, and displays their issue found. If no issue was spotted, Exakat exits with 0, and no display.

The config file used is .exakat.ini or .exakat.yaml located at the root of your path/to/code.

Configuring Exakat for Travis-ci

Travis-ci works with docker images, with a service aptly named docker and one line of installation.

language: php

services:
  - docker

before_install:
  - docker pull exakat/exakat:latest

script:
  - docker run -it --rm -w /src -v $(pwd):/src --entrypoint "/usr/src/exakat/exakat.phar" exakat/exakat:latest  project

The docker command is long, and quite standard. -w sets the working directory, to be the source directory. The src directory is set as the current directory, and then exakat is called with the command project. Then, the .exakat.yml or .exakat.ini is used.

Configuring Exakat for Jenkins

Jenkins is another popular CI server where the use case is to run your CI process inside your own infrastructure to avoid to expose your very secret code on the Cloud.

Our use case is based to the following approach :

Jenkins is installed on premise on your server
- See : https://jenkins.io/download/
Exakat is installed on premise on the same server
- See the Installation for more details to install Exakat Engine on your server
The .exakat.ini or .exakat.yaml config file is located in your /path/to/code repository

In your Jenkins project, Build section :

add a new step to your build
select the Execute shell script on remote host using ssh step type
define the following command lines

cd /path/to/exakat
php exakat.phar upgrade -u
cd /path/to/code
php /var/www/exakat/exakat.phar project

exakat.phar upgrade -u : This command update Exakat Engine to the latest release
exakat.phar project : This command launch the analyse base on the .exakat.ini or .exakat.yaml config file. By the way, all the options of the project command keep allowed.

Then launch a build …

Exakat results in Console Output with Jenkins

Configuring Exakat for CircleCI

Circleci requires a .circleci/config.yml. The following code is a job that runs Exakat on the code. You have to add this job to your workflow to make it run.

version: 2.0

jobs:
  exakat:
    docker:
      - image: exakat/exakat:latest
    steps:
    - checkout
    - run:
        command: exakat project

Customize Your Coding Reference

Including Exakat in your CI is a great way to monitor closely your code. Adding the .exakat.yml file allows you to configure the analysis to run, and the CI will apply systematically the checks before the code is pushed to production.

There are standard list of analysis, available in Exakat : Security, Performances, Migration 7.4, Classreview, etc. They are ready to use, and require no configuration.

With experience, you’ll find important to tailor that list to meet your local standard. Some analysis are important for your code base, but others are less critical, and may be omitted reasonably. For that, use the rule set configuration, and build your list incrementally. You may also take a look at the ‘ExakatYaml‘ report, which lists the analysis that yielded no results in the previous audit : this is a good start to make a selection.

Want to Keep in touch with us, subscribe to our newsletter !

Technology

Add Exakat To Your CI Pipeline

Add Exakat To Your CI Pipeline

Configuring Exakat For CI

.exakat.ini

.exakat.yaml

Testing Exakat Like CI

direct installation

docker usage

Configuring Exakat for various CI

Configuring Exakat for Gitlab CI

Configuring Exakat for Bitbucket Cloud

Configuring Exakat for Travis-ci

Configuring Exakat for Jenkins

Configuring Exakat for CircleCI

Customize Your Coding Reference

Login