Documentation
Get Started
GitLab CI

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.

Prerequisites

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 npm install).

3. Choose your initial 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

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

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 api scope:

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

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 main branch.

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 x-optic-url?
  • Is the Optic workflow being triggered in CI?
  • Is there an OPTIC_TOKEN and OPTIC_GITLAB_TOKEN set and is it visible to the GitLab pipeline?

What's next?

Congratulations, Optic is now set up to track all changes and run automated checks against every API change.

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

GitHub CIFastify