# GitHub Action

Source: https://apigenie.pl/techdocs/reference/cli-github-action

The API Genie GitHub Action installs the CLI on GitHub Actions runners and
lints, checks the formatting of, or diffs OpenAPI, Swagger 2.0, AsyncAPI,
Protobuf and GraphQL files. Issues and changes are shown as annotations on the
files of a pull request, and a report is added to the job summary. The action
is published on the GitHub Marketplace as `mykulyak/api-genie-action`; its
source and its releases are in
[mykulyak/api-genie-action](https://github.com/mykulyak/api-genie-action).

## Usage

```yaml
on: pull_request
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mykulyak/api-genie-action@v0
        with:
          command: lint
          files: api/**/*.yaml
          config: apigenie.yaml
      - uses: mykulyak/api-genie-action@v0
        with:
          command: format
          files: api/**/*.yaml
      - uses: mykulyak/api-genie-action@v0
        with:
          command: diff
          files: api/openapi.yaml
```

- `lint` fails the step when an issue of severity `error` is reported (see
  [lint](/techdocs/reference/cli-lint#exit-status)).
- `format` runs `apigenie format --check`: nothing is written, and the step
  fails when a file is not formatted.
- `diff` compares each file with its version at the base commit of the pull
  request, or the commit before a push, and fails the step on breaking
  changes. Set `base` to compare with another commit, branch or tag, or
  `base-file` to compare two files of the repository.
- Without `command`, the action only installs `apigenie` and puts it on
  `PATH`, for the steps that follow.

## Inputs

| Input | Description |
| ----- | ----------- |
| `version` | CLI version: `latest` (default), `X.Y.Z` or `cli-X.Y.Z`. 0.9.0 is the oldest supported version. |
| `command` | `lint`, `format` or `diff`. |
| `files` | Files, one per line or separated by spaces. Glob patterns such as `api/**/*.yaml` are expanded. |
| `config` | The [configuration file](/techdocs/reference/cli-configuration). |
| `formatter` | Formatter of `lint` and `diff`. Only the default, `unix`, becomes annotations. |
| `report` | Report of `diff`: `status`, `changelog` (default) or `detailed`. |
| `fail-on` | `error` (default), `warning` (lint warnings fail the step too) or `never`. |
| `base`, `base-file` | What `diff` compares with. |
| `args` | More arguments for the command, separated by spaces. |
| `annotations`, `summary` | Turn the annotations or the job summary off with `false`. |

## Outputs

| Output | Description |
| ------ | ----------- |
| `status` | `lint`: `clean`, `warnings` or `errors`. `format`: `clean` or `changed`. `diff`: `none`, `non-breaking` or `breaking`. |
| `exit-code` | The exit status of the CLI. |
| `error-count`, `warning-count` | The numbers of lint errors and warnings. |
| `changed-files` | The files that are not formatted. |
| `version`, `path` | The installed CLI and its location. |

## Runners

The action runs on Linux x64, macOS arm64 and Windows x64 runners. It
downloads the CLI from the GitHub release, checks it against the release's
checksums, and reuses it in later steps of the same job.