Portability and the two tiers

How vela works on every GitLab CE install method: what GitLab documents as an extension point, the server hook and overlay tiers, and surviving upgrades.

The goal is that vela works on any GitLab Community Edition, however it was installed, and keeps working through upgrades and downgrades. This page says honestly what is possible, what GitLab's documentation allows, and how vela covers the rest.

What GitLab documents as an extension point

From GitLab's own docs (file hooks, server hooks, extending GitLab):

MechanismCan block something?Stable across versions?
Server hooks (pre-receive, update, post-receive), global or per repositoryYes, a pushYes. Documented for Linux package, source and Helm installs
File hooks, system hooks, webhooksNo, they run after the eventYes
REST and GraphQL APIsNoVersioned (v4)
Anything else (hide a path in the UI, add a settings page)No documented wayGitLab's advice is to change the source and contribute upstream

So no supported plugin API can hide paths or add a page to Project Settings. What can be done in a supported, version-proof way is write enforcement through a global pre-receive server hook. That is Tier A.

The two tiers

Tier A: server hookTier B: overlay
EnforcesWrite (push, web edit, API commit, merge, tag)Write, plus hides paths (View and Read) in the UI, API, search and diffs
Relies onOnly documented behaviour: hook environment variables, the REST API, plain gitGitLab internals (the push-check hook, Repository, Tree and others)
VersionsAny CE with global server hooksTested versions only. Refuses to start if an internal it needs is missing
Install methodsLinux package, Docker, source, HelmLinux package, Docker, source (Helm needs a custom image)
Where rules liveA project CI/CD variable VELA_PATH_POLICY (only Maintainers and Owners can read or change it)Database tables
Survives a GitLab upgradeYes, it lives outside GitLab's filesYes, if installed the persistent way below

You can run Tier A alone on any GitLab. Add Tier B when you also want paths hidden. If both run, a push is checked twice, which is harmless.

How vela stays safe across versions

  1. Capability checks, not version numbers. At boot the overlay checks that every method it wraps still exists. If one is missing, GitLab refuses to start rather than run unprotected. The server hook uses no GitLab internals at all.
  2. Fail closed everywhere. If rules cannot be read, a push is rejected and a read is a 404. Never "allow because we could not check".
  3. Automated compatibility tests. dev/e2e.sh runs the same live suite against any GitLab version, in either tier. A scheduled workflow runs it across a version matrix, and results are published in compat/. A version is listed as supported only when its results are green.
  4. Upgrades: see below.
  5. Downgrades: the add-on tables are separate from GitLab's own and are never touched by GitLab migrations, so a downgrade leaves them intact. The overlay re-checks its hooks on the older version at the next start. (GitLab itself only supports downgrades through a database restore.)

Surviving an upgrade, per install method

A GitLab upgrade can replace files under its own directories. vela puts nothing there that it cannot restore on its own.

InstallTier A (hook)Tier B (overlay)
Linux packageThe hook lives in custom_hooks_dir, which upgrades do not touchAdd a copy step to /etc/gitlab/gitlab.rb. It runs on every reconfigure, which is part of every package upgrade, so the initializer is put back automatically. See install.md
DockerMount the hook directoryMount lib/ and overlay/ as directories and copy the initializer from gitlab.rb as above. This is what dev/up.sh does. It was tested through an in-place container upgrade
Sourcecustom_hooks_dir in gitlab-shell/config.ymlCopy the initializer after each git checkout of a new tag. The doctor script reports if it is missing
HelmSet the Gitaly chart's global server hooksBuild a custom image with the initializer baked in

The doctor check

After any upgrade or downgrade, run sudo bin/doctor --deep. It is read-only. It reports which tiers are active, whether the hook can still reach GitLab's API with its token, whether the overlay initializer is still in place and loaded, and whether the database role can still read the add-on tables.

Running Tier A in production: what to know

  • The hook calls GitLab's REST API (about three to five small requests per push: the project's policy, the user, their access, and group membership). The Gitaly server must be able to reach GitLab's web address. A brief outage is retried three times (after 0.5 s and 1.5 s) before the push is rejected. A wrong token is not retried.
  • It adds time to every push to a project that has path permissions on. About 2.5 seconds on a small test VM. Projects without the VELA_PATH_POLICY variable cost one small request.
  • Commits made inside GitLab (API, web editor, merge button) also run the hook, and the hook then calls back into GitLab's web process. Keep at least two web workers (the default Linux package setup has them) so the nested call has a free thread. On a single-process, single-thread setup it would time out and the commit would be rejected.
  • Projects with CI/CD turned off answer 403 (not 404) when the hook looks for the policy variable. Such a project cannot hold the variable, so the hook treats it as having no policy. A token without the api scope is still rejected. If you turn CI/CD off on a project that already has a policy, the policy stops applying: keep CI/CD on for protected projects.
  • If GitLab's API is down, pushes to protected projects are rejected. That is the fail-closed choice. Pushes to projects without a policy variable are also affected, because the hook must ask GitLab whether one exists.
  • Group membership counts inherited members, but not groups shared into another group.

What cannot be promised

  • Version coverage beyond what the compatibility results show. Untested versions may work, and the boot check will say if the overlay cannot.
  • Tier A cannot hide anything. Hiding needs Tier B.
  • Neither tier restricts git clone or git fetch.

This page is built from docs/portability.md on GitHub.

On this page