Skip to main content
Troubleshoot problems with CI/CD integration, authentication, and automated workflows.

​
GitHub Actions: API Call Fails

Error: 
curl: (6) Could not resolve host: bytebase.example.com
Causes:
  1. Incorrect Bytebase URL
  2. Network restrictions
  3. DNS resolution issues
Solutions: 
# .github/workflows/gitops.yml

# 1. Verify BB_URL environment variable
- name: Check Bytebase URL
  run: echo "Bytebase URL: $BB_URL"
  env:
    BB_URL: ${{ secrets.BYTEBASE_URL }}

# 2. Test connectivity
- name: Test Connection
  run: curl -f $BB_URL/v1/actuator/info

# 3. Use correct authentication
- name: Create Release
  run: |
    curl -X POST "$BB_URL/v1/projects/my-project/releases" \
      -H "Authorization: Bearer $BB_TOKEN" \
      -H "Content-Type: application/json" \
      -d @release.json
  env:
    BB_URL: ${{ secrets.BYTEBASE_URL }}
    BB_TOKEN: ${{ secrets.BYTEBASE_TOKEN }}

​
Unauthorized Error

Error: 
401 Unauthorized: Invalid token
Causes:
  1. Token expired or invalid
  2. Token not properly set in secrets
  3. Wrong token format
Solutions:
Test token manually:
curl -H "Authorization: Bearer $BB_TOKEN" \
  $BB_URL/v1/actuator/info
Should return server info, not 401.
  1. Login to Bytebase
  2. Navigate to Settings → Service Accounts
  3. Find CI/CD service account
  4. Generate new token
  5. Update CI/CD secrets
Token should be:
  • Format: bb_xxxxxxxxxxxxxxxxxxxxxx
  • No quotes or extra characters
  • Properly base64 encoded if required
In GitHub Actions:
env:
  BB_TOKEN: ${{ secrets.BYTEBASE_TOKEN }}
  # NOT: "${{ secrets.BYTEBASE_TOKEN }}"

​
SQL Review Fails in CI

Error: 
SQL review failed: Rule violation - table naming convention
Cause: Migration violates configured SQL review rules. Solutions: Option 1: Fix the violation 
-- If error: Table name must be lowercase
-- ❌ Wrong
CREATE TABLE UserProfiles (...);

-- ✅ Correct
CREATE TABLE user_profiles (...);
Option 2: Adjust SQL review policy If rule is too strict:
  1. Navigate to SQL Review settings
  2. Adjust rule severity (ERROR → WARNING)
  3. Or disable rule if not needed

SQL Review Rules

Complete reference of 200+ rules
 Option 3: Override for specific case Add comment justification in SQL: 
-- bytebase:ignore-rule table.naming.convention
-- Legacy table name required for compatibility
CREATE TABLE UserProfiles (...);
Review failures prevent bad changes from reaching production. Fix violations rather than bypassing checks.

​
CI Timeout

Error: 
Error: The operation was canceled.
Causes:
  1. Long-running migration exceeds CI timeout
  2. Network connectivity issues
  3. Bytebase server overloaded
Solutions:
  • Increase Timeout
  • Optimize Migration
  • Check Bytebase Status
GitHub Actions:
jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # Increase from default 360
    steps:
      - name: Deploy
        timeout-minutes: 20  # Step-level timeout
        run: ...
GitLab CI:
rollout:
  timeout: 30m
  script:
    - bytebase-action rollout ...

​
Workflow Dispatch Not Triggering

Error: Manual workflow doesn’t start when triggered. Causes:
  1. Wrong branch selected
  2. Insufficient permissions
  3. Workflow file syntax error
Solutions: Check workflow configuration: 
# .github/workflows/deploy.yml
name: Manual Deploy
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        type: choice
        options:
          - dev
          - staging
          - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to ${{ inputs.environment }}
        run: echo "Deploying to ${{ inputs.environment }}"
Verify permissions:
  • Must have write access to repository
  • Workflow must be in default branch
  • Actions must be enabled for repository

​
Secrets Not Available

Error: 
Error: Secret BYTEBASE_TOKEN is not set
Solutions:
  1. Add secrets to repository:
    • Navigate to Settings → Secrets and variables → Actions
    • Click “New repository secret”
    • Add required secrets
  2. Environment-specific secrets: 
    jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Use environment secrets
    steps:
      - name: Deploy
        env:
          BB_TOKEN: ${{ secrets.BYTEBASE_TOKEN }}
  3. Organization secrets:
    • Can be shared across repositories
    • Set at organization level
    • Select which repositories can access

​
Next Steps

GitOps Tutorials

Step-by-step CI/CD setup guides

API Authentication

Learn about service accounts

Best Practices

CI/CD patterns and strategies

Troubleshooting Overview

Return to troubleshooting overview