GitHub Actions deploy

Jason Lee

Automatically publish markdown files to Sitepaste whenever you push to your repository. The deploy action syncs a directory of markdown files and triggers a site build.

Quick start

First, create an API token from the Sitepaste dashboard under Settings > API tokens. See the authentication docs for details. Add it as a repository secret called SITEPASTE_TOKEN in your GitHub repository settings.

Then add a workflow file to your repository at .github/workflows/deploy.yml:

name: Deploy docs

on:
  push:
    branches: [main]
    paths: [docs/**]

concurrency:
  group: sitepaste-deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Sitepaste/integrations/actions/deploy@v1
        with:
          api-token: ${{ secrets.SITEPASTE_TOKEN }}
          content-dir: docs
          content-type: docs

Inputs

Outputs

Front matter

You can add YAML front matter to any markdown file to control how it appears on your site. All fields are optional. When omitted, the slug is derived from the filename and the title is derived from the slug.

Examples

Publish blog posts from a posts/ directory:

name: Publish blog

on:
  push:
    branches: [main]
    paths: [posts/**]

concurrency:
  group: sitepaste-deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Sitepaste/integrations/actions/deploy@v1
        with:
          api-token: ${{ secrets.SITEPASTE_TOKEN }}
          content-dir: posts
          content-type: blog

Preview changes on pull requests without publishing:

name: Preview deploy on PR

on:
  pull_request:
    paths: [docs/**]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Sitepaste/integrations/actions/deploy@v1
        with:
          api-token: ${{ secrets.SITEPASTE_TOKEN }}
          content-dir: docs
          content-type: docs
          dry-run: 'true'

Validation

The action validates every file before making any API call. If any file has a slug that is too long, content that exceeds the size limit, or a duplicate slug, the workflow fails with annotations pointing to the exact file. Relative image references produce warnings since media must be uploaded separately via the dashboard or the media API.

Learn more

The action source and additional examples are available in the Sitepaste/integrations repository. For details on the underlying API used by the action, see the pages API docs and the builds API docs.