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.yml

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.

optic.yml

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.

.github/workflows/optic.yml

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

Need Help? Set up office hours with the Optic team (opens in a new tab)

Run in CI Setting API Standards