Skip to main content

CI Integration

Deprecated

The dbdocs CLI is deprecated. It keeps working and stays documented here for existing pipelines, but it stops receiving updates in 2027. For new pipelines use the dbdiagram CLI, which publishes the same doc project with dbdiagram build document.

Integrate with CI​

You can use your unique access token to update projects with continuous integration (CI) systems:

First, generate your access token locally after logging in.

$ dbdocs token -g
✔ Verify your identity
✔ Your access token is: <your-token>
  › Warning: Please save this token. You cannot see it again.

Then add DBDOCS_TOKEN as a new environment variable in your CI system.

DBDOCS_TOKEN=<your-token>

Security Note: Never commit your token to version control. Use your CI platform's secret management to store the token securely.

Now you can run dbdocs build command on your CI without manual login steps:

$ dbdocs build ./ecommerce.dbml --project ecommerce

GitHub Actions Example​

Here's a complete example of integrating dbdocs with GitHub Actions:

name: Update dbdocs

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dbdocs
        run: sudo npm install -g dbdocs

      - name: Verify dbdocs installation
        run: dbdocs --version

      - name: Update dbdocs project
        env:
          DBDOCS_TOKEN: ${{ secrets.DBDOCS_TOKEN }}
        run: dbdocs build ./ecommerce.dbml --project ecommerce

Setup Instructions:

  1. Generate your access token locally using dbdocs token -g
  2. Go to your GitHub repository Settings → Secrets and variables → Actions
  3. Create a new secret named DBDOCS_TOKEN and paste your token
  4. The workflow will automatically update your project on every push to main

Revoke Access Token​

If your token is compromised or no longer needed, you can revoke it immediately:

$ dbdocs token -r
✔ Verify your identity
✔ Your access token has been revoked

After revoking, you'll need to generate a new token and update your CI system's environment variables.