# GitLab CI

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

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](/docs/ci) 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](https://github.com/mykulyak/api-genie/issues),
makes it checked.

## The pipeline

```yaml
# .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](https://docs.gitlab.com/ci/pipelines/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:

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