VelvetPress/DocsBack to dashboard

Connecting GitLab

VelvetPress can build your plugins and themes from GitLab projects as well as GitHub repos. Everything after the push works the same way: channels, version rules, [skip build], release history and the updates your customers see in wp-admin. This page covers what's different: connecting an account, picking projects, and where to look when something goes wrong.

What you need

  • A gitlab.com account. Self-managed GitLab instances aren't supported yet.
  • Maintainer (or Owner) access on each project you want to ship. VelvetPress registers a webhook on the project, and GitLab only lets Maintainers do that.
  • To create new projects from VelvetPress: Maintainer access on the group you create them in, or your personal namespace.

Connect your GitLab account

In the dashboard, open Settings → Connections. On the GitLab Connection card, click Connect GitLab. GitLab asks you to authorize the VelvetPress application, then sends you back to the dashboard, where the card shows Connected as @your-username.

VelvetPress asks for these GitLab scopes:

  • api: list your groups and projects, create a project when you start a new product, and add or remove the build webhook.
  • read_user: show which account is connected.
  • read_repository: clone your code to package releases.
  • write_repository: push the starter template's first commit when you create a new product on GitLab.

The connection belongs to the workspace

A GitLab connection belongs to the workspace (your personal account, or the organization you've switched to), not to the person who clicked Connect GitLab. Each workspace has one GitLab account. Builds run on the stored connection, so a teammate leaving the organization doesn't break its GitLab products. Clicking Reconnect replaces the connection with whichever GitLab account you authorize.

Use a dedicated account for teams

GitLab can't limit an application's access to a single project the way the GitHub App can. The connection can reach everything the connected GitLab user can reach. For an organization, connect a dedicated GitLab account (a "bot" user) that has Maintainer access only on the groups or projects you ship through VelvetPress, rather than a person's own account.

Add a product from an existing project

  1. Open Themes (or Plugins) and click Add.
  2. Choose GitLab in the GitHub | GitLab toggle.
  3. Find the project. Filter by group, or search by name. The list only shows projects where you're a Maintainer or Owner.
  4. Confirm the Slug, Type, Branch and Root directory. These work exactly as they do for GitHub; see Developer onboarding. The branch defaults to the project's default branch.
  5. Click Create & set up automatically. VelvetPress registers a webhook on the project and runs the first build from the current tip of the branch.

Several products in one project

A monorepo can hold several plugins and themes. Add each one as its own product with its own Root directory, such as themes/my-theme or plugins/my-plugin. Each product gets its own webhook on the project. A push only rebuilds the products whose root directory it touched.

Create a new product on GitLab

Starting from a starter template works on GitLab too:

  1. Click + New Product, pick a type and a starter, and name the product.
  2. On the details step, choose GitLab, then the GitLab namespace to create the project in: your personal namespace, or a group where you're a Maintainer or Owner.
  3. Choose Private or Public and click Create product.

VelvetPress creates an empty project named after the product's slug, pushes the personalized starter as its first commit, and that push runs the first build. The progress screen shows each step until the product is live.

Move an existing product from GitHub to GitLab

If you've moved a repo from GitHub to GitLab, you can switch its products over without losing anything. Release history, channels, preview builds and connected sites all stay with the product.

  1. Make sure the project is on GitLab and your workspace's GitLab connection can see it.
  2. Open the product's Settings panel and click Disconnect next to ✓ GitHub App connected. A product builds from one source at a time.
  3. If the plugin or theme sits at a different path in the GitLab project (for example, you merged two repos into one), update its Root directory in the same panel and save. Do this before the next step, because connecting runs a build straight away.
  4. Click Connect GitLab on the product card and pick the project.

VelvetPress registers the webhook and runs a build from the branch tip. If the version header hasn't changed since the last release, that build shows as skipped and nothing new ships. From then on, pushes to the release branch on GitLab build as usual, and pushes to the old GitHub repo no longer trigger builds for that product.

Disconnect GitLab

On Settings → Connections, click Disconnect on the GitLab card, then Confirm disconnect. VelvetPress revokes its token on GitLab and deletes the stored connection.

Products linked to GitLab stay linked, but their builds fail with a "Reconnect GitLab" message until you connect again. To remove one product's webhook from its project, click Disconnect next to ✓ GitLab connected in that product's Settings panel instead, or delete the product.

You can also revoke access from GitLab itself: Manage on GitLab → opens your authorized applications on gitlab.com. The dashboard then shows that the connection needs reconnecting.

How GitLab differs from GitHub

  • Access follows the connected user. If that user loses access to a project, its builds fail with an access error until you reconnect with an account that has access, or restore the access.
  • Each product has its own webhook. On GitHub, products in one repo share the repo's webhook. On GitLab, each product registers its own, signed with a secret only that product knows.
  • GitLab disables webhooks that keep failing. After 4 failed deliveries in a row GitLab pauses a webhook for a while, and after 40 it disables it. VelvetPress answers every delivery it deliberately ignores (another branch, a tag, an unmapped channel) with success, so this only happens when deliveries really fail.
  • Very long pushes rebuild every product in the project. GitLab lists at most 20 commits in a push event. When a push has more, VelvetPress can't tell which directories changed, so every product in that project builds. Products whose version header didn't change are skipped as usual, so nothing is republished unnecessarily.

Troubleshooting GitLab builds

The build failed with "Reconnect GitLab". The workspace's GitLab connection expired, was revoked, or was disconnected. Open Settings → Connections and click Reconnect on the GitLab card, then Trigger build on the product or push again.

I pushed but nothing happened. In the GitLab project, open Settings → Webhooks. Each VelvetPress product has a hook pointing at …/webhooks/gitlab/…. Click Edit on it and scroll to Recent events to see each delivery and the response VelvetPress returned. You can resend a delivery from there. If the hook is marked disabled, fix the cause, then re-enable it from that page. Then check the usual suspects in Troubleshooting: the branch you pushed to and the product's Root directory.

My project isn't in the picker. The picker only lists projects where the connected GitLab user is a Maintainer or Owner. Check the role on the project or its group, and check which GitLab account is connected on Settings → Connections.