CI/CD Integration Guide

This guide walks you through integrating Seedfast into your CI/CD pipelines. By the end, you'll have automated database seeding running in GitHub Actions, GitLab CI, CircleCI, or Jenkins.

Before you begin

Make sure you have:

• A Seedfast account
• A PostgreSQL, MySQL, or SQL Server database accessible from your CI/CD environment
• Access to configure secrets in your CI/CD platform

Create your API key

API keys authenticate the Seedfast CLI in non-interactive environments where browser-based login isn't possible.

To generate an API key:

1. Log in to the Seedfast Dashboard
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Copy the key immediately — it won't be shown again

Your API key looks like this:

sfk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Configure CI/CD secrets

Store your API key and database credentials as encrypted secrets in your CI/CD platform.

GitHub Actions:

Go to your repository → Settings → Secrets and variables → Actions → New repository secret. Add:

SEEDFAST_API_KEY=sfk_live_...
DATABASE_URL=postgres://user:pass@host:5432/db

GitLab CI:

Go to your project → Settings → CI/CD → Variables. Add the same variables and mark them as Masked and Protected.

CircleCI:

Go to Project Settings → Environment Variables and add both secrets.

Install Seedfast in your pipeline

The simplest way is using npx — no installation required:

npx seedfast seed --scope "Your scope here"

Or download the binary directly:

curl -fsSL https://get.seedfast.dev | sh

Write your first seeding command

The basic command structure for CI/CD:

seedfast seed --scope "Your scope description" --output json

The --scope flag describes what data to seed in plain English:

# Seed by schema
--scope "HR schema only"

# Seed by use case
--scope "Users and orders for e-commerce tests"

# Seed with specificity
--scope "Single admin user with 5 team members"

When --scope is provided, Seedfast automatically approves the seeding plan without prompting. This enables fully automated pipelines.

The --output flag controls output format:

• json — Machine-readable for scripts
• plain — Timestamped logs for CI
• interactive — Colors and spinners (default)

GitHub Actions example

Here's a complete workflow that seeds a test database before running E2E tests:

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: testpass
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
      - name: Seed test data
        run: npx seedfast seed --scope "Users and orders for E2E tests"
        env:
          SEEDFAST_API_KEY: ${{ secrets.SEEDFAST_API_KEY }}
          DATABASE_URL: postgres://postgres:testpass@localhost:5432/postgres
      - run: npm run test:e2e

GitLab CI example

test:
  stage: test
  services:
    - postgres:15
  variables:
    POSTGRES_PASSWORD: testpass
    DATABASE_URL: postgres://postgres:testpass@postgres:5432/postgres
  script:
    - npm ci
    - npm run db:migrate
    - npx seedfast seed --scope "Test dataset" --output plain
    - npm run test

Validate seeding results

Use JSON output to validate seeding in scripts:

RESULT=$(seedfast seed --scope "..." --output json)

if [ "$(echo $RESULT | jq -r '.success')" != "true" ]; then
  echo "Seeding failed!"
  exit 1
fi

echo "Seeded $(echo $RESULT | jq -r '.rows') rows"

Exit codes

Handle these exit codes in your pipeline:

• 0 — Success
• 1 — Generic error
• 2 — Authentication failed (check API key)
• 3 — Database connection failed (check DATABASE_URL)
• 4 — Quota exceeded

Troubleshooting

"Authentication failed" in CI but works locally:

• Verify the secret name matches exactly
• Check for leading/trailing whitespace in the secret
• Ensure the API key hasn't been revoked

"Connection refused" to database:

• Wait for database health check to pass
• Use correct hostname (localhost for GitHub Actions, postgres for GitLab CI)
• Check firewall rules allow CI runner IPs

Security best practices

• Store API keys in CI/CD secret management — never commit to repo
• Use separate keys per environment
• Rotate keys every 90 days
• Limit key scope to seeding step only:

# Good: Key only in seeding step
- name: Seed database
  run: seedfast seed --scope "..."
  env:
    SEEDFAST_API_KEY: ${{ secrets.SEEDFAST_API_KEY }}

Next steps

You're now ready to automate database seeding in your pipelines. Start with one test job, refine your scope based on actual needs, then expand to more test suites.