Setup Optic in CI for generated specs
Optic tracks every API change by integrating into your CI pipelines and checking for breaking changes and other issues with the design every time the API changes. The goal is to prevent any problematic API changes from landing in production, while keeping your internal documentation up-to-date at all times.
This guide focuses on integrating Optic with generated specs. This usually means you have a script that you can run that creates an OpenAPI file from your code, and the OpenAPI file might not be committed to Git. If you are interested in using a generated spec workflow, we have guides for different frameworks in our adopt OpenAPI section.
Optic usually uses git
refs to compare two versions of a spec. Since generated specs aren't usually checked into Git history, we have to either store the base spec (either in Git or in Optic Cloud) or generate both versions of the spec from the two different Git instances.
By setting up Optic Cloud, Optic will compare changes on pull requests between your branch's generated spec and the spec from your repo's default branch.
You can also set this up manually by either committing the generated spec every time it changes, or by checking out and generating both versions of your spec.
1. Set up Optic in CI
Generate CI scripts
In the repo where you have your OpenAPI specs, run the following command.
optic ci setup
This will prompt you with a couple of questions such as what CI provider do you use and whether you use a script to generate your specs. You should answer yes
if you use a script to generate your OpenAPI specs. You will also be prompted to give a command that creates a spec and also the path that your OpenAPI spec is generated at.
$ optic ci setup
✔ What CI provider would you like to configure? › GitHub Actions
✔ Should failing standards fail CI? › Yes - Recommended
✔ Do you use a script to generate your OpenAPI specs? › Yes
✔ The script or command you use to generate your specs (ex: generate.sh) … yarn run generate-spec
✔ Path to your OpenAPI spec files (examples: "first-spec.yml,second-spec.yml" or "**/spec.yml") … ./specs/openapi.yml
✔ Wrote GitHub CI configuration to .github/workflows/optic.yml
Once you've committed the generated file, come back here to choose your API standards and configure commenting on pull requests.
Optic uses the location of your spec in the Git repository to identify it between different commits. As long as you don't move or rename the specification Optic will continue to compute history correctly. If you want to move your specification add an x-optic-url extension so Optic can keep track of it.
You can get the x-optic-url
from Optic Cloud by visiting https://app.useoptic.com (opens in a new tab) and clicking your API. The URL of the API is the x-optic-url
(and should look something like this: https://app.useoptic.com/organizations/{yourOrgId}/apis/{yourApiId}
).
openapi: 3.1.3
...
x-optic-url: https://app.useoptic.com/organizations/{yourOrgId}/apis/{yourApiId}
info:
title: my spec
version: 1.0.0
Choose your API standards
Create an optic.yml
file at the root of your repo and copy the ruleset below and commit this file.
ruleset:
- breaking-changes
Check the standards documentation for a detailed view of Optic capabilities.
Configure commenting on Pull Requests
Optic adds a summary of API changes and automated checks on pull requests when there is something to report. Don't worry, Optic only comments when there's something meaningful! We won't comment when there aren't API changes.

In GitHub navigate to Repo > Settings > Actions > General
and set Workflow permissions
to Read and write permissions
.

2. Log into your Optic Cloud account
Next, log into Optic Cloud in your CLI by running the following command. You will be able to create an account if you do not already have one
optic login
> optic login
Generate a token below
Create an account and generate a personal access token at https://app.useoptic.com/user-settings/personal-access-token/new
✔ Enter your token here: … ***********************************************************************************************************
Verifying your token
Successfully saved your personal access token to /Users/user/.config/optic/config.json
3. Turn on cloud
Finally, turn on Optic Cloud in your CI pipeline by adding an Optic token.
Start by generating an organization access token by visiting our app (opens in a new tab).
Once you have generated a token, set the token in the CI script
Set this token as a GitHub Actions Secret for your project (opens in a new tab). You can do this on GitHub's UI or with their gh
CLI:
gh secret set OPTIC_TOKEN
Then update the GitHub action workflow set the optic_token
input to ${{ secrets.OPTIC_TOKEN }}
. You should have this already set in your generated .github/workflows/optic.yml
file.
jobs:
diff-all:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- uses: opticdev/action@v1
with:
# Your Optic Cloud Token
optic_token: ${{ secrets.OPTIC_TOKEN }}
...
4. Trigger Optic
Now that we've set up everything, it's time to test out the entire flow! Ensure that all the changes in the previous steps have been merged into your main
branch.
Make some changes
Start by making a pull request and making a couple of changes to your API. Below are some suggestions of changes:
- remove an endpoint
- remove a field from a response body
- add a required query parameter to an endpoint
Notice anything about these changes? These are breaking changes that Optic is designed to prevent!
See how Optic works
Once you open your PR, Optic will diff changes between the default branch (typically main
) and the pull request's branch, commenting once complete with:
- the results of any automated checks
- a link to preview your documentation (Optic cloud only)
- a link to the proposed changes in the PR (Optic cloud only)
Troubleshooting
Didn't get a pull request comment from Optic or something didn't quite work right? Here's some common troubleshooting steps:
- is the Optic workflow being triggered in CI?
- does the workflow have the
Read and write permissions
enabled? - did you add the OpenAPI file you changed to the
--match
option in the generated CI file from step 1?
What's next?
Congratulations! Optic is now set up to track changes and run automated checks against every API change. As OpenAPI changes are merged into your default branch you'll notice Optic tracking every version and reporting statistics like the number of added, changed, or removed endpoints, breaking changes, and more.
Here are some other things you can do with Optic Cloud