Deploy with Auth

The Issue Tracker has been running against a cloud Convex dev deployment throughout this chapter. To put it online, we need a production Convex deployment, a separate GitHub OAuth App for the production callback URL, and a few environment variables set on the production side. The CI/CD workflow from the previous chapter already handles the actual deploy step, so most of this section is env-var work.

The CI/CD Workflow from the previous chapter

Your repository already contains .github/workflows/deploy.yml from the Project Planner. Open it and you will see it runs a single deploy command on every push to master:

- name: Build with Vite
  run: npx convex deploy --cmd 'pnpm run build'
  env:
    CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}

That one command does two things in order:

  1. Deploys your convex/ directory to your production Convex deployment (the schema, queries, mutations, actions, HTTP routes — everything).
  2. Runs pnpm run build, which builds the Vite app and injects VITE_CONVEX_URL as the production URL (not your dev URL).

The built dist/ folder is then uploaded as a GitHub Pages artifact by a later step in the same workflow. You do not need to change this file. It already builds and deploys a Convex + Vite project. All we need to do is create a production Convex deployment for it to target and set the right env vars on that deployment.

Create a Production Convex Deployment

From the issue-tracker directory, run:

npx convex deploy

The first time you run this, Convex will:

  1. Ask you to confirm you want to create a new production deployment for this project.
  2. Generate a new deployment at a different URL from your dev one (something like https://<some-name>.convex.cloud and https://<some-name>.convex.site).
  3. Deploy your current code — functions, schema, everything — to it.

The new deployment is now live at its own URL. It has no environment variables set yet. Everything we configured in this chapter (JWT keys, SITE_URL, GitHub OAuth credentials) lives on your dev deployment.

Note the production convex.site URL that gets printed to the terminal. You will need it when you create the production OAuth App. You can find it again on the dashboard: open your project, click the dropdown at the top left that shows your current deployment, and you will see both dev and prod URLs listed.

Generate Production JWT Keys

The auth library signs session tokens with a key pair. Dev has one pair, and production needs its own pair. Do not reuse the dev keys. Keep the two pairs separate.

npx @convex-dev/auth --prod

The --prod flag targets the production deployment. The helper does the same things against prod that it did in dev: the JWT key pair, SITE_URL, and checking that the four files exist. When asked for the SITE_URL, enter the production URL with the basepath included: https://<your-github-username>.github.io/issue-tracker/.

At the end of the process, your production deployment has JWT_PRIVATE_KEY and JWKS set, along with other required configuration like SITE_URL set to the production URL.

Create a Production GitHub OAuth App

Go to https://github.com/settings/developers → New OAuth App. This time, fill in the form with your production values:

  • Application name: Issue Tracker (without “(dev)” or “Dev”)

  • Homepage URL: https://<your-github-username>.github.io/issue-tracker/

  • Authorization callback URL: your production Convex .site URL followed by /api/auth/callback/github:

    https://<your-prod-convex-slug>.convex.site/api/auth/callback/github

Click Register application, then Generate a new client secret, and copy its value. Now set the AUTH_GITHUB_ID and AUTH_GITHUB_SECRET environment variables on your production Convex deployment to the new client ID and secret values.

npx convex env set AUTH_GITHUB_ID <your-prod-client-id> --prod
npx convex env set AUTH_GITHUB_SECRET <your-prod-client-secret> --prod

You can verify all the production env vars are set with:

npx convex env list --prod

Deploy Key and GitHub Actions Secret

The CI/CD workflow authenticates to Convex using a deploy key:

  1. Go to https://dashboard.convex.dev/, open your issue-tracker project.
  2. Select the production deployment (not dev).
  3. Go to Settings → Deploy Keys and generate one. Copy the value.
  4. Go to your GitHub repo → Settings → Secrets and variables → Actions.
  5. Create or update the CONVEX_DEPLOY_KEY secret with the new key.

Push and Deploy

Make sure you set the GitHub Pages source to “GitHub Actions” in your repo’s settings. You may have to go to the “Environments” tab and under “Deployment branches and tags” add master (or whatever you call your default branch) as an allowed branch if you have not already.

Commit whatever’s still uncommitted, push to master:

git push

The workflow kicks off. You can follow it under your repo’s Actions tab. The Build with Vite step runs npx convex deploy --cmd 'pnpm run build', which pushes all your backend code to production and builds the frontend with the production VITE_CONVEX_URL included, in one atomic operation.

When the workflow finishes, visit https://<your-github-username>.github.io/issue-tracker/. The production site is live. Click Sign in with GitHub. You will be taken through the production OAuth App’s authorize screen (note it says the production app name, not “dev”). After authorizing, you land back on the production site, signed in, with a clean production database (zero projects, zero issues, your user row created on first sign-in).