Skip to main content

Installing GitHub App

Pre-requisites​

Before getting started, ensure you have the following:

  • Repository Permissions: You must have the appropriate permissions to install the app on your GitHub repository. If you're a member of an organization, the organization owner must approve the installation.
  • APIMatic Account: You need a free APIMatic account. Create one at APIMatic.

Getting Started​

Step 1: Install the App​

  1. Please contact support@apimatic.io to install the app.

  2. Choose the GitHub account or organization where you want to install the app.

  3. Select the repositories where you want the app to run.

  4. Authorize the app with your APIMatic account (you will be automatically redirected to APIMatic's login page). Do not close the page until the authorization is successful.

    Installation Completed

note

If you're installing on an organization, the organization owner must approve the installation.

Installation Requested

Step 2: Configure the App​

Once installed, you need to configure the app by creating a .apimaticsettings.json configuration file in the root directory of your repository.

Required Configuration​

In the .apimaticsettings.json file, define the paths to your OpenAPI definitions. Here's an example:

{
  "OpenAPIDefinitionPaths": [
    "path/to/openapi/directory",
    "path/to/openapi.yaml",
    "path/to/openapi.json"
  ]
}

This configuration tells the linter where to find your OpenAPI definitions.

Optional Configuration​

If you have branch protection rules that prevent merging PRs with failing checks, you can disable the GitHub checks by adding the following to your configuration file:

{
  "IgnoreValidationErrors": true
}
note

IgnoreValidationErrors is set to false by default, meaning GitHub checks will fail on validation errors. You can override this behavior by setting IgnoreValidationErrors to true.

How It Works​

After installation and configuration, the APIMatic OpenAPI Linter GitHub App automatically triggers validation for every pull request (PR) created or updated. The app validates the OpenAPI definitions in the PR according to the paths specified in the .apimaticsettings.json configuration file.

Validation Process​

  1. When a PR is created or synchronized, the app runs the validation process in the background.
  2. The results are displayed in the PR Comment section.
  3. If validation passes, the PR can be merged. If validation fails, the PR will be blocked from merging (unless you do not have branch protection rules enabled or you opt to skip validation with IgnoreValidationErrors set to true).

Customizing Validation​

APIMatic's OpenAPI Linter uses a highly configurable validation engine, allowing you to configure the checks based on your needs.

Example of Custom Rule Configuration​

{
    "Id": "my-custom-ruleset",
    "Rules": [
        {
            "Id": "max-operation-id-length-30",
            "VerificationMethod": "Length",
            "Targets": [
                {
                    "JsonPath": "$.paths.*.*.operationId"
                }
            ],
            "VerificationMethodArgs": {
                "Maximum": 30
            },
            "Message": "Operation id is too long."
        }
    ]
}

This example shows how to enable a custom rule with specific parameters.

Troubleshooting​

Common Issues​

  1. Unauthorized Installation: Make sure the GitHub app is installed correctly on the desired repositories and that the APIMatic account is properly linked.

  2. Missing Configuration File: Ensure that .apimaticsettings.json is present in the root of your repository.

  3. Invalid Configuration File: Ensure that the file is syntactically correct and that its content is accessible.

  4. Incorrect OpenAPI Paths: Double-check the file paths in your configuration file to ensure they are correct.

  5. Failed Checks: If validation fails, check the PR comments or the detailed audit report for more information on which rules failed.

For any further questions or support, visit our Support Page.