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 theproject
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 theText
report, and display it to the standard output. This is suitable for CI. If you want other reports, for exampleAmbassador
, add them here, one by line. All the reports are available in the Manualproject_themes
is an array that contains the expected rule sets. By default, Exakat will run theAnalyze
. 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 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 theproject
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 theText
, and output it to the standard output. This is suitable for CI. If you want other reports, for exampleAmbassador
, add them here, one by line. All the reports are available in the Manualproject_themes
is an array that contains the expected rule sets. By default, Exakat will run theAnalyze
. 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 theMy_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 theExakatYaml
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 :
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
- 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 releaseexakat.phar project
: This command launch the analyse base on the.exakat.ini
or.exakat.yaml
config file. By the way, all the options of theproject
command keep allowed.
Then launch a build …
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.