Setup Optic in GitHub CI
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.
- Install the Optic CLI and link your cloud account
- Have an account in Optic Cloud (don't have one yet? Create one here (opens in a new tab))
- Have an OpenAPI spec or a script to generate an OpenAPI spec from your code
- Don't have an OpenAPI spec? Optic can help you generate one
1. Add the APIs you want to track to Optic
Generated specs: If you have a script that generates a spec, you can skip to the next section
Open one of your API projects and run the
add command with an OpenAPI specification:
optic api add specs/account-service-openapi.yml
This will add your API to Optic and start tracking any changes you make to this file.
You will notice that there's an
x-optic-url added to your OpenAPI spec, if you follow this link, you'll be able to see your documentation and any history in Optic's cloud viewer! You should also commit this to your repo.
If you have a lot of OpenAPI specs in a monorepo, you might want to add multiple specs at once. You can always come back and add more specs later so it is ok to skip this step for now.
# list all the detected specs in the current repo optic api list # add these specs to Optic optic api add --all
2. Set up Optic in CI
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.
Once you've completed the prompts, Optic should generate you a file that should run any time your API changes and run breaking change checks. Commit these changes.
Generated specs: The CLI should have generated you a GitHub action file with a placeholder generation script (named
generate-spec.sh). You should replace this command to call your own generation script, along with any other setup it needs to run (like an
3. Choose your initial API standards
optic.yml file at the root of your repo and copy the ruleset below and commit this file.
ruleset: - breaking-changes
4. Add an Optic CI Token to your CI Environment
You will need to provide the ci script running Optic a secret CI token. Navigate to the
Tokens tab in Optic Cloud and click "New"
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 secret set OPTIC_TOKEN
5. 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 if there's something meaningful! (that means we won't post when there aren't any API changes).
In GitHub navigate to
Repo > Settings > Actions > General and set
Workflow permissions to
Read and write permissions.
6. 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
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!
You should notice once you open your PR, Optic will diff changes between the
main branch and the pull request's branch and post a comment once it's completed with:
- A link to preview your documentation
- A link to the proposed changes in the PR
- The results of any automated checks
Didn't get a pull request comment from Optic or something didn't quite work right? Here's some common troubleshooting steps:
- Does the OpenAPI spec have an
- Is the Optic workflow being triggered in CI?
- Is there an
OPTIC_TOKENset in GitHub actions?
- Does the workflow have the
Read and write permissionsenabled?
Congratulations, Optic is now set up to track all changes and run automated checks against every API change.
- View your documentation and history in Optic (opens in a new tab)
- Configure your API standards
- Verify your API documentation against the implementation