CI/CD and Deployment for Convex via Github Actions and Workflows

[severe sedge]

What is the recommended setup for Convex when using Github actions for CI/CD as well as deployments?
I found https://docs.convex.dev/testing/ci, however no mention of how to best handle deployments in a similar way.
Is this a good idea or recommended and does there exist a good template to start out from for this specific purpose?

[sudden bobcat]

Hi @severe sedge. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Based on the knowledge sources, here's the recommended setup for Convex deployments using GitHub Actions:

Deployment Setup

The recommended approach is to use the CONVEX_DEPLOY_KEY environment variable in your GitHub Actions workflow. Here's how to set it up:

1. Generate a Deploy Key: Go to your Project Settings in the Convex Dashboard and generate a Production Deploy Key.

2. Add to GitHub Secrets: Store the deploy key as a GitHub secret named CONVEX_DEPLOY_KEY.

3. Configure Your Workflow: Use npx convex deploy --cmd 'npm run build' in your GitHub Action to deploy both your Convex backend and build your frontend.

Example GitHub Action

Here's a working example from the knowledge sources for deploying to GitHub Pages:

name: Deploy to GitHub Pages

on:
  push:
    branches: [ master ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      
      - name: Install dependencies
        run: bun install
      
      - name: Deploy Convex and build site
        run: bunx convex deploy --cmd 'bun run build'
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
      
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

## How It Works

According to the [CLI documentation](<https://docs.convex.dev/cli#deploy>), when `CONVEX_DEPLOY_KEY` is set, `npx convex deploy` will:
1. Set the `CONVEX_URL` environment variable for your frontend build
2. Run your build command (e.g., `npm run build`)
3. Deploy your Convex functions to production

This approach is also documented in the [Vercel](<https://docs.convex.dev/production/hosting/vercel>) and [Netlify](<https://docs.convex.dev/production/hosting/netlify>) hosting guides, and works the same way for GitHub Actions.

For testing in CI, you can refer to the [GitHub Actions testing guide](<https://docs.convex.dev/testing/ci#testing-in-github-actions>) mentioned in the knowledge sources.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------