This article was originally published on[the SpecShield blog]. I'm a co-founder of SpecShield, one of the migration targets discussed below — full disclosure upfront. The post tries to be honest about where SpecShield fits and where other tools fit better.
TL;DR
- Optic's GitHub repo was
archived on January 12, 2026. Last release:v1.0.9 in August 2025. The
useoptic.com
domain no longer resolves.- Optic was acquired by Atlassian in April 2024but was never folded into Atlassian Compass.- The MIT-licensed source is still on GitHub, but abandoned— no security patches, no new rules, no support, and your CI will eventually break when a transitive dependency goes EOL.- If you used Optic primarily for spec-to-spec diffing and breaking-change checks in CI, the most direct migration path is to(Web UI + CLI + GitHub App + free GitHub Action) or[SpecShield](open-source CLI, no UI).[oasdiff]- If you used Optic for OpenAPI generation from test traffic— there is no direct replacement. You'll need to change workflow.- Below: a feature-by-feature comparison table, a step-by-step migration walkthrough, and an honest list of what's hard to replace.
What actually happened to Optic #
For the last six years, Optic was the open-source default for OpenAPI breaking-change detection. It had what most developer-tool startups don't: a clean CLI, a sensible rule system, MIT licensing, deep CI integration, and a small but devoted community.
Here's the timeline of how it ended:
| Date | Event |
|---|---|
| April 2024 | |
| Atlassian acquires Optic Labs. Optic team joins Atlassian. | |
| April 2024 – August 2025 | |
| Release cadence slows. Most commits become dependency bumps. Issues pile up unanswered. | |
| August 10, 2025 | |
| Final release: v1.0.9. No release notes hint that it's the last. | |
| August 2025 – January 2026 | |
| Silence. No releases, no maintainer responses. The community asks "is Optic still maintained?" — no official answer. | |
| January 12, 2026 | |
The opticdev/optic GitHub repo is archived (made read-only). The useoptic.com domain stops resolving shortly after. |
There was no formal sunset announcement, no migration guide from the Optic team, no archived-but-here's-a-fork blessing. It just stopped.
The expectation in the community after the Atlassian acquisition was that Optic would become part of Atlassian Compass — Atlassian's developer-experience product. That integration never shipped. As of May 2026, Compass remains focused on service catalogs and DORA metrics, with no API drift detection capability.
The 1.5k-star repo has 92 forks, but no fork has emerged as a community successor. If you keep depending on @useoptic/optic
from npm, you're depending on unmaintained code that will eventually break when its TypeScript / Node / npm peer dependencies hit EOL.
You need to migrate. The good news: this is a four-hour job for most teams, not a four-week project.
What you actually used Optic for (and what you'll need to replace) #
Optic had five distinct capabilities. Different teams used different subsets. Identify which ones applied to you before picking a replacement — choosing wrong is the single biggest migration mistake.
1. Spec-to-spec diffing and breaking-change detection
The most common use case. You had openapi.yaml
in your repo, you ran optic diff
in CI on every PR, and the action commented on the PR with breaking-change warnings.
Replacement difficulty: Easy. Multiple drop-in alternatives exist.
2. OpenAPI rule-based linting
Optic had its own ruleset format (.optic.dev.yml
) for things like "all paths must be kebab-case" or "every endpoint needs a description".
Replacement difficulty: Medium. You'll switch to Spectral, which is the de-facto standard for OpenAPI linting and has a much larger ecosystem of rulesets. Your custom rules will need to be re-expressed in Spectral's format.
3. OpenAPI generation from captured traffic (optic capture
)
This was Optic's most novel feature. You'd run your test suite with the Optic proxy in front of it, and Optic would generate (or update) the OpenAPI spec from observed traffic.
Replacement difficulty: Hard. There is no direct open-source replacement with the same maturity. Alternatives include:
Pollyjs(record/replay HTTP, generic) - Speakeasy(different workflow — spec drives SDK, not traffic drives spec) - Hand-maintaining the OpenAPI spec (which is what most teams end up doing)
If you relied heavily on optic capture
, your migration is more painful than spec-diff users. Plan accordingly.
4. CI integration via GitHub Action
The useoptic/optic-action
GitHub Action posted PR comments with diff results.
Replacement difficulty: Easy. Several drop-in alternatives exist with similar or better PR comment design.
5. Hosted UI for browsing diffs and history
Optic Cloud (the SaaS layer) gave you a web UI to browse diffs across releases and share them with non-developer stakeholders.
Replacement difficulty: Medium. The hosted UI tools available today either cost more (Bump.sh, Stoplight) or look less polished. SpecShield's web UI is a direct equivalent in scope and is in active development.
Your migration options at a glance #
Honest comparison of the realistic alternatives, as of May 2026:
| Tool | What it replaces | Pricing | Hosted UI | OSS engine | PR comments | Active development |
|---|---|---|---|---|---|---|
| Optic's spec-diff, breaking-change detection, hosted UI, CI integration, BDCT (bonus) | Free tier; paid from $29/mo | ✅ Yes | Closed core, free GitHub Action coming | ✅ Yes (GitHub App + Action) | ✅ Active | |
| Spec-diff and breaking-change detection (CLI only) | Free / OSS (Apache 2.0) | ❌ No | ✅ Yes (Go) | ✅ Via official GitHub Action | ✅ Active | |
| Optic's linting (not diffing) | Free / OSS (Apache 2.0) | ❌ No | ✅ Yes (TS) | Via custom integration | Active but slower post-SmartBear acquisition | |
| Hosted docs + changelog (a different workflow than Optic's CI flow) | From $50/mo | ✅ Yes | ❌ No | ❌ No native PR comments | ✅ Active | |
| Linting + diff (basic) | Free CLI; paid platform | ✅ Yes (paid) | Partial OSS | Via custom integration | ✅ Active |
Three patterns will cover ~95% of Optic migrations:
You used Optic for spec-diff in CI + you want a UI→** SpecShield**(most direct replacement, smallest mental model shift) - You used Optic for spec-diff in CI + you don't need a UI→** oasdiff**(CLI-only, Apache 2.0, will outlive any SaaS company) - You used Optic for linting→** Spectral**(regardless of which diff tool you pick)
The rest of this post focuses on path #1, because it's the most common and the least documented. If you're on path #2 or #3, the official docs for oasdiff and Spectral are excellent and you don't need a migration guide.
Why SpecShield is the most direct replacement for Optic users #
I built SpecShield specifically for the spec-first, CI-driven workflow Optic championed. The mental model is identical:
- You commit your OpenAPI spec to git
- On every PR, the new spec is compared to the base branch
- Breaking changes are flagged before merge
- You get a beautiful diff report (in the UI, the CLI, andas a PR comment)
What's the same as Optic:
- OpenAPI 3.0 and 3.1 support
- Multi-file spec support (with
$ref
) - Breaking-change classification (removed paths, type changes, new required fields, etc.)
- CI/CD integration via GitHub App and (soon) free GitHub Action
- CLI distributed via npm (
npx specshield compare ...
)
What's better than Optic:
Bi-Directional Contract Testing (BDCT)— verify provider/consumer compatibility, with acan-i-deploy
gate. Optic never had this. - Compatibility matrix for multi-service architectures - Beautiful, screenshot-worthy PR comments(Optic's were utilitarian) - Active development— we ship roughly weekly - Free tier with no time limit (Optic Cloud's free tier was always limited)
What's different (some teams will see these as downgrades):
- SpecShield is a SaaS product with a free tier. Optic was BYO-infrastructure if you stayed on the open-source CLI.
- The core diff engine isn't open-source today (the free GitHub Action will be, when it ships later in 2026).
- We're a smaller team than Optic was at its peak — though we ship faster.
If you're moving primarily because Optic stopped getting maintained and you want something that will be maintained, those tradeoffs probably work in your favor. If you fundamentally need OSS-or-nothing, see oasdiff.
Step-by-step migration: Optic → SpecShield #
Here's the actual migration for a team that was using Optic's CLI and GitHub Action. Expect this to take 30–60 minutes end-to-end, including PR review time.
Step 0 — Audit what you're currently using
Before deleting anything, find every place Optic is referenced in your repo:
find . -name ".optic.dev.yml" -o -name "optic.yml" -o -name ".optic*"
grep -rE "useoptic/optic-action|optic diff|optic lint" .github/
grep -rE "@useoptic/optic|optic capture|optic verify" package.json scripts/
grep -ri "optic" README.md docs/ 2>/dev/null
Make a checklist of every file you found. You'll touch each one.
Step 1 — Install the SpecShield CLI
The SpecShield CLI is published to npm as specshield
. You don't need to globally install it — npx
is fine for CI:
npx specshield compare old-openapi.yaml new-openapi.yaml
You'll see output that includes the same categories Optic produced (breaking, non-breaking, additions), formatted as a clean terminal table.
If you want JSON output for CI scripting, use the --json
flag (with --output
to also write to a file):
npx specshield compare old.yaml new.yaml --json --output diff.json
The JSON shape is:
{
"summary": { "breaking": 3, "additions": 12, "modifications": 7, "warnings": 0 },
"breakingChanges": [...],
"additions": [...],
"modifications": [...],
"warnings": [...]
}
Step 2 — Replace your Optic GitHub workflow
If you had something like this .github/workflows/api-check.yml
:
name: API contract check
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: useoptic/optic-action@v1
with:
spec: openapi.yaml
base_ref: ${{ github.event.pull_request.base.ref }}
Replace it with this:
name: API contract check
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Extract base spec from base branch
run: git show origin/${{ github.event.pull_request.base.ref }}:openapi.yaml > /tmp/base.yaml
- name: Compare specs
id: compare
continue-on-error: true
run: |
{
echo '## 🛡️ SpecShield · API contract check'
echo ''
echo '```
{% endraw %}
'
npx specshield compare /tmp/base.yaml openapi.yaml --fail-on-breaking
echo '
{% raw %}
```'
} > /tmp/comment.md
- name: Comment on PR
if: always()
uses: marocchino/sticky-pull-request-comment@v2
with:
path: /tmp/comment.md
- name: Fail the build if breaking changes were found
if: steps.compare.outcome == 'failure'
run: exit 1
A few notes on this pattern:
- The CLI auto-disables ANSI color codes when not running in a TTY, so the output inside the fenced code block renders cleanly on GitHub.
continue-on-error: true
on the compare step lets the PR comment post even when breaking changes are detected. The final step then fails the build explicitly so PR checks still gate the merge. -
marocchino/sticky-pull-request-comment
updates the existing comment in place on subsequent commits rather than spamming the PR. - A dedicated SpecShield Action (in development) will render a richer markdown comment with a color-coded summary table and collapsible per-endpoint diffs. Until that ships, the fenced-code-block approach above is the cleanest path.
Step 3 — Migrate your custom rules (if you had any)
This is the step that takes the longest if you'd customized Optic's rule engine. Optic rules looked like this:
ruleset:
- breaking-changes
- examples
- name: kebab-case-paths
where:
operation: { in: any }
rule:
after: must
assert: |
operation.path.split('/').every(s => /^[a-z0-9-]*$/.test(s))
SpecShield doesn't currently expose a Spectral-compatible custom rule API. For now:
Breaking-change rules: covered by SpecShield's built-in detector — no migration needed - Style/lint rules(kebab-case paths, required descriptions, etc.): migrate these to a separate Spectral step in your CI:
- name: OpenAPI lint
run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml
With a .spectral.yaml
like:
extends: spectral:oas
rules:
paths-kebab-case:
description: Paths should be kebab-case
given: $.paths.*~
severity: warn
then:
function: pattern
functionOptions:
match: ^(\/[a-z0-9-]*)+$
We're working on first-class custom-rule support in SpecShield. Until then, the two-step approach above is the cleanest path.
Step 4 — Remove Optic dependencies
Once your new workflow is green:
npm uninstall @useoptic/optic
rm .optic.dev.yml
rm .github/workflows/optic-check.yml
Commit the migration as a single PR — easier to review, easier to revert if anything's off.
Step 5 — Set up the dashboard (optional but recommended)
If you want history, team collaboration, BDCT, and a can-i-deploy
gate beyond the per-PR diff:
- Sign up free at specshield.io - Install the SpecShield GitHub App on your repo
- Your existing CLI runs will automatically appear in your dashboard's compare history
No re-configuration needed — the GitHub App and CLI write to the same backend.
What SpecShield does NOT replace from Optic (being honest) #
Three Optic capabilities don't have a clean SpecShield replacement today. If you depended on these, you need a plan.
1. optic capture
— generating specs from traffic
No direct replacement in SpecShield. Our model assumes you maintain the spec by hand (or generate it from code via a framework annotation library). If optic capture
was central to your workflow, evaluate:
- Continuing to use Optic's archived
capture
command standalone (it'll keep working for a while — it's not network-dependent) - Replacing with Pollyjsfor record/replay - Switching to a spec-first workflow (which is where the industry has moved, for what it's worth)
optic capture
-style functionality is on our roadmap but isn't shipping in 2026.
2. The MIT-licensed core
Optic's diff engine was MIT. SpecShield's core engine is closed-source as of May 2026. The free GitHub Action will be Apache 2.0 when it ships, but the engine behind the hosted product is proprietary.
If "must be fully open-source" is a non-negotiable requirement, use oasdiff — it's the most mature open-source option and is unaffected by Optic's shutdown.
3. The exact ruleset format
Optic's rule DSL is unique. Your rules don't port 1:1 to anything. You'll re-author them in either:
- SpecShield's built-in rules (which cover ~80% of the common cases by default)
- Spectral's rule DSL (for the remaining 20% of custom style rules)
Plan ~1 hour per custom rule for the rewrite.
When SpecShield is NOT the right migration target #
Honest recommendations for the cases where another tool is better:
| Your situation | Recommended migration target |
|---|---|
| "I just want a CLI that does breaking-change detection, no SaaS" | |
| oasdiff. It will outlive every SaaS in this list. | |
| "We had thousands of dollars of Optic Cloud customization and need a high-touch enterprise vendor" | |
| Bump.sh or Stoplight for documentation | |
| "We need OpenAPI capture from traffic" | Stay on Optic's archived CLI for now; Speakeasy if you can shift to spec-first |
| "We need OpenAPI linting and nothing else" | |
| Spectral (standalone, free) | |
| "We want a fully self-hosted option with no cloud component" | |
| oasdiff + Spectral, both run on your own infra | |
| "We're a microservice org with consumer/provider contracts" | |
| SpecShield (has BDCT built in) or PactFlow (the dedicated Pact-broker SaaS) |
The honest read on the post-Optic landscape: there's no single tool that covers everything Optic did. Most teams will end up with two tools in their pipeline — one for diff/breaking-change detection, one for linting — where they had one before.
What we learned from Optic's end #
A few takeaways worth sitting with, especially if you build or pay for developer tools:
OSS + VC is a fragile combination. Optic raised funding, was acquired, and shut down within a typical VC fund lifecycle. The OSS code still exists but nobody is paid to maintain it. If a tool is mission-critical to your CI, weight its funding model and sustainabilityalong withits features.Acquisition isn't continuity."Acquired by [BigCo]" sounds reassuring at the time. It almost never is. Plan for the acquired tool to be gone within 18 months unless its product roadmap is publicly aligned with the acquirer's stated direction.Spec-first won. Optic's bet was that you should auto-generate specs from traffic. The industry consensus has moved the other way — the spec is the source of truth, code and tests are generated from it. That shift is part of why the spec-from-capture approach didn't become indispensable.Beauty matters. Optic's PR comments were functional but plain. The tools that have taken its place (and the ones that will replace whatever replaces them) compete heavily on UI/UX. Engineers screenshot and share comments that look good. That's distribution.
Migrate today, not next quarter #
Three reasons to do this migration now, not after your next release:
Optic's npm package will eventually break.@useoptic/optic
depends on TypeScript, Node, and dozens of transitive packages, several of which will hit EOL within 12 months. When that happens, your CI will silently start failing in ways that are hard to debug because the underlying tool is unmaintained.Your team is forgetting Optic's quirks. The longer you wait, the harder the migration. The engineer who set up your Optic workflow may not be at the company in 12 months.The migration is small if you do it now. Most teams can complete the steps above in under an hour. Wait until a CI break forces it, and you'll be doing it in a panic on a Friday afternoon.
Try SpecShield in 5 minutes #
If you've read this far and want to try SpecShield as your Optic replacement:
npx specshield compare old-openapi.yaml new-openapi.yaml
For the dashboard, history, GitHub App, and BDCT: sign up free at specshield.io/signup — no credit card, generous free tier. Pricing details at specshield.io/pricing.
For migration support, email me at founder@specshield.io — happy to help any Optic refugee migrate, gratis, regardless of whether you end up using SpecShield. The migration matters more than the tool.
Was this guide helpful? It's part of a series on the post-Optic API tooling landscape. Next post: a deep technical comparison of the breaking-change rules across SpecShield, oasdiff, and Optic's archived ruleset — including the edge cases each catches that the others miss.
Have feedback or corrections? Drop a comment below or email me directly. I'd rather get this right than get this fast.