Setup Optic in GitLab 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 GitLab pipeline 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"
Copy the token to the Project or Group settings for your project (opens in a new tab). The generated pipeline expects you to name this variable
5. Configure commenting on Merge Requests
Optic adds a summary of API changes and automated checks on merge 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 order to post a comment, you will need to give the Optic Pipeline a Group Access Token, or a Project Access Token, or a Personal Access Token with the
We strongly recommend using a Group Access Token (opens in a new tab) because:
- it is what GitLab recommends
- comments will come from a group bot, not your personal account
- the same token can be used across all the projects in a group
Optic runs when your OpenAPI specs change so you will want it to run on temporary feature branches. Uncheck the option to
Export variable to pipelines running on protected branches and tags only when creating the token. The generated pipeline expects you to name this variable
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 merge 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 merge 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 merge 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_GITLAB_TOKENset and is it visible to the GitLab pipeline?
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