{"canonical_url":"https://engineer.company/glossary/gitlab/","content_markdown":"# GitLab\n\n## What it is\n\nGitLab is a single application built around git repositories: it hosts the code\nand adds merge requests for review, issues for planning, and a built-in CI/CD\nsystem that builds, tests and deploys from the same place. What sets it apart is\nthe choice of where it runs. The same product is offered as GitLab.com, the\nservice GitLab runs itself; as GitLab Self-Managed, which you install on servers\nof your own; and as GitLab Dedicated, a single-tenant instance that GitLab hosts\nand maintains for one customer in the AWS region that customer prefers.\n\nUnderneath is ordinary git. Every project is a git repository that can be\ncloned, pushed to and fetched from with the usual commands, and the history in a\nclone is complete. Everything GitLab adds on top, from review threads and issues\nto pipeline results and permissions, is kept by GitLab itself, outside the\nrepository, and a clone carries none of it.\n\nA merge request is GitLab's name for a proposed change waiting to be merged, the\nsame idea other platforms call a pull request. The documentation describes it as\na central place to review code, hold the discussion and track the change. One\npage shows the description, the code changes with inline review comments, the\nstate of the CI/CD pipelines, the reports on whether the change can be merged,\nand the list of commits. A merge request can be linked to an issue and close\nthat issue automatically when it merges. By default the project's default\nbranch, usually main, is protected, and only people with the Maintainer role or\nhigher may merge into it.\n\nThe CI/CD system is configured in a file named `.gitlab-ci.yml` at the root of\nthe project. It declares the stages, jobs and scripts that together form a\npipeline: stages set the order, such as build, then test, then deploy, and jobs\nare the tasks performed within each stage. The jobs are executed by GitLab\nRunner, a separate program written in Go and shipped as a single binary. A\nrunner connects to a GitLab instance, waits for jobs, runs each one on the\nmachine itself, inside a Docker container or on a remote server over SSH, and\nreports the result back.\n\n## Why it matters\n\nMost of what a software team does between writing code and shipping it can\nhappen inside one GitLab instance: the code, the review, the pipeline that tests\nit, the issue that asked for it and the record of who approved what. One\napplication means one set of accounts and permissions, one place to search, and\nlinks that hold between an issue, the merge request that answered it and the\npipeline that checked it.\n\nThe self-managed option is the reason many organisations choose GitLab at all.\nWhen code cannot leave a company's own infrastructure, because of a contract, a\nregulator or plain policy, a hosted service is out, and GitLab can be installed\ninside the network that has to keep it. The documentation treats this as a\nfirst-class use: it publishes reference architectures for installations sized\nfrom 1,000 to 50,000 users, alongside the Linux package and a Helm chart for\nKubernetes.\n\nThat control has a price, and it is paid in operations rather than in licence\nfees alone. Running GitLab yourself means sizing a server for it, keeping its\nPostgreSQL database and its Redis or Valkey store healthy, providing machines\nfor the runners, taking backups that can actually be restored, and moving\nthrough upgrades in the order the project requires. The hosted options hand that\nwork to GitLab; the self-managed one keeps it with you.\n\n## What it looks like in practice\n\nThe company's own work has met GitLab from both directions.\n\nOver several years of data engineering,\n[CI/CD practices built on GitHub and GitLab](/portfolio/saved-4000-hours-with-github-and-gitlab-ci-cd/),\nwith Bash and Python doing the automation underneath, replaced manual steps in\nboth the data analysis and the software development. The way work moved from\ndevelopment to delivery was standardised so it was the same every time rather\nthan reinvented per project, and the analysis side, long treated as a separate\nand more manual world, was brought into the same pipeline as the development\nwork. The page records roughly 4,000 hours saved, and work that shipped more\nconsistently because it was no longer done a slightly different way each time.\n\nThe company's own code shows the other end of self-hosting. When it moved off a\nthird-party hosting service, it went to\n[a forge it runs itself, that is a single binary, SSH-first and with no administrative web interface](/portfolio/your-code-on-your-own-hardware/),\nchosen on the principle that the less interface there is, the less there is to\ndefend. That forge shares\n[a public-services host with 512 MB of memory](/portfolio/a-whole-company-on-one-small-server/),\nabout 464 MB of it usable, with a web server for seven domains, a Tor onion\nservice, a Gemini server, a Gopher server and intrusion banning. Backup\nautomation is implemented separately; its implementation is distinct from\nactive backups.\n\nNeither page mentions GitLab, and the comparison that follows is this article's\nown arithmetic. GitLab documents 8 GB of memory as the least a single-node\ninstallation can run with; the whole of that host has a sixteenth of it. Being\nable to run GitLab yourself means having a server sized for GitLab, and a small,\nsingle-purpose forge is the other way to keep code on your own machines.\n\nA minimal pipeline file shows the shape of the CI/CD configuration, with two\nstages that run in order and one job in each:\n\n```yaml\nstages:\n    - build\n    - test\n\nbuild-site:\n    stage: build\n    script:\n        - make build\n\nrun-tests:\n    stage: test\n    script:\n        - make test\n```\n\n## Where it goes wrong\n\n- **A small server makes the whole instance slow.** GitLab's documentation gives\n  16 GB of memory as the baseline for a single-node installation and 8 GB as the\n  least it can run with in a memory-constrained environment. It also warns that\n  under load, swap can degrade performance significantly, and asks for swap to\n  be disabled where possible or for enough memory that GitLab never touches it.\n- **A backup restores into an instance that cannot read its own data.** The\n  backup command leaves out the configuration directory, `/etc/gitlab`, and with\n  it `gitlab-secrets.json`, the keys that decrypt encrypted values in the\n  database. Without that file, a restored database keeps those values locked.\n  The documentation asks for the configuration to be backed up separately, at\n  the very least `gitlab-secrets.json` and `gitlab.rb`.\n- **An upgrade jumps over a required stop.** Upgrade paths include required\n  stops, versions that must be installed before any later one, and since GitLab\n  17.5 they fall at x.2, x.5, x.8 and x.11. The background migrations of each\n  stop have to finish before the next upgrade starts, so an instance that falls\n  several versions behind catches up one stop at a time.\n- **A managed data store turns out to be unsupported.** PostgreSQL is the only\n  supported database. Redis or Valkey holds sessions and background tasks and\n  has to be a standalone instance: Redis Cluster and serverless variants of\n  Redis and Valkey are not supported. A managed cloud service is allowed, so\n  long as it is one of the standalone kinds.\n- **Pipelines wait on machines nobody planned for.** GitLab.com offers\n  ready-made runners, but on a self-managed instance the administrator provides\n  and manages the infrastructure where CI/CD jobs run, which includes making\n  sure the runners have enough capacity for the organisation's workload. A busy\n  team with one small runner queues behind it.\n\n## Further reading\n\n- [GitLab Docs](https://docs.gitlab.com/) — the full documentation for using,\n  installing and administering GitLab.\n- [Installation requirements](https://docs.gitlab.com/install/requirements/) —\n  memory, CPU, storage and the supported PostgreSQL and Redis versions.\n- [Back up GitLab](https://docs.gitlab.com/administration/backup_restore/backup_gitlab/)\n  — what a backup contains, what it leaves out and how to store the secrets\n  beside it.\n- [Upgrade paths](https://docs.gitlab.com/update/upgrade_paths/) — the required\n  upgrade stops and why background migrations must finish between them.\n- [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/) — the\n  `.gitlab-ci.yml` file, stages, jobs and pipelines.\n- [GitLab Runner](https://docs.gitlab.com/runner/) — the program that runs the\n  jobs, and the ways it can run them.\n\n\u003chttps://engineer.company/glossary/gitlab/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"What GitLab bundles around git, why teams install it on their own servers, and the memory, backup and upgrade work that comes with keeping it there.","formats":{"gemtext":"https://engineer.company/glossary/gitlab/index.gmi","gopher":"https://engineer.company/glossary/gitlab/gophermap","html":"https://engineer.company/glossary/gitlab/","json":"https://engineer.company/glossary/gitlab/index.json","markdown":"https://engineer.company/glossary/gitlab/index.md","pdf":"https://engineer.company/glossary/gitlab/index.pdf"},"kind":"page","language":"en","title":"What is GitLab?","url":"https://engineer.company/glossary/gitlab/","version":1}