Skip to main content

Running in CI pipelines

Optic makes it easy to check and/or enforce your API standards in CI. There are two main options for doing this:

This guide will explain the nuances of running optic diff in your CI Pipelines manually. If you have dozens or hundreds of specifications or have specifications spread over many repos you probably are at a scale where Optic Cloud makes sense in the long run.

Run optic diff in CI

The simplest way to run the standards is to run the optic diff command in your CI pipeline, just as you run it locally. You will need to include the file in each project where you want the tool to run. There are detailed instructions here.

Consideration #1 Sequential runs

The optic diff tool exits 1 if there are any issues. If you run optic diff commands sequentially the first spec to fail will prevent the following ones from running. You can write a bash loop that stores the exit codes if you want all of your checks to run sequentially.

Consideration #2 Fetch Depth & Merge

optic diff uses git's database to compare changes across branches. Many CI tools do shallow clones in their runners for performance reasons. You will likely need to fetch the branch you are merging into before running Optic. We also suggest performing a merge and comparing the merged version to the branch the PR is targeting. That way the changelog always shows the effective API change if the branch is merged.

Consideration #2 Network access

If any of your OpenAPI files reference external $ref references loaded over HTTP, you will need to give the CI runner access to those hostnames or the resolve step of the diff will fail.

Need help?

We invite you to book office hours if you need any help. Someone on our team can answer questions and help write an Optic CI task.

The easy way

Getting your API linters and other tools to run in every team's CI pipelines can be a huge bottleneck. Coordinating with each team's CI engineers can be expensive and time-consuming. If you ever want to change the standards or tooling you may have to do all that work again. Optic Cloud was built to make this easy.

Instantly deploy and change API Standards

Optic Cloud lets your team configure the API Standards for each team from a central dashboard. You do not need to add any code to the repositories or write any CI tasks. It just works.

  1. Optic listens to your GitHub/GitLab webhooks (like a CI provider)
  2. When OpenAPI files change, it pulls the specs from Git[Hub/Lab]'s API. We do not clone the repos for security reasons, we only look at specs.
  3. Optic runs your linting/diff checks on our infrastructure, then posts back via the Checks API.