Git integration with Stoplight is like performing surgery with a chainsaw - it works until it doesn't, and when it fails, it takes your afternoon with it.
The YAML Merge Conflict Hell
OpenAPI specs in YAML format turn into unreadable garbage during merge conflicts. Three developers editing the same spec file simultaneously? Prepare for 90 minutes of diff hell.
The Problem: Git's default merge algorithm doesn't understand YAML structure. A simple indentation change makes every line look different:
<<<<<<< HEAD
responses:
'200':
description: Success
content:
application/json:
schema:
=======
responses:
'200':
description: Success
content:
application/json:
schema:
>>>>>>> feature-branch
Best Fix: Use semantic merge tools that understand YAML structure. yq can help resolve conflicts programmatically, and the official YAML specification provides detailed formatting rules for conflict resolution. The Git merge documentation covers advanced merge strategies for complex files:
## Install yq first
brew install yq # macOS
sudo apt-get install yq # Ubuntu
## Merge YAML files with conflict resolution
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml branch.yaml
Prevention Strategy: Use .gitattributes to define custom merge drivers for YAML files. The Git attributes documentation explains merge driver configuration, while Stack Overflow YAML merge discussions provide community solutions for common conflicts:
*.yaml merge=ours
*.yml merge=ours
Team Workflow: Assign spec file ownership. Only one person edits the main OpenAPI file at a time. Everyone else works on separate files and uses $ref to include their changes. The OpenAPI specification documentation covers $ref usage patterns, and JSON Schema external references explain the underlying reference resolution mechanism. Swagger documentation provides practical examples for splitting large specs.
Branch Syncing Issues with Platform
Stoplight's Git sync frequently gets confused by force pushes, branch renames, or when someone rebases without telling anyone.
Symptoms:
- "Your branch is behind" when it's not
- Changes not appearing in platform after push
- Random 404s on docs that worked yesterday
Debug Process:
- Check status.stoplight.io first - platform downtime is more common than they admit
- Verify webhook delivery in your Git provider (GitHub/GitLab/etc)
- Force a manual sync from Stoplight platform settings
Nuclear Reset: Disconnect and reconnect the Git integration:
- Project Settings → Git Integration
- Disconnect repository
- Wait 5 minutes (seriously, their cache is slow)
- Reconnect with same repository URL
- Re-configure branch settings
This loses some project history but fixes 90% of sync issues.
File Path Problems
Stoplight gets confused by repository structures it doesn't expect. If your OpenAPI files aren't in the root directory, prepare for random failures.
Works Fine:
project/
├── api.yaml
└── models/
├── user.yaml
└── product.yaml
Breaks Randomly:
project/
├── docs/
│ └── api/
│ └── openapi.yaml
└── src/
└── models/
Fix: Use explicit file paths in your Stoplight project configuration. Don't rely on auto-discovery.
Relative Path Hell: When using $ref, paths break if you move files around:
## This breaks when you reorganize directories
$ref: '../models/user.yaml#/User'
## This is more resilient
$ref: '#/components/schemas/User'
The "Permission Denied" Mystery
Random authentication failures when Stoplight tries to access your repository, especially with enterprise GitHub/GitLab instances.
Common Causes:
- OAuth token expired (GitHub tokens expire after 1 year)
- Repository permissions changed
- Organization SSO requirements updated
- SmartBear's IP addresses got blocked by your corporate firewall
Fix Process:
- Regenerate Git integration token in your Git provider
- Update token in Stoplight project settings
- Test with a simple commit to verify access
- If still failing, check your network team blocked
*.stoplight.iodomains
Enterprise Gotcha: If your company uses SAML/SSO, the service account used by Stoplight might need special permissions or exemptions. The GitHub Enterprise SSO documentation covers common integration issues, while Azure AD OAuth troubleshooting helps resolve authentication failures with enterprise identity providers.
Performance Issues with Large Repositories
Stoplight chokes on repositories with thousands of files or deep Git history. Symptoms include slow syncing, timeout errors, and random build failures.
Temporary Fix: Use shallow clones by creating a dedicated documentation repository instead of mixing docs with code:
## Create a docs-only repo
git clone --depth 1 https://github.com/stoplightio/elements.git
Better Solution: Use Git submodules to keep docs separate:
git submodule add https://github.com/stoplightio/spectral.git docs/api
This keeps your main repository clean and Stoplight happy, but adds complexity to your workflow.
