# CircleCI

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

A `.circleci/config.yml` that lints, checks the formatting of and compares an OpenAPI file on every
push, as one job with a step per check: each has its own status in the job, and the lint report
feeds the Tests tab. [Any CI system](/docs/ci) explains the pieces: the commands, the reports, the
installation and the comparison with the base branch.

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

## The pipeline

```yaml
# .circleci/config.yml
version: 2.1

jobs:
  api:
    docker:
      - image: cimg/node:22.12
    environment:
      BASE: main
    steps:
      - checkout
      - run:
          name: Install API Genie
          command: npm install -g @mykulyak/api-genie
      - run:
          name: Lint
          command: |
            mkdir -p reports
            apigenie lint --formatter junit api/openapi.yaml > reports/lint.xml
      - store_test_results:
          path: reports
      - run:
          name: Check formatting
          when: always
          command: apigenie format --check api/openapi.yaml
      - run:
          name: Breaking changes
          when: always
          command: |
            git fetch --depth=1 origin "$BASE"
            git show FETCH_HEAD:api/openapi.yaml > base.yaml
            apigenie diff base.yaml api/openapi.yaml

workflows:
  api:
    jobs:
      - api
```

CircleCI has no variable for the branch a pull request merges into, so the job compares with
`main`, set in `BASE`; a project that merges into release branches changes it per branch with a
[pipeline value](https://circleci.com/docs/variables/) or asks the provider's API for the pull
request. `when: always` keeps the later `run` steps running after a failed one, so the job shows
all three results; `store_test_results` runs after a failed step on its own, and takes no `when`.
The `cimg/node` image lets `npm install -g` write without `sudo`.

## What the pull request shows

- The status of the job as a check on the pull request, with the steps and their status on the
  job page. A failed step fails the job.
- The Tests tab of the job, from the JUnit report: a failed test per lint issue, named
  `apigenie.<rule>`, with the message; warnings are failed tests too, on a step that passed. The
  failed tests also appear in the insights of the project.
- The output of the steps: the files that would change, and the changes with their severity.