Developer onboarding

This is the long-form version of Quick Start steps 1–2. By the end of it, you'll have a VelvetPress account, the VelvetPress GitHub App installed on the account or organization that owns the repo you want to ship, a product registered in VelvetPress, and a release branch chosen. The next push to that branch publishes the first release.

Overview

You'll do four things:

Create a VelvetPress account.
Install the VelvetPress GitHub App on the personal account or organization that owns the repo you want to ship.
Register that repo as a VelvetPress product.
Pick which branch produces releases.

Steps 2–4 happen in the same flow on the dashboard — they're listed separately here because each one is something you might want to come back and change later.

Create your VelvetPress account

Go to velvetpress.dev. On the landing page, click Sign In in the top nav (or Get Started in the pricing section) — both open the same Clerk-hosted sign-in modal, which doubles as sign-up if you don't have an account yet.

You can sign up with email or any of the social providers Clerk surfaces (Google, GitHub, and so on). Once you're in, you land on /dashboard.

The first account in your workspace is the owner. Inviting teammates and switching between organizations happens through the org switcher in the dashboard header, but that's beyond this guide.

Install the VelvetPress GitHub App

From the dashboard, click Themes (or Plugins) in the left sidebar, then click Add. The first time, VelvetPress checks whether you've already authorized the GitHub App. If you haven't, you'll see a panel titled Connect your GitHub account with a single Connect GitHub button.

VelvetPress supports installing the GitHub App on either a personal account or any organization you belong to, and you can connect more than one. Teams usually install it on the org that owns the plugin or theme repo; solo developers usually install on their personal account. Either works the same way end-to-end.

Click Connect GitHub. GitHub takes you to its install screen, where you'll:

Pick the account or org to install into. If your plugin or theme lives under an organization, pick the org — not your personal account. You can come back and connect another account or org later.
Choose repository access. Pick Only select repositories and tick just the repo (or repos) you want VelvetPress to ship. You can grant access to more later from your GitHub settings; least-privilege is the safer default. "All repositories" works too, but VelvetPress only needs the repos you'll actually publish from.
Review permissions and install. The app needs read access to your repo contents (so it can package releases) and the ability to register a push webhook on the repo (so pushes trigger builds). GitHub's install screen labels these explicitly — the exact wording is whatever the App manifest declares at the time you install.

GitHub sends you back to the dashboard. The Add product form now shows your accessible repos, streaming in newest-pushed first. If you've installed the App on more than one account or org, the form shows an installation switcher above the repo list — click a different account/org chip to stream that installation's repos instead.

Manage connected accounts and add another

Every account or org you've installed the GitHub App on shows up in the dashboard's Connections tab in the left sidebar. From there you can:

See each connected account or organization with a Manage on GitHub link to its install settings — that's where you adjust which repos VelvetPress can see within an existing install.
Click Add another account or organization to walk through the install flow on a new account or org. The new install joins the switcher in the repo picker the next time you open Add product.

You can also start a new install directly from the repo picker: the last entry in the installation switcher is Install on another account or org, which jumps to the same GitHub install screen.

Select a repo to ship

In the repo picker, find the repo you forked or created for your plugin or theme and click it. Each repo becomes one product in VelvetPress — a plugin product or a theme product, your choice on the next screen.

The picker shows the repo's default branch next to each row. That's just an indicator at this point; you'll confirm the release branch in the next step.

If your repo isn't in the list, check three things in order:

You're looking at the right installation. If you've connected more than one account or org, the installation switcher above the repo list defaults to one of them. Click the chip for the account or org that owns the repo.
The GitHub App can see the repo within that install. Open the Connections tab and click Manage on GitHub for that account or org to add the repo to the App's allowed repositories. The dashboard picks up the change the next time it loads the repo list.
The repo's account isn't connected at all. Use Add another account or organization on the Connections tab (or Install on another account or org in the picker) to install the App on it.

The picker also offers a Try reinstalling the GitHub App link as a shortcut for the second case.

Configure the release branch

Clicking a repo takes you to Configure Product. Four fields:

Type — Theme or Plugin. Pick the one that matches what the repo contains.
Slug — defaults to the repo name. This must match the WordPress plugin or theme folder name (the slug WordPress uses internally for updates). Change it only if the repo name doesn't match.
Branch — defaults to the repo's default branch (usually main). This is the release branch: every push to it triggers a new release. Pushes to other branches are ignored.
Root directory — . if the plugin or theme lives at the repo root. If you store your theme under, say, themes/my-theme/, put that path here. VelvetPress packages the contents of this directory as the release zip.

Click Create & set up automatically. VelvetPress creates the product record and registers a push webhook on the repo in one step — no need to add a webhook by hand. You'll land back on the Themes (or Plugins) tab with the new product listed.

You can change the branch, root directory, or slug later from the product card if your repo's layout shifts.

What's next

You've connected one repo and picked a release branch. Two things to do next:

Install the client plugin on your WordPress site so it can poll for updates. See Installing on a customer WordPress site.
Push your first change. Bump the version header in your repo and push to the release branch. See Publishing a plugin or theme for what triggers a release, what the manifest contains, and the versioning conventions VelvetPress expects.

For the wire-level details of the update endpoint your sites poll, see the Update manifest reference.