Brainfish OAS GitHub Actions Sync

Brainfish OAS Sync is now available on the GitHub Marketplace! This GitHub Action automatically synchronizes your OpenAPI Specification (OAS) files from your repository to your Brainfish API catalog, keeping your documentation always up-to-date.

📋 Prerequisites

Before you begin, make sure you have:

1. A Brainfish account - Sign up here if you don't have one
2. A GitHub repository with OpenAPI specification files
3. Repository admin access to configure GitHub Actions and secrets

🎯 Quick Setup (5 Minutes)

Step 1: Install the Action from GitHub Marketplace

1. Visit the Brainfish OAS Sync on GitHub Marketplace
2. Click "Use latest version" to get the installation instructions
3. Or simply use brainfish-ai/brainfish-oas-sync@v0.0.16 in your workflow

Step 2: Get Your Brainfish Credentials

Get Your API Token

1. Log in to your Brainfish dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New Token"
4. Copy the token (you'll need this for GitHub secrets)

Find Your Catalog ID

1. In your Brainfish dashboard, navigate to the catalog where you want to sync your OAS files
2. The Catalog ID is visible in the URL: https://app.brainfi.sh/catalogs/your-catalog-id-here
3. Copy the catalog ID

Step 3: Configure GitHub Secrets

1. Go to your GitHub repository
2. Click Settings → Secrets and variables → Actions
3. Click "New repository secret" and add:
   • Name: BRAINFISH_API_TOKEN
   • Value: Your API token from Step 2
4. Add another secret:
   • Name: BRAINFISH_CATALOG_ID
   • Value: Your catalog ID from Step 2

Step 4: Create Your Workflow

Create a new file .github/workflows/sync-oas.yml in your repository:

name: Sync OAS to Brainfish

on:
  push:
    branches: [main]
    paths: ['docs/api.yaml'] # Update this path to your OAS file

jobs:
  sync-oas:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        
      - name: Sync OAS to Brainfish
        uses: brainfish-ai/brainfish-oas-sync@v0.0.16
        with:
          brainfish_api_token: ${{ secrets.BRAINFISH_API_TOKEN }}
          catalog_id: ${{ secrets.BRAINFISH_CATALOG_ID }}
          oas_file_path: 'docs/api.yaml' # Update this path to your OAS file

Step 5: Test Your Setup

1. Commit and push the workflow file to your repository
2. Make a change to your OAS file
3. Push the changes to the main branch
4. Check the Actions tab in your GitHub repository to see the sync in progress
5. Verify in your Brainfish catalog that the OAS file has been updated

📖 Common Use Cases

Sync on Every Push to Main

Perfect for keeping your production API documentation always current:

name: Sync OAS to Brainfish

on:
  push:
    branches: [main]
    paths: ['openapi.yaml']

jobs:
  sync-oas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: brainfish-ai/brainfish-oas-sync@v0.0.16
        with:
          brainfish_api_token: ${{ secrets.BRAINFISH_API_TOKEN }}
          catalog_id: ${{ secrets.BRAINFISH_CATALOG_ID }}
          oas_file_path: 'openapi.yaml'

Sync on Release

Ideal for versioned API documentation:

name: Sync OAS on Release

on:
  release:
    types: [published]

jobs:
  sync-oas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: brainfish-ai/brainfish-oas-sync@v0.0.16
        with:
          brainfish_api_token: ${{ secrets.BRAINFISH_API_TOKEN }}
          catalog_id: ${{ secrets.BRAINFISH_CATALOG_ID }}
          oas_file_path: 'api-spec.json'

Manual Trigger

Great for testing or controlled updates:

name: Manual OAS Sync

on:
  workflow_dispatch:
    inputs:
      oas_file:
        description: 'Path to OAS file'
        required: true
        default: 'openapi.yaml'

jobs:
  sync-oas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: brainfish-ai/brainfish-oas-sync@v0.0.16
        with:
          brainfish_api_token: ${{ secrets.BRAINFISH_API_TOKEN }}
          catalog_id: ${{ secrets.BRAINFISH_CATALOG_ID }}
          oas_file_path: ${{ github.event.inputs.oas_file }}

Multiple API Specs

Perfect for microservices or multi-API projects:

name: Sync Multiple OAS Files

on:
  push:
    branches: [main]

jobs:
  sync-multiple-oas:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - file: 'user-api/openapi.yaml'
            catalog: 'user-api-catalog-id'
          - file: 'payment-api/openapi.yml'
            catalog: 'payment-api-catalog-id'
          - file: 'admin-api/openapi.json'
            catalog: 'admin-api-catalog-id'
    
    steps:
      - uses: actions/checkout@v4
      - uses: brainfish-ai/brainfish-oas-sync@v0.0.16
        with:
          brainfish_api_token: ${{ secrets.BRAINFISH_API_TOKEN }}
          catalog_id: ${{ matrix.catalog }}
          oas_file_path: ${{ matrix.file }}

🔧 Configuration Options

Required Parameters

Parameter	Description	Example
brainfish_api_token	Your Brainfish API token	${{ secrets.BRAINFISH_API_TOKEN }}
catalog_id	Target Brainfish catalog ID	${{ secrets.BRAINFISH_CATALOG_ID }}
oas_file_path	Path to your OAS file	'docs/api.yaml'

Optional Parameters

Parameter	Description	Default	Example
base_url	Brainfish API base URL	https://app.brainfi.sh	https://app.dev.brainfish.app
github_token	GitHub token for private repos	${{ github.token }}	${{ secrets.GITHUB_TOKEN }}

Supported File Formats

Format	Extensions	Processing	Status
YAML	.yaml, .yml	✅ Auto-converts to JSON	✅ Supported
JSON	.json	⚡ Uploads as-is	✅ Supported

🚨 Troubleshooting

Common Issues and Solutions

"OAS file not found"

• Problem: The action can't find your OAS file
• Solution: Check that the oas_file_path matches your actual file location
• Example: If your file is in docs/openapi.yaml, use oas_file_path: 'docs/openapi.yaml'

"Authentication failed"

• Problem: Invalid or expired API token
• Solutions:
  • Verify your BRAINFISH_API_TOKEN secret is correct
  • Generate a new API token in Brainfish settings
  • Check that the token has proper permissions

"Catalog not found"

• Problem: Invalid catalog ID
• Solutions:
  • Verify your BRAINFISH_CATALOG_ID secret is correct
  • Check the catalog ID in your Brainfish dashboard URL
  • Ensure you have access to the specified catalog

"Invalid YAML format"

• Problem: Your YAML file has syntax errors
• Solutions:
  • Use a YAML validator to check your file syntax
  • Verify proper indentation (use spaces, not tabs)
  • Check for special characters that need escaping

Enable Debug Logging

Add this to your workflow for detailed debugging information:

env:
  ACTIONS_STEP_DEBUG: true

Check Action Logs

1. Go to your repository's Actions tab
2. Click on the failed workflow run
3. Expand the "Sync OAS to Brainfish" step
4. Review the detailed logs for specific error messages

🆘 Getting Help

Support Channels

• 📖 Documentation: Full README
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📚 Brainfish Help: help.brainfi.sh

Before Reporting Issues

Please include:

1. Your workflow YAML configuration
2. The complete error message from GitHub Actions logs
3. Your OAS file format and approximate size
4. Whether this worked before or is a new setup

🎉 Success! What's Next?

Once your OAS sync is working:

1. Set up notifications - Configure GitHub Actions to notify your team of successful/failed syncs
2. Create branch protection - Require OAS sync to pass before merging PRs
3. Monitor your catalogs - Regularly check your Brainfish catalogs to ensure documentation stays current
4. Scale up - Add more OAS files and catalogs as your API ecosystem grows

---

🔗 Quick Links

• GitHub Marketplace - Install the action
• Brainfish Dashboard - Manage your API catalogs
• GitHub Repository - Source code and documentation

Questions? We're here to help! Reach out through any of the support channels above.