Guide

Self-hosted GitLab and CI: a development process for teams that test hardware and software together

A hardware team that versions and tests firmware, schematics and models together needs four things on its own servers: GitLab for code and reviews, GitLab CI with runners at the hardware for tests, OpenProject for planning and traceability, and paperless-ngx for documents that are not a repository. Here is how they fit together, with LDAP, SAML and SMTP.

It is written for mid-sized manufacturers whose development process so far consists of e-mails, network drives and a Kanban board.

1. Starting point: Kanban is no longer enough

Many hardware teams started with Kanban: a board, cards, columns. That works as long as the whole process lives in the heads of the people involved. It stops working when customers or standards ask which firmware version was tested with which schematic revision, who gave the approval and where the test report is. Then the process needs a form that tools can map.

For a mid-sized manufacturer of security technology we guided exactly this transition: advice on the new development process with complex hardware tests for code as well as for designs and models, then building the tools on virtual machines and connecting them via SMTP and LDAP/SAML2, over around six months. The decisions from back then are the sections of this article.

2. Why run it yourself

Three reasons that regularly tip the balance for hardware manufacturers:

  • The test hardware is on site. CI jobs that flash firmware onto a device and drive a test rig run on runners that physically stand next to the device. A cloud service only reaches that test rig in roundabout ways.
  • Schematics, models and test data are trade secrets. A repository with the layout of a product does not leave the building.
  • Licence costs per user. In teams where the test lab, production and documentation should also be able to read, a per-seat price quickly gets expensive. Self-hosted open-source tools do not have this cost item; instead they have operating effort, which can be planned.

What speaks against it: someone has to install updates, check backups and be reachable when something fails. If you do not have that in-house, you buy it as a service or take the cloud version and solve the test-rig problem with a single local runner.

3. The four tools and their roles

Tool Role What goes in
GitLab Versioning, merge requests, reviews, releases Firmware, software, test scripts, schematic and model exports, CI definitions
GitLab CI with runners Build, unit tests, hardware-in-the-loop tests, artefacts Pipelines per repository; runners with tags per test rig
OpenProject Specs, work packages, releases, traceability What is built and why; links to merge requests
paperless-ngx Documents that do not belong in the repository Test reports as PDF, certificates, supplier documents, signed approvals

The separation matters: everything that can be versioned as text belongs in GitLab. Everything that is a document with a date and a signature belongs in paperless-ngx. OpenProject holds it together: a work package points to the merge request that implemented it and to the test report that signed it off.

4. The platform: virtual machines, deliberately simple

For a team of this size, virtual machines are the right choice, not Kubernetes. One VM per service, plus one for the GitLab runners and one for the reverse proxy with TLS. That can be backed up and restored with standard tools and needs no platform know-how in-house.

Recommendations that have proven themselves:

  • One VM per service, not everything on one. A GitLab update that goes wrong must not take OpenProject down with it.
  • Snapshots before every update, and a restore test once a quarter. A backup that was never restored is a guess.
  • A reverse proxy with internal certificates or an internal ACME service, so that browsers and runners work without warnings.
  • Fixed internal hostnames for all four services, maintained in DNS, not in /etc/hosts.

5. Identity: LDAP for everyone, SAML where possible

Four tools with four passwords per person are the reason teams do not use tools. The solution has two stages:

LDAP (usually Active Directory) is the source for users and groups. GitLab and OpenProject can authenticate against it directly. paperless-ngx has no LDAP of its own; it signs users in via OpenID Connect at the identity provider (which in turn sits on the directory) or takes the user from an authenticating proxy in front of it. Groups from the directory are mapped to roles: development may write, testlab may read and file test reports, management may approve.

SAML 2.0 via an identity provider (Entra ID, Keycloak or the one already in place) adds single sign-on to LDAP: whoever is signed in on the company network is also signed in to GitLab. GitLab and OpenProject support SAML directly; paperless-ngx goes via OpenID Connect, which the same identity provider offers.

The order when building it: first LDAP in GitLab and OpenProject, test groups and roles, then add SAML as a second sign-in method, then switch off LDAP password sign-in. If you start with SAML, you lose access to the tools the first time the identity provider fails; a local break-glass administrator per service always remains.

6. E-mail: SMTP is not optional

Each of the four tools sends e-mails: merge request notifications, pipeline results, reminders, incoming documents. Without working delivery, reviewers do not notice it is their turn, and the process stalls.

An internal SMTP relay that forwards to the company mail server is the clean way: one sender per service (gitlab@, openproject@, paperless@), an SPF record for the relay, authentication with service accounts instead of personal credentials. In the other direction, paperless-ngx can fetch a mailbox and file incoming test reports or supplier documents automatically.

7. CI at the hardware

