---
title: "Brainfish OAS GitHub Actions Sync"
description: "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."
canonical_url: "https://help.brainfi.sh/articles/brainfish-oas-github-actions-sync-mSe3TY5Zi9"
md_url: "https://help.brainfi.sh/articles/brainfish-oas-github-actions-sync-mSe3TY5Zi9.md"
---
# Brainfish OAS GitHub Actions Sync

**Brainfish OAS Sync** is now available on the [GitHub Marketplace](https://github.com/marketplace/actions/brainfish-oas-sync)! 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](https://app.brainfi.sh) 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](https://github.com/marketplace/actions/brainfish-oas-sync)
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](https://app.brainfi.sh/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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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](https://github.com/brainfish-ai/brainfish-oas-sync#readme)
* **🐛 Bug Reports**: [GitHub Issues](https://github.com/brainfish-ai/brainfish-oas-sync/issues)
* **💬 Discussions**: [GitHub Discussions](https://github.com/brainfish-ai/brainfish-oas-sync/discussions?blk=true)
* **📚 Brainfish Help**: [help.brainfi.sh](https://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](https://github.com/marketplace/actions/brainfish-oas-sync)** - Install the action
* **[Brainfish Dashboard](https://app.brainfi.sh)** - Manage your API catalogs
* **[GitHub Repository](https://github.com/brainfish-ai/brainfish-oas-sync)** - Source code and documentation

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