# GitHub Action

Our GitHub Action drops into your repository to establish best practices and
continuous quality monitoring for your OpenAPI definitions.

## Usage

Add the GitHub Action to your repository and configure it to run on pull
requests and pushes for continuous quality monitoring.

### Getting an API key

The GitHub Action calls the Rate My OpenAPI API, which requires an API key.
[Subscribe to the free plan](https://docs.ratemyopenapi.com/pricing) (free
forever) to register or log in — your API key is created automatically. Copy
it from your dashboard and store it as a repository secret
(e.g. `RMOA_API_KEY`).

:::warning{title="New API keys required"}
On May 12, 2026, Rate My OpenAPI switched to a new registration system. API
keys created before that date no longer work. Subscribing again issues a new
key automatically.
:::

### Basic setup

Lint an OpenAPI definition file using the default configuration:

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: zuplo/rmoa-action@v1
    with:
      filepath: './my-api.json'
      apikey: ${{ secrets.RMOA_API_KEY }}
```

### Advanced setup

Override the minimum passing score (default 80 / 100) and cap the allowed
warnings and errors:

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: zuplo/rmoa-action@v1
    with:
      filepath: './my-api.json'
      apikey: ${{ secrets.RMOA_API_KEY }}
      max-errors: 0
      max-warnings: 5
      minimum-score: 70
```

**Configuration options**

```yaml
- uses: zuplo/rmoa-action@v1
  with:
    # File containing the OpenAPI Spec to be linted.  Examples: my-api.oas.json, api-spec.yaml
    filepath: ''

    # Your Rate My OpenAPI API key (https://docs.ratemyopenapi.com/pricing)
    apikey: ''

    # The maximum number of warnings allowed before labeling the run as failed.
    max-warnings: ''

    # The maximum number of errors allowed before labeling the run as failed.
    max-errors: ''

    # The minimum score (0 - 100) to label a lint run as successful/passing. Default is 80.
    minimum-score: ''
```

### Example

This workflow runs `rmoa-action` on every pull request. The pull request cannot
be merged until the OpenAPI specification in `my-api.json` reaches a minimum
score of 80.

```yaml
on:
  pull_request:
    branches: [$default-branch]

jobs:
  rate-my-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: zuplo/rmoa-action@v1
        with:
          filepath: './my-api.json'
          apikey: ${{ secrets.RMOA_API_KEY }}
```

:::warning{title="Reports are public"}
All reports generated by Rate My OpenAPI are public (with an unguessable UUID
URL), even when uploaded with an API key. Anyone with the URL to your report
can access it.
:::

Source code and documentation at [zuplo/rmoa-action](https://github.com/zuplo/rmoa-action).