GitHub Actions

You can deploy your docs automatically on every push to your repository using GitHub Actions. The workflow runs npx blodemd push under the hood.

Minimal workflow

This workflow deploys your docs whenever you push to the main branch:

Copyname: Deploy docs

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx --yes blodemd push
        env:
          BLODEMD_API_KEY: ${{ secrets.BLODEMD_API_KEY }}

Production workflow with branch deploys

This workflow deploys the main branch to production and creates preview deployments for pull requests:

Copyname: Deploy docs

on:
  push:
    branches: [main]
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run

The BLODEMD_BRANCH value uses github.head_ref for pull requests (the source branch name) and falls back to github.ref_name for pushes.

Using the composite action

Blode.md also provides a composite GitHub Action that wraps the CLI. You can use it instead of running npx directly:

Copyname: Deploy docs

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mblode/blodemd/packages/deploy-action@main
        with:
          api-key: ${{ secrets.BLODEMD_API_KEY }}

Action inputs

Setting up the API key

You need a BLODEMD_API_KEY secret in your GitHub repository. Here is how to set it up:

CopyProject my-project created
API key for CI: bmd_abc123...

Specifying the docs directory

If your docs are not in the default location, pass the directory path as an argument or use the directory input:

Copy- run: npx --yes blodemd push ./my-docs
  env:
    BLODEMD_API_KEY: ${{ secrets.BLODEMD_API_KEY }}

Auto-detected environment variables

When running in GitHub Actions, the CLI automatically detects:

• GITHUB_REF_NAME: used as the branch name if BLODEMD_BRANCH is not set
• Working directory: the checkout root, where docs.json auto-detection starts

Related pages

• Deploying with push -- command reference and deployment flow
• Environment variables -- all recognized environment variables