---
title: "Add Exakat To Your CI Pipeline"
url: https://www.exakat.io/add-exakat-to-your-ci-pipeline/
date: 2019-06-03
modified: 2019-06-03
author: "dams"
description: "Configure exakat with .exakat.yml, and run it in your CI pipeline."
categories:
  - "Technology"
tags:
  - "CI"
  - "circleci"
  - "gitlab"
  - "jenkins"
  - "pipeline"
  - "travis-ci"
image: https://www.exakat.io/wp-content/uploads/2019/05/pipeline.320.jpg
word_count: 1967
---

# Add Exakat To Your CI Pipeline

# Add Exakat To Your CI Pipeline

![](https://178.62.231.40/wp-content/uploads/2019/05/pipeline.320.jpg)

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`](https://exakat.readthedocs.io/en/latest/Reports.html#text) report, and display it to the standard output. This is suitable for CI. If you want other reports, for example [`Ambassador`](https://exakat.readthedocs.io/en/latest/Reports.html#ambassador), add them here, one by line. All the reports are available in the [Manual](https://exakat.readthedocs.io/en/latest/Reports.html)- `project_themes` is an array that contains the expected rule sets. By default, Exakat will run the [`Analyze`](https://exakat.readthedocs.io/en/latest/Rulesets.html#analyze). If you want more analysis to be run, [`Security`](https://exakat.readthedocs.io/en/latest/Rulesets.html#security), add them here, one by line. All the standard Exakat rule sets are available in the [Manual](https://exakat.readthedocs.io/en/latest/Rulesets.html). 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 `doctor`command 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`](https://exakat.readthedocs.io/en/latest/Reports.html#text), and output it to the standard output. This is suitable for CI. If you want other reports, for example [`Ambassador`](https://exakat.readthedocs.io/en/latest/Reports.html#ambassador), add them here, one by line. All the reports are available in the [Manual](https://exakat.readthedocs.io/en/latest/Reports.html)- `project_themes` is an array that contains the expected rule sets. By default, Exakat will run the [`Analyze`](https://exakat.readthedocs.io/en/latest/Rulesets.html#analyze). If you want more analysis to be run, [`Security`](https://exakat.readthedocs.io/en/latest/Rulesets.html#security), add them here, one by line. All the standard Exakat rule sets are available in the [Manual](https://exakat.readthedocs.io/en/latest/Rulesets.html). 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`](https://exakat.readthedocs.io/en/latest/Reports.html#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](https://exakat.readthedocs.io/en/latest/Rules.html), 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](https://exakat.readthedocs.io/en/latest/Installation.html) 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](https://hub.docker.com/u/exakat). 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](https://178.62.231.40/wp-login.php?action=slack-invitation)

## Configuring Exakat for Gitlab CI

[Gitlab](https://gitlab.com/gitlab-com) 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](https://cloud.docker.com/u/exakat/repository/docker/exakat/exakat) image, and it is publicly available. It is updated with every new version. 

![](https://178.62.231.40/wp-content/uploads/2019/05/gitlab.results-1024x532.png)

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](https://bitbucket.org/product/) 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](https://cloud.docker.com/u/exakat/repository/docker/exakat/exakat) 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. 

![](https://178.62.231.40/wp-content/uploads/2019/05/bitbucket.results.2-1024x511.png)Exakat results at Bitbucket Cloud

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](https://travis-ci.org/) 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

![](https://178.62.231.40/wp-content/uploads/2019/05/travis-ci.results-1024x566.png)Exakat results at Travis-ci.org

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/](https://jenkins.io/download/)- Exakat is installed on premise on the same server See the [Installation](https://exakat.readthedocs.io/en/latest/Installation.html) 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

![](https://178.62.231.40/wp-content/uploads/2019/05/jenkins.config-1024x418.png)Exakat Step in Jenkins Build

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 ...

![](https://178.62.231.40/wp-content/uploads/2019/05/jenkins.results-1024x543.png)Exakat results in Console Output with Jenkins

## Configuring Exakat for CircleCI

[Circleci](https://circleci.com/) 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](https://circleci.com/docs/2.0/config-intro/#section=configuration) 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](https://exakat.readthedocs.io/en/latest/Rulesets.html#security), [Performances](https://exakat.readthedocs.io/en/latest/Rulesets.html#performances), [Migration 7.4](https://exakat.readthedocs.io/en/latest/Rulesets.html#compatibilityphp74), [Classreview](https://exakat.readthedocs.io/en/latest/Rulesets.html#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](https://exakat.readthedocs.io/en/latest/Reports.html#exakatyaml)' report, which lists the analysis that yielded no results in the previous audit : this is a good start to make a selection.