Optic makes it easy to check and/or enforce your API standards in CI. There are two main options for doing this:
- Run the open source CLI in one of your CI pipelines
- Optic Cloud can discover all the OpenAPI specifications in your repos. You can use the dashboard to set the standards and workflows for each one.
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.
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
optic.dev.yml file in each project where you want the tool to run. There are detailed instructions here.
Consideration #1 Sequential runs
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.
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.
- Optic listens to your GitHub/GitLab webhooks (like a CI provider)
- 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.
- Optic runs your linting/diff checks on our infrastructure, then posts back via the Checks API.