# Jenkins

Source: https://apigenie.pl/docs/ci/jenkins

A `Jenkinsfile` that lints, checks the formatting of and compares an OpenAPI file in every pull
request of a multibranch pipeline, as one stage per check: each has its own status on the build,
and the Warnings plugin shows the lint issues. [Any CI system](/docs/ci) explains the pieces: the
commands, the reports, the installation and the comparison with the target branch.

**Unchecked.** The file follows the Jenkins documentation and has not run on a Jenkins. A run on
one, passed or failed, reported in an [issue](https://github.com/mykulyak/api-genie/issues), makes
it checked.

## The pipeline

The agent needs `curl`, `tar` and `git`; the CLI comes from the release archive, checked against
its checksum, into the workspace. The [Warnings](https://plugins.jenkins.io/warnings-ng/) plugin
reads the Checkstyle report, and a multibranch pipeline with a branch source for GitHub, GitLab or
Bitbucket builds the pull requests, with `CHANGE_TARGET` as the target branch.

```groovy
// Jenkinsfile
pipeline {
  agent any
  environment {
    VERSION = '0.10.0'
  }
  stages {
    stage('Install') {
      steps {
        sh '''
          curl -fsSLO "https://github.com/mykulyak/api-genie/releases/download/cli-$VERSION/apigenie-$VERSION-linux-x64.tar.gz"
          curl -fsSLO "https://github.com/mykulyak/api-genie/releases/download/cli-$VERSION/apigenie-$VERSION-linux-x64.tar.gz.sha256"
          sha256sum -c "apigenie-$VERSION-linux-x64.tar.gz.sha256"
          tar xzf "apigenie-$VERSION-linux-x64.tar.gz" apigenie
        '''
      }
    }
    stage('Lint') {
      steps {
        catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
          sh './apigenie lint --formatter checkstyle api/openapi.yaml > lint.xml'
        }
      }
      post {
        always {
          recordIssues tools: [checkStyle(pattern: 'lint.xml')]
        }
      }
    }
    stage('Format') {
      steps {
        catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
          sh './apigenie format --check api/openapi.yaml'
        }
      }
    }
    stage('Diff') {
      when { changeRequest() }
      steps {
        sh '''
          git fetch --depth=1 origin "$CHANGE_TARGET"
          git show FETCH_HEAD:api/openapi.yaml > base.yaml
          ./apigenie diff base.yaml api/openapi.yaml
        '''
      }
    }
  }
}
```

`catchError` marks the stage and the build as failed and goes on to the next stage, so the build
shows all three results; the last stage fails the build on its own. `when { changeRequest() }`
runs the comparison for pull requests only, where `CHANGE_TARGET` is set.

## What the pull request shows

- The status of the build on the pull request, set by the branch source plugin, and the stages
  with their status on the build page.
- The *Checkstyle Warnings* view of the build, from the Warnings plugin: each lint issue with its
  file, line, severity and rule, and the trend across builds. The plugin reads the SARIF report as
  well, with `sarif(pattern: 'lint.sarif')` and `--formatter sarif`; the
  [JUnit](https://plugins.jenkins.io/junit/) plugin shows `--formatter junit` as failed tests, with
  `junit 'lint.xml'` in place of `recordIssues`.
- The logs of the stages: the files that would change, and the changes with their severity.