GitLab CI

A .gitlab-ci.yml that lints, checks the formatting of and compares an OpenAPI file in every merge request, as three jobs: each has its own status in the merge request, and the lint report feeds the test summary. Any CI system explains the pieces: the commands, the reports, the installation and the comparison with the target branch.

Unchecked. The file follows the GitLab CI documentation and has not run on a project on GitLab. A run on one, passed or failed, reported in an issue, makes it checked.

The pipeline

# .gitlab-ci.yml
.apigenie:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - npm install -g @mykulyak/api-genie

lint:
  extends: .apigenie
  script:
    - apigenie lint --formatter junit api/openapi.yaml > lint.xml
  artifacts:
    when: always
    reports:
      junit: lint.xml

format:
  extends: .apigenie
  script:
    - apigenie format --check api/openapi.yaml

diff:
  extends: .apigenie
  script:
    - git fetch --depth=1 origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - git show FETCH_HEAD:api/openapi.yaml > base.yaml
    - apigenie diff base.yaml api/openapi.yaml

The rules run the jobs in merge request pipelines only, where CI_MERGE_REQUEST_TARGET_BRANCH_NAME names the target branch. artifacts: when: always uploads the lint report when the job fails, which is when the report matters; without it, GitLab keeps the artifacts of successful jobs alone.

What the merge request shows

• The pipeline widget lists the three jobs with their status. A failing job blocks the merge once Pipelines must succeed is on, under Settings > Merge requests.
• The test summary, from the JUnit report of lint, counts the failed tests and lists them: one per issue, named apigenie.<rule>, with the message; warnings are failed tests too, on a job that passed.
• The logs of format and diff: the files that would change, and the changes with their severity.

The Code Quality widget reads the CodeClimate format, which lint does not write, and GitLab has no reader for the SARIF report.

The Docker image

The jobs can run in the mykulyak/apigenie image instead of installing the CLI into node:22. The image’s entry point is apigenie, and a GitLab job needs the shell, so the entry point is cleared; before_script goes:

.apigenie:
  image:
    name: mykulyak/apigenie:0.10.0
    entrypoint: [""]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

The image has git, so the diff job runs in it too.