The real reason to run GitLab CI yourself is the tests on the device. The pattern:

stages: [build, unit, hil, release]

build-firmware:
  stage: build
  image: registry.example.test/toolchain/arm-gcc
  script:
    - make -j firmware
  artifacts:
    paths: [build/firmware.bin]

unit-tests:
  stage: unit
  script:
    - make test

hil-test-rig-a:
  stage: hil
  tags: [test-rig-a] # runner physically stands at test rig A
  resource_group: test-rig-a # never two jobs at the same device at once
  script:
    - ./tools/flash.sh build/firmware.bin
    - ./tools/run-hil.sh --suite smoke --report report.xml
  artifacts:
    reports:
      junit: report.xml
    paths: [report.xml, logs/]
  rules:
    - if: $CI_MERGE_REQUEST_IID

Three details carry the pattern:

  • Runner tags per test rig, so that a job runs exactly where the device is connected.
  • resource_group, so that two pipelines never flash the same device at the same time.
  • JUnit reports as an artefact, so that the result appears in the merge request and OpenProject can link to it.

For designs and models that are not compiled (schematics, mechanical models, simulation models), the same principle applies with different steps: export to a textual or comparable format, checking rules as a script (design rule checks, bill-of-materials comparison), the result as an artefact. Not everything can be automated; but everything that is automated runs on every merge request, not just before the trade fair.

8. The process the tools map

Tools do not replace a process; they make it visible. The development process we set up with the manufacturer follows a simple flow:

  1. Requirement as a work package in OpenProject, with acceptance criteria.
  2. Implementation in a branch; the merge request points to the work package.
  3. Automated tests in the pipeline, including the hardware test at the test rig, with the result in the merge request.
  4. Review by a second person; for safety-relevant changes, by two.
  5. Approval as a release tag in GitLab; the test report is filed as a PDF in paperless-ngx and linked to the release and the work package.
  6. Traceability: from every firmware version shipped, a path leads back to the work package, the review and the test report.

Kanban stays, as a view on the work packages in OpenProject. What is added is the chain from the requirement to the document.

9. Checklist

Platform:

  • One VM per service plus a runner VM plus a reverse proxy; snapshots before updates; restore rehearsed.
  • Internal hostnames in DNS; TLS via an internal CA or ACME.

Identity and e-mail:

  • LDAP in GitLab and OpenProject, paperless-ngx via OIDC at the identity provider; groups mapped to roles.
  • SAML (GitLab, OpenProject) and OIDC (paperless-ngx) via the identity provider; a break-glass admin per service.
  • SMTP relay with one sender per service; SPF set; test mail from every service.

CI:

  • A runner per test rig with a tag and a resource_group.
  • Pipelines with build, unit tests, HIL test, release; JUnit artefacts.
  • Checking rules for designs and models as pipeline steps.

Process:

  • Work package → merge request → pipeline → review → release → test report documented as a chain.
  • Roles: who may write, check, approve.
  • Traceability from a firmware version back to the requirement walked through once.

10. Frequently asked questions

GitLab or Gitea/Forgejo? Gitea and Forgejo are easier to run and are enough for versioning and reviews. GitLab brings CI, a registry, merge request workflows and the SAML connection in one product; for a team with test rigs and an approval process, that is the lower overall complexity.

Do I need OpenProject if GitLab has issues? GitLab issues are enough for development teams. OpenProject brings requirements management, Gantt charts, roles for non-developers and the traceability that standards and customer audits demand. If you have both, keep work packages in OpenProject and link merge requests to them.

How long does the build take? The tools are up in days. The process, the roles and the connection of the test rigs take weeks, because they are developed with the team. Plan months, not days, and start with one product, not all of them.

What about backups? Each service has its own backup procedure (GitLab: gitlab-backup; OpenProject and paperless-ngx: a database dump plus the file directory). gitlab-backup does not include /etc/gitlab/gitlab.rb and /etc/gitlab/gitlab-secrets.json; back both up separately and securely, or part of the data cannot be read after a restore. On top of that, VM snapshots. What counts is the rehearsed restore, not the existence of the files.

Where this leads

We run our own hardware in a data centre in Munich, and we also run GitLab with CI for ourselves. How we build development processes and the tools for them with your team is described under Software architecture & development.

Example from a project: A development process for a manufacturer of security technology.

How individual CI jobs become automated release tests in environments of their own: Release environments on Kubernetes with Crossplane and Argo Workflows.

German version: GitLab und CI selbst betreiben: ein Entwicklungsprozess für Teams, die Hardware und Software zusammen testen.

Sources

All read on 20 Oct 2026.

Does your development process need tools?

Tell us how you develop and test today. In the intro call we work out which of the four building blocks you need and where to start.