[{"data":1,"prerenderedAt":792},["ShallowReactive",2],{"/en-us/blog/generic-semantic-version-processing":3,"navigation-en-us":38,"banner-en-us":438,"footer-en-us":448,"blog-post-authors-en-us-Julian Thome":688,"blog-related-posts-en-us-generic-semantic-version-processing":702,"assessment-promotions-en-us":744,"next-steps-en-us":782},{"id":4,"title":5,"authorSlugs":6,"body":8,"categorySlug":9,"config":10,"content":14,"description":8,"extension":25,"isFeatured":12,"meta":26,"navigation":27,"path":28,"publishedDate":20,"seo":29,"stem":33,"tagSlugs":34,"__hash__":37},"blogPosts/en-us/blog/generic-semantic-version-processing.yml","Generic Semantic Version Processing",[7],"julian-thome",null,"security",{"slug":11,"featured":12,"template":13},"generic-semantic-version-processing",false,"BlogPost",{"title":15,"description":16,"authors":17,"heroImage":19,"date":20,"body":21,"category":9,"tags":22},"SemVer versioning: how we handled it with linear interval arithmetic","SemVer versioning made it difficult to automate processing. We turned to linear interval arithmetic to come up with a unified, language-agnostic semantic versioning approach.",[18],"Julian Thome","https://res.cloudinary.com/about-gitlab-com/image/upload/v1749663397/Blog/Hero%20Images/logoforblogpost.jpg","2021-09-28","The [semantic versioning (SemVer) specification](https://semver.org/) can be considered the de-facto standard for tracking software states during its evolution. Unfortunately, in reality many languages/ecosystems practice \"SemVer versioning\" and have not adopted the standard as-is; instead we can find many different semantic versioning flavors that are not necessarily compatible with the original SemVer spec. SemVer Versioning has led to the creation of a variety of different semantic versioning schemes.\nGitLab provides a [Dependency Scanning (DS)](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/)\nfeature that automatically detects vulnerabilities in the dependencies of a software project for a variety of different languages. DS relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db)\nthat is updated on a daily basis providing information about vulnerable packages that is expressed in the package-specific (native)\nsemantic version dialect. GitLab also recently launched an [Open Source Edition](https://gitlab.com/gitlab-org/advisories-community) of the GitLab Advisory Database.\nAt GitLab we use a semi-automated process for advisory generation: we extract advisory data that includes package names and vulnerable versions from data-sources such as [NVD](https://nvd.nist.gov/) and generate advisories that adhere to the GitLab advisory format before they are curated and stored in our [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db).\nThe plethora of SemVer versioning in the wild posed a major challenge for the level of automation we could apply in the advisory generation process: the different semantic version dialects prevented us from building generic mechanisms around version matching, version verification (i.e., the process of verifying whether or not versions are available on the relevant package registry), fixed version inference etc. Moreover, since advisory generation requires us to extract and update advisory data on scale from data-sources with hundreds of thousands vulnerability entries, translating and/or verifying versions by hand is not a viable, scalable solution.\nHaving a generic method to digest and process a variety of different SemVer versioning dialects was an important building block for automating large parts of the advisory generation process. This led to the development of [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects), a utility that helps processing semantic versions in a generic, language-agnostic manner which has been recently open-sourced (MIT) and [published on rubygems.org](https://rubygems.org/gems/semver_dialects).\n## Understand the SemVer spec\nThe SemVer spec is the de-facto standard for tracking states of software projects during their evolution by associating unique, comparable version numbers to distinct states, and by encoding semantic properties into the semantic version strings so that a version change implicitly conveys information about the nature of the change.  \nA semantic version consists of a prefix (version core) and a suffix that hold pre-release and/or build information. A version core consists of three numeric components that are delimited by `.`:\n* major: backwards-incompatible changes\n* minor: new backwards-compatible functionality\n* patch: backwards-compatible bug fixes\nConsidering a software project using SemVer, with two releases `1.0.0` and `1.0.1`, by just looking at the change applied to the semantic version strings, it is clear that `1.0.1` is a newer (more recent) release of the software, whereas version `1.0.0` is an older release. In addition, the version number `1.0.1` represents an improved state of the software as compared to version `1.0.0` which contained a bug that has been fixed in version `1.0.1`. This fix is signalled by the higher number of the patch version component.\nSemantic version processing is particularly useful in the context of [Dependency Scanning (DS)](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/). DS is the process of automatically detecting (and potentially fixing)\nvulnerabilities related to the dependencies of a software project: dependencies of a software project are checked against a set of configuration files (so called advisories) that contain information about vulnerable dependencies; advisories usually include the versions of the vulnerable dependency.\nVulnerable versions are usually expressed in terms of version intervals: for example [this out-of-bounds read vulnerability for the Python tensorflow package](https://nvd.nist.gov/vuln/detail/CVE-2021-29560) contains information about the vulnerable version by listing the four version intervals below:\n1. up to 2.1.4\n1. from 2.2.0 up to 2.2.3\n1. from 2.3.0 up to 2.3.3\n1. from 2.4.0 up to 2.4.2\nWhile SemVer is very concise and clear about the syntax and semantic of semantic versions, it does not specify how to express and represent semantic version constraints. In addition, SemVer is purposefully simplistic to foster its adoption. In practice it seems as if many ecosystems required features that go beyond SemVer which led to the development of many SemVer versioning flavours as well as a variety of different native constraint matching syntaxes, some of which deviate from the official SemVer specification.  Depending on the ecosystem you are working with, the same semantic version string may be treated/interpreted differently: for example both Maven and pip/PyPI treat versions `1.2.3.SP` differently because pip/PyPI lacks the notion of an `SP` post release. Apart from that, `1.2.3.SP` cannot be considered a valid semantic version according to the SemVer spec.\nToday we have a variety of different semantic versioning schemes:\n- `gem`: [gem requirement](https://guides.rubygems.org/specification-reference/#add_runtime_dependency)\n- `maven`: [Maven Dependency Version Requirement Specification](https://maven.apache.org/pom.html#Dependency_Version_Requirement_Specification)\n- `npm`: [node-semver](https://github.com/npm/node-semver#ranges)\n- `php`: [PHP Composer version constraints](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints)\n- `pypi`: [PEP440](https://www.python.org/dev/peps/pep-0440/#version-specifiers)\n- `go`: [go semver](https://godoc.org/golang.org/x/tools/internal/semver)\n- `nuget`: [NuGet semver](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning)\n- `conan`: [node-semver flavour](https://github.com/npm/node-semver#ranges)\nThis SemVer versioning fragmentation limited the degree of automation we could apply to our advisory extraction/generation process. This limitation motivated the development of a methodology and tool [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) that helps to digest and process semantic versions in a language agnostic way and, hence, helps to reduce the manual advisory curation effort.\nBelow, you can see an excerpt of the advisory information that is extracted and generated by our semi-automated advisory generation process:\n```yaml\n# ...\naffected_range: \">=1.9,\u003C=2.7.1||==2.8\"\nfixed_versions:\n- \"2.7.2\"\n- \"2.8.1\"\nnot_impacted: \"All versions before 1.9, all versions after 2.7.1 before 2.8, all versions\n  after 2.8\"\nsolution: \"Upgrade to versions 2.7.2, 2.8.1 or above.\"\n# ...\n```\nIn the excerpt above:\n- `affected_range` denotes the range of affected versions which is the machine-readable, native syntax used by the package manager/registry (in this case pypi).\n- `fixed_versions` denotes the concrete versions when the vulnerability has been fixed.\n- `not_impacted` provides a textual description of the versions that are not affected.\n- `solution` provides information about how to remediate the vulnerability.\nTo be able to extract and generate advisories like the one illustrated above in a language/ecosystem agnostic way, we implemented and open-sourced a generic semantic version representation and processing approach called semver_dialects.\nIn the advisory excerpt above, the `affected_range` field contains the version constraints in the native constraint syntax (in this case PyPI for Python); `fixed_versions` can be inferred by inverting the `affected_version` (i.e., non-affected versions) and by selecting the first available  version that falls into the range of non-affected versions from the native package registry; this step requires our approach to be able to parse the native semantic version syntax.\nIn order to deal with SemVer versioning and automatically process and generate the fields according to this description, our [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) implementation had to satisfy the following requirements:\n1. Provide a unified interface to the language specific dialects.\n1. Match semantic versions in a language agnostic way.\n1. Invert ranges.\n1. Cope with scattered, non-consecutive ranges.\n1. Parse and produce different version syntaxes.\n1. Parse and match versions/constraints in a best-effort manner.\n## SemVer versioning representation\nFirst, we need a generic representation of a semantic version to start with. We assume that a semantic version is composed of prefix and suffix where the prefix contains segments for major, minor and patch version components as defined in the\nSemVer specification. The suffix may hold additional information about pre/post releases etc. As illustrated below, the major, minor and patch prefix segments can be accessed by means of the corresponding methods.\n```ruby\ns1 = SemanticVersion.new('1.2.3')\nputs \"segments: #{s1}\"\n# segments: 1:2:3\nputs \"major #{s1.major}\"\n# major 1\nputs \"minor #{s1.minor}\"\n# minor 2\nputs \"patch #{s1.patch}\"\n# patch 3\n```\nWe cannot generally assume that all provided versions we would like to process fully adhere to the SemVer spec which requires a version prefix (core) to consist of three segments: major, minor and patch. Hence, per default, we remove redundant, trailing zeros from the prefix to ensure that `2.0.0`, `2.0` and `2` are considered identical.\n[Semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) translates language specific version suffixes into numeric values. This process can be described as version normalization.  For example the Maven (pre-)release candidate version `2.0.0.RC1` can be translated to a numeric representation with prefix: `2` and suffix `-1:1` by mapping `RC` to a numeric value (in this example `-1`) and, thus, rendering it numerically comparable.\nAfter this normalization step, semantic version matching for two versions `vA` and `vB` can be implemented by simply numerically comparing their segments in a pairwise fashion.  For unknown suffices that are not mappable to the numeric domain, we use lexical matching as a default fallback strategy.\nIn summary, comparing two semantic versions is a two-step process:\n1. Normalization: Extend both semantic versions to have the same prefix length and suffix lengths by appending zeros. 1. Comparison: Iterate over segments and compare each of them numerically.\nFor example, after normalizing the versions `2.0.0.RC1` and `2.0.0` to `2:-1:1` and `2:0:0`, respectively, we can iterate over the segments (delimited by `:` in the example) which we can compare numerically to successfully identify `2:-1:1` as being the smaller (release-candidate) version in comparison to `2:0:0`.\n## Constraint syntax - everything is a linear interval\nTranslating semantic versions into a generic representation makes them numerically comparable which is already useful but not sufficient to express SemVer versioning constraints in a language-agnostic fashion.\nFor representing semantic version constraints in a generic way, we rely on linear intervals.  For the purpose of this blog, we define an interval as an ordered pair of two semantic versions which we are referring to as lower and upper bounds (or cuts). For the sake of simplicity, for the remainder of this section we will use simple integers as examples for lower and upper bounds, respectively.\nLinear intervals capture semantic version ranges symbolically which makes them very versatile and space efficient. At the same time, we can rely on well-established mathematical models borrowed from linear interval arithmetic that enable us to translate/express any type of constraint in terms of mathematical set operations on intervals.\nIn the table below you can find all the different types of intervals we considered to model semantic version constraints and a corresponding description where `L` stands for left, `R` stands for right with `a` and `b` being the lower and upper bounds, respectively.\n| Type of interval | Example                    | Description                               |\n| ---------------- | ---------------------------| ----------------------------------------- |\n| LR-closed        |  `[a,b]: x >= a, x \u003C= b`   | all versions starting from a until b      |\n| L-open R-closed  |  `(a,b]: x > a, x \u003C= b`    | all versions after a until b              |\n| L-closed R-open  |  `[a,b): x >= a, x \u003C b`    | all versions starting from a before b     |\n| LR-open          |  `(a,b): x > a, x \u003C b`     | all versions between a and b              |\n| L-unbounded      |  `(-inf,b]: x \u003C= b`        | all versions until b                      |\n| R-unbounded      |  `[a,+inf): x >= a`        | all versions starting from a              |\nBelow you can see example output for the different types of ranges from [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) where we are using the `VersionParser` component to generate linear intervals from version constraints where `,` denotes a logical conjunction: e.g., `>=1, \u003C=2` denotes the set of integers that are greater than or equal to 1 *and* smaller than or equal to two, i.e., all integers/versions numbers starting from 1 until 2.\n```ruby\nputs VersionParser.parse(\">=1, \u003C=2\")\n# [1,2]\nputs VersionParser.parse(\">1, \u003C=2\")\n# (1,2]\nputs VersionParser.parse(\">=1, \u003C2\")\n# [1,2)\nputs VersionParser.parse(\">1, \u003C2\")\n# (1,2)\nputs VersionParser.parse(\"\u003C=2\")\n# (-inf,2]\nputs VersionParser.parse(\">=1\")\n# [1,+inf)\n```\nFor solving SemVer versioning constraints, we use linear interval arithmetic which is explained in-depth in the text-book \"[Introduction to Interval\nAnalysis](https://epubs.siam.org/doi/book/10.1137/1.9780898717716?mobileUi=0&).\"\nAs mentioned earlier, for our purposes, we define an interval as an ordered pair of two semantic versions (lower and upper bound) that represents the set of all those semantic versions that are enclosed by lower and upper bounds.\nGiven that intervals are sets, we can perform standard set operations on them.\nIn the context of advisory generation, there are three operations we require to satisfy all the requirements we defined earlier: Intersection, Union and Complement.\nThe operations are explained in more detail in the sections below.\nFor the remainder of this section, we explain interval operations, using two example intervals `X` and `Y` with `X=[x_l, x_u]` and `Y=[y_l, y_u]` where `x_l`, `x_u` denote the lower and upper bounds for `X`, and `y_l`, `y_u` denote the lower and upper bounds for `Y`, respectively. In addition, we are using the `min` and `max` functions, where `max(a,b)` returns the largest and `min(a,b)` returns the smallest value of the parameters `a` and `b`; the ∅ symbol denotes the empty set.\n### Intersection\nThe recipe below illustrates how the intersection (`X` ∩ `Y`) can be computed.\n`X` ∩ `Y` = if `X` and `Y` have points in common `[max(x_l,y_l), min(x_u,y_u)]` else ∅\nIntuitively, the intersection extracts the overlap (if any) from the two intervals `X` and `Y`.\nThe code snippet below shows how the intersection is computed in [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) for the two examples:\n1. `[2,5]` ∩ `[3,10]`\n1. `[2,5]` ∩ `[7,10]`\n```ruby\n# 1. [2,5] ∩ [3,10] = [3, 5]\nputs VersionParser.parse(\">=2, \u003C=5\").intersect(VersionParser.parse(\">=3, \u003C=10\"))\n# [3,5]\n\n# 2. [2,5] ∩ [7,10] = ∅\nputs VersionParser.parse(\">=2, \u003C=5\").intersect(VersionParser.parse(\">=7, \u003C=10\"))\n# empty\n```\nThe intersection operation is useful to perform semantic version matching for checking whether semantic version falls into a certain version interval or range. For instance we may want to check whether version `1.2.3` satisfies the constraint `>=1.0.0, \u003C1.2.4`. In the context of [Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/), these types of constraints are very common. The problem `1.2.3` ∈ `[1.0.0, 1.2.4)` can be translated to a set intersection: `[1.2.3, 1.2.3]` ∩ `[1.0.0, 1.2.4)` = `[1.2.3, 1.2.3]`  which returns a non-empty set and, hence, tells us that version `1.2.3` satisfies the given version constraints.\nIn the context of our advisory generation process, we use intersection to cross-validate versions from vulnerability reports (CVEs) with versions of the available package that are available on the package registry that serves it.\nFor convenience, as mentioned earlier, [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) also supports grouping intervals into ranges by means of the `VersionRange` class. A range is a set of intervals which we denote with `{I0, I1, ..., IN}` where `I` denotes version intervals delimited by `,` which can be interpreted as a union operator (explained in the next section).\nA range is a set of intervals. In the example below, we first create a range `r1` to which we are adding two intervals: `r1 = {[2.2.1, 5.1.2], (3.1, 10)}`.\nAfter that, there is a check for an overlap (i.e., an intersection) between `r1` and `[0, 2.1)` (no overlap) as well as `[5.5, 5.5]` (overlap). You can see the output of [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) in the excerpt below.\n```ruby\nr1 = VersionRange.new\nr1.add(VersionParser.parse(\">=2.1.2, \u003C=5.1.2\"))\nr1.add(VersionParser.parse(\">3.1, \u003C10\"))\n\nputs \"[0,2.1) in #{r1}? #{r1.overlaps_with?(VersionParser.parse(\">=0, \u003C2.1\"))}\"\n# [0,2.1) in [2.1.2,5.1.2],(3.1,10)? false\nputs \"[5.5,5.5] overlap with #{r1}? #{r1.overlaps_with?(VersionParser.parse(\"=5.5\"))}\"\n# [5.5,5.5] overlap with [2.1.2,5.1.2],(3.1,10)? true\n```\n### Union\nThe recipe below illustrates how the union (`X` ∪ `Y`) can be computed.\n`X` ∪ `Y` = if `X` and `Y` have points in common `{[min(x_l,y_l), max(x_u,y_u)]}` else `{X,Y}`\nThe code snippet below shows how the union can be computed with [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) for the two examples: 1. `[2,5]` ∪ `[3,10]` = `{[2,5], [3,10]}` = `{[2, 10]}`\n2. `[2,5]` ∪ `[7,10]` = `{[2,5], [7,10]}`\nWith the union operator, we can collapse version intervals in case they have an overlap/intersection; otherwise, if `X` and `Y` are disjoint, we add their intervals directly to the range.\n```ruby\n# 1. [2,5] ∪ [3,10] = [2, 10]\nputs \"union: #{VersionParser.parse(\">=2, \u003C=5\").union(VersionParser.parse(\">=3, \u003C=10\"))}\"\n# union: [2,10]\n\n# Version ranges perform union two for the purpose of automatically collapsing\n# intervals (if possible)\nr1 = VersionRange.new\nr1.add(VersionParser.parse(\">=2, \u003C=5\"))\nr1.add(VersionParser.parse(\">=3, \u003C=10\"))\nputs \"r1: #{r1}\"\n# union: [2,5],[3,10]\nputs \"r1 collapsed: #{r1.collapse}\" # creates the union between intervals\n# r1 collapsed: [2,10]\n\n# 2. [2,5] ∪ [7,10] = {[2, 10], [7,10]}\nr2 = VersionRange.new\nr2.add(VersionParser.parse(\">=2, \u003C=5\"))\nr2.add(VersionParser.parse(\">=7, \u003C=10\"))\nputs \"r2: #{r2}\"\n# r2: [2,5],[7,10]\n```\nIn the context of [Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/), vulnerability data usually lists a set of intervals for dependencies that are susceptible to a given vulnerability like the [tensorflow example](https://nvd.nist.gov/vuln/detail/CVE-2021-29560) in the introduction where the following versions are affected:\n1. up to 2.1.4\n1. from 2.2.0 up to 2.2.3\n1. from 2.3.0 up to 2.3.3\n1. from 2.4.0 up to 2.4.2\nThis list of intervals can be represented as a single range (`VersionRange`) by combining all of the mentioned version intervals through the union operator.\nIn the Ruby code example above, you can also see the `collapse` method which is invoked on a `VersionRange` object. This method automatically collapses overlapping intervals that are included in the same `VersionRange` to eliminate redundant intervals. Collapsing the range `{[2, 5], [3, 10]}` yields a new range `{[2,10]}` with only one interval while preserving semantic equivalence.\n### Complement\nThe recipe below, illustrates how the relative complement (`X` - `Y`) can be computed.\n`X` - `Y`: `Z` := `X` ∩ `Y`; if (`z_l` > `x_l` && `z_u` \u003C `x_u`)\n          `{[x_l, z_l),(z_u, x_u]}` else if (`x_l` \u003C `z_l`)\n          `{[x_l, z_l)}` else if (`x_u` > `z_u`)\n          `{(z_u, x_u]}`\n\nIntuitively, this recipe computes the intersection (`Z`) between `X` and `Y` and removes all elements from `X` that are included in the intersection. The examples below illustrate the recipe:\n1. `[3, 5]` - `[1, 3]`: with `Z` = `[3, 3]` we get `{(3, 5]}` which is\n   equivalent to `{[4, 5]}`\n1. `[3, 10]` - `[10, 11]`: with `Z` = `[10, 10]` we get `{[3, 10)}` which is equivalent to `{[3, 9]}`\n1. `[1, 5]` - `[2, 2]`: with `Z` = `[2, 2]` we get `[1, 2), (2, 5]` which is equivalent to `{[1, 1], [3, 5]}`\nWith the recipe above, we can also compute the absolute complement `X` - `Y` by assuming `X` is the universe that captures the entirety of all possible values:\n`(-inf,+inf)`. The universal complement can be defined as `~X` = `(-inf,+inf)` - `X`.\nWith [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects), the absolute complement can be computed by means of the `invert` method as illustrated in the example below.\n```ruby\n# example 1: ~[1,3] = {(-inf,0],[4, +inf)} = {(-inf,1),(3,+inf)}\nr1 = VersionRange.new\nr1.add(VersionParser.parse(\">=1, \u003C=3\"))\nputs r1.invert\n# (-inf,1),(3,+inf)\n\n# example 2: ~{[2.1.2, 5.1.2], (3.1, 10)} = ~{[2.1.2, 10)} = {(-inf,2.1.2),[10,+inf)}\n{(-inf,0],[4, +inf)} = {(-inf,1),(3,+inf)}\nr2 = VersionRange.new\nr2.add(VersionParser.parse(\">=2.1.2, \u003C=5.1.2\"))\nr2.add(VersionParser.parse(\">3.1, \u003C10\"))\nputs r2.collapse.invert\n# (-inf,2.1.2),[10,+inf)\n```\nIn the context of [Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/), this functionality is used to automatically infer non-affected versions from the affected versions information: if `[1, 3]` represents all the affected versions of a vulnerable package, its complement `{(-inf,1),(3,+inf)}`, per definition, captures only the unaffected version. In our advisory generation process we cross-validate the version information of packages from the package registries with this information about unaffected versions to check whether or not unaffected packages are available; if this is the case, we add the corresponding remediation information to the generated advisories.\n## Version Translation\nLinear interval arithmetic provides us with all the means necessary to represent and solve SemVer versioning constraints in a language-agnostic way.\nHowever, in order to leverage the generic representation, we have to be able to automatically translate the native semantic version dialects into the generic representation and vice versa. The details of this translation functionality are provided below.\n[Semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) offers a `VersionTranslator` class. The `VersionTranslator` takes a native semantic version constraint, and translates it into an intermediate string representation that can then be translated into a range (`VersionRange`) by using the `VersionParser`. Currently semver_dialects supports all the syntax listed below by invoking `translate_\u003Cpackage_type>` where `\u003Cpackage_type>` is one of:\n- `gem`: [gem requirement](https://guides.rubygems.org/specification-reference/#add_runtime_dependency)\n- `maven`: [Maven Dependency Version Requirement Specification](https://maven.apache.org/pom.html#Dependency_Version_Requirement_Specification)\n- `npm`: [node-semver](https://github.com/npm/node-semver#ranges)\n- `packagist`: [PHP Composer version constraints](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints)\n- `pypi`: [PEP440](https://www.python.org/dev/peps/pep-0440/#version-specifiers)\n- `go`: [go semver](https://godoc.org/golang.org/x/tools/internal/semver)\n- `nuget`: [NuGet semver](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning)\n- `conan`: [node-semver flavour](https://github.com/npm/node-semver#ranges)\nThe example below illustrates how the [semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects)' `VersionTranslator` can be used to translate native version syntax to an intermediate representation.\nThe `VersionTranslator` parses the native version syntax and translates it into a common format. In the example below, you can further see that both native, semantically equivalent but syntactically different version strings for packagist and maven are translated into a common format: a string array where a single array entry represents a conjunct of the semantic version constraints. This translation step removes all language-specific features from the native semantic version constraints.\n```ruby\n# native packagist version constraint syntax\nvs_packagist = \"\u003C2.5.9||>=2.6.0,\u003C2.6.11\"\n# native maven version constraint syntax\nvs_maven = \"(,2.5.9),[2.6.0,2.6.11)\"\n\n# translate\nputs VersionTranslator.translate_packagist(vs_packagist).to_s\n# [\"\u003C2.5.9\", \">=2.6.0 \u003C2.6.11\"]\nputs VersionTranslator.translate_maven(vs_maven).to_s\n# [\"\u003C2.5.9\", \">=2.6.0 \u003C2.6.11\"]\n```\nThis common format can then be translated to a version interval by means of `VersionParser` and `VersionRange`. The example below illustrates how the version interval `constraint` is generated by iterating over the array elements of our intermediate representation, translating them to intervals and adding these intervals to the `VersionRange` object `constraint`. At the end of the excerpt below, we check whether version `1.0.0` satisfies the version constraint `\u003C2.5.9||>=2.6.0,\u003C2.6.11` which correctly yields `true`.\n```ruby\n# translate native maven version constraint to range of interval\nconstraint = VersionRange.new\nVersionTranslator.translate_maven(vs_maven).each do |version_string|\n  constraint \u003C\u003C VersionParser.parse(version_string)\nend\n\nputs constraint.overlaps_with?(VersionParser.parse('=' + '1.0.0'))\n# true\n```\n## Wrapping it up\nWe discussed the fragmentation of SemVer versioning which poses a challenge when building automation around semantic version processing for multi-language/ecosystem applications. In this blog post, we used our internal semi-automated process for advisory generation as an example.\nWe illustrated how we tackled the above-mentioned challenge by building a generic/language-agnostic semantic version approach based on linear interval arithmetic. All mechanisms discussed in this blog post are implemented in the open-sourced (MIT)\n[semver_dialects](https://gitlab.com/gitlab-org/vulnerability-research/foss/semver_dialects) implementation and published on [rubygems.org](https://rubygems.org/gems/semver_dialects).\n",[9,23,24],"DevOps","open source","yml",{},true,"/en-us/blog/generic-semantic-version-processing",{"title":15,"description":16,"ogTitle":15,"ogDescription":16,"noIndex":12,"ogImage":19,"ogUrl":30,"ogSiteName":31,"ogType":32,"canonicalUrls":30},"https://about.gitlab.com/blog/generic-semantic-version-processing","https://about.gitlab.com","article","en-us/blog/generic-semantic-version-processing",[9,35,36],"devops","open-source","GeKmo0qa8bpbkrR5Q2x9ngrxYntqsn-gBfWALS_XaDo",{"data":39},{"logo":40,"freeTrial":45,"sales":50,"login":55,"items":60,"search":368,"minimal":399,"duo":418,"pricingDeployment":428},{"config":41},{"href":42,"dataGaName":43,"dataGaLocation":44},"/","gitlab logo","header",{"text":46,"config":47},"Get free trial",{"href":48,"dataGaName":49,"dataGaLocation":44},"https://gitlab.com/-/trial_registrations/new?glm_source=about.gitlab.com&glm_content=default-saas-trial/","free trial",{"text":51,"config":52},"Talk to sales",{"href":53,"dataGaName":54,"dataGaLocation":44},"/sales/","sales",{"text":56,"config":57},"Sign in",{"href":58,"dataGaName":59,"dataGaLocation":44},"https://gitlab.com/users/sign_in/","sign in",[61,88,183,188,289,349],{"text":62,"config":63,"cards":65},"Platform",{"dataNavLevelOne":64},"platform",[66,72,80],{"title":62,"description":67,"link":68},"The intelligent orchestration platform for DevSecOps",{"text":69,"config":70},"Explore our Platform",{"href":71,"dataGaName":64,"dataGaLocation":44},"/platform/",{"title":73,"description":74,"link":75},"GitLab Duo Agent Platform","Agentic AI for the entire software lifecycle",{"text":76,"config":77},"Meet GitLab Duo",{"href":78,"dataGaName":79,"dataGaLocation":44},"/gitlab-duo-agent-platform/","gitlab duo agent platform",{"title":81,"description":82,"link":83},"Why GitLab","See the top reasons enterprises choose GitLab",{"text":84,"config":85},"Learn more",{"href":86,"dataGaName":87,"dataGaLocation":44},"/why-gitlab/","why gitlab",{"text":89,"left":27,"config":90,"link":92,"lists":96,"footer":165},"Product",{"dataNavLevelOne":91},"solutions",{"text":93,"config":94},"View all Solutions",{"href":95,"dataGaName":91,"dataGaLocation":44},"/solutions/",[97,121,144],{"title":98,"description":99,"link":100,"items":105},"Automation","CI/CD and automation to accelerate deployment",{"config":101},{"icon":102,"href":103,"dataGaName":104,"dataGaLocation":44},"AutomatedCodeAlt","/solutions/delivery-automation/","automated software delivery",[106,110,113,117],{"text":107,"config":108},"CI/CD",{"href":109,"dataGaLocation":44,"dataGaName":107},"/solutions/continuous-integration/",{"text":73,"config":111},{"href":78,"dataGaLocation":44,"dataGaName":112},"gitlab duo agent platform - product menu",{"text":114,"config":115},"Source Code Management",{"href":116,"dataGaLocation":44,"dataGaName":114},"/solutions/source-code-management/",{"text":118,"config":119},"Automated Software Delivery",{"href":103,"dataGaLocation":44,"dataGaName":120},"Automated software delivery",{"title":122,"description":123,"link":124,"items":129},"Security","Deliver code faster without compromising security",{"config":125},{"href":126,"dataGaName":127,"dataGaLocation":44,"icon":128},"/solutions/application-security-testing/","security and compliance","ShieldCheckLight",[130,134,139],{"text":131,"config":132},"Application Security Testing",{"href":126,"dataGaName":133,"dataGaLocation":44},"Application security testing",{"text":135,"config":136},"Software Supply Chain Security",{"href":137,"dataGaLocation":44,"dataGaName":138},"/solutions/supply-chain/","Software supply chain security",{"text":140,"config":141},"Software Compliance",{"href":142,"dataGaName":143,"dataGaLocation":44},"/solutions/software-compliance/","software compliance",{"title":145,"link":146,"items":151},"Measurement",{"config":147},{"icon":148,"href":149,"dataGaName":150,"dataGaLocation":44},"DigitalTransformation","/solutions/visibility-measurement/","visibility and measurement",[152,156,160],{"text":153,"config":154},"Visibility & Measurement",{"href":149,"dataGaLocation":44,"dataGaName":155},"Visibility and Measurement",{"text":157,"config":158},"Value Stream Management",{"href":159,"dataGaLocation":44,"dataGaName":157},"/solutions/value-stream-management/",{"text":161,"config":162},"Analytics & Insights",{"href":163,"dataGaLocation":44,"dataGaName":164},"/solutions/analytics-and-insights/","Analytics and insights",{"title":166,"items":167},"GitLab for",[168,173,178],{"text":169,"config":170},"Enterprise",{"href":171,"dataGaLocation":44,"dataGaName":172},"/enterprise/","enterprise",{"text":174,"config":175},"Small Business",{"href":176,"dataGaLocation":44,"dataGaName":177},"/small-business/","small business",{"text":179,"config":180},"Public Sector",{"href":181,"dataGaLocation":44,"dataGaName":182},"/solutions/public-sector/","public sector",{"text":184,"config":185},"Pricing",{"href":186,"dataGaName":187,"dataGaLocation":44,"dataNavLevelOne":187},"/pricing/","pricing",{"text":189,"config":190,"link":192,"lists":196,"feature":276},"Resources",{"dataNavLevelOne":191},"resources",{"text":193,"config":194},"View all resources",{"href":195,"dataGaName":191,"dataGaLocation":44},"/resources/",[197,230,248],{"title":198,"items":199},"Getting started",[200,205,210,215,220,225],{"text":201,"config":202},"Install",{"href":203,"dataGaName":204,"dataGaLocation":44},"/install/","install",{"text":206,"config":207},"Quick start guides",{"href":208,"dataGaName":209,"dataGaLocation":44},"/get-started/","quick setup checklists",{"text":211,"config":212},"Learn",{"href":213,"dataGaLocation":44,"dataGaName":214},"https://university.gitlab.com/","learn",{"text":216,"config":217},"Product documentation",{"href":218,"dataGaName":219,"dataGaLocation":44},"https://docs.gitlab.com/","product documentation",{"text":221,"config":222},"Best practice videos",{"href":223,"dataGaName":224,"dataGaLocation":44},"/getting-started-videos/","best practice videos",{"text":226,"config":227},"Integrations",{"href":228,"dataGaName":229,"dataGaLocation":44},"/integrations/","integrations",{"title":231,"items":232},"Discover",[233,238,243],{"text":234,"config":235},"Customer success stories",{"href":236,"dataGaName":237,"dataGaLocation":44},"/customers/","customer success stories",{"text":239,"config":240},"Blog",{"href":241,"dataGaName":242,"dataGaLocation":44},"/blog/","blog",{"text":244,"config":245},"Remote",{"href":246,"dataGaName":247,"dataGaLocation":44},"https://handbook.gitlab.com/handbook/company/culture/all-remote/","remote",{"title":249,"items":250},"Connect",[251,256,261,266,271],{"text":252,"config":253},"GitLab Services",{"href":254,"dataGaName":255,"dataGaLocation":44},"/services/","services",{"text":257,"config":258},"Community",{"href":259,"dataGaName":260,"dataGaLocation":44},"/community/","community",{"text":262,"config":263},"Forum",{"href":264,"dataGaName":265,"dataGaLocation":44},"https://forum.gitlab.com/","forum",{"text":267,"config":268},"Events",{"href":269,"dataGaName":270,"dataGaLocation":44},"/events/","events",{"text":272,"config":273},"Partners",{"href":274,"dataGaName":275,"dataGaLocation":44},"/partners/","partners",{"backgroundColor":277,"textColor":278,"text":279,"image":280,"link":284},"#2f2a6b","#fff","Insights for the future of software development",{"altText":281,"config":282},"the source promo card",{"src":283},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1758208064/dzl0dbift9xdizyelkk4.svg",{"text":285,"config":286},"Read the latest",{"href":287,"dataGaName":288,"dataGaLocation":44},"/the-source/","the source",{"text":290,"config":291,"lists":293},"Company",{"dataNavLevelOne":292},"company",[294],{"items":295},[296,301,307,309,314,319,324,329,334,339,344],{"text":297,"config":298},"About",{"href":299,"dataGaName":300,"dataGaLocation":44},"/company/","about",{"text":302,"config":303,"footerGa":306},"Jobs",{"href":304,"dataGaName":305,"dataGaLocation":44},"/jobs/","jobs",{"dataGaName":305},{"text":267,"config":308},{"href":269,"dataGaName":270,"dataGaLocation":44},{"text":310,"config":311},"Leadership",{"href":312,"dataGaName":313,"dataGaLocation":44},"/company/team/e-group/","leadership",{"text":315,"config":316},"Team",{"href":317,"dataGaName":318,"dataGaLocation":44},"/company/team/","team",{"text":320,"config":321},"Handbook",{"href":322,"dataGaName":323,"dataGaLocation":44},"https://handbook.gitlab.com/","handbook",{"text":325,"config":326},"Investor relations",{"href":327,"dataGaName":328,"dataGaLocation":44},"https://ir.gitlab.com/","investor relations",{"text":330,"config":331},"Trust Center",{"href":332,"dataGaName":333,"dataGaLocation":44},"/security/","trust center",{"text":335,"config":336},"AI Transparency Center",{"href":337,"dataGaName":338,"dataGaLocation":44},"/ai-transparency-center/","ai transparency center",{"text":340,"config":341},"Newsletter",{"href":342,"dataGaName":343,"dataGaLocation":44},"/company/contact/#contact-forms","newsletter",{"text":345,"config":346},"Press",{"href":347,"dataGaName":348,"dataGaLocation":44},"/press/","press",{"text":350,"config":351,"lists":352},"Contact us",{"dataNavLevelOne":292},[353],{"items":354},[355,358,363],{"text":51,"config":356},{"href":53,"dataGaName":357,"dataGaLocation":44},"talk to sales",{"text":359,"config":360},"Support portal",{"href":361,"dataGaName":362,"dataGaLocation":44},"https://support.gitlab.com","support portal",{"text":364,"config":365},"Customer portal",{"href":366,"dataGaName":367,"dataGaLocation":44},"https://customers.gitlab.com/customers/sign_in/","customer portal",{"close":369,"login":370,"suggestions":377},"Close",{"text":371,"link":372},"To search repositories and projects, login to",{"text":373,"config":374},"gitlab.com",{"href":58,"dataGaName":375,"dataGaLocation":376},"search login","search",{"text":378,"default":379},"Suggestions",[380,382,386,388,392,396],{"text":73,"config":381},{"href":78,"dataGaName":73,"dataGaLocation":376},{"text":383,"config":384},"Code Suggestions (AI)",{"href":385,"dataGaName":383,"dataGaLocation":376},"/solutions/code-suggestions/",{"text":107,"config":387},{"href":109,"dataGaName":107,"dataGaLocation":376},{"text":389,"config":390},"GitLab on AWS",{"href":391,"dataGaName":389,"dataGaLocation":376},"/partners/technology-partners/aws/",{"text":393,"config":394},"GitLab on Google Cloud",{"href":395,"dataGaName":393,"dataGaLocation":376},"/partners/technology-partners/google-cloud-platform/",{"text":397,"config":398},"Why GitLab?",{"href":86,"dataGaName":397,"dataGaLocation":376},{"freeTrial":400,"mobileIcon":405,"desktopIcon":410,"secondaryButton":413},{"text":401,"config":402},"Start free trial",{"href":403,"dataGaName":49,"dataGaLocation":404},"https://gitlab.com/-/trials/new/","nav",{"altText":406,"config":407},"Gitlab Icon",{"src":408,"dataGaName":409,"dataGaLocation":404},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1758203874/jypbw1jx72aexsoohd7x.svg","gitlab icon",{"altText":406,"config":411},{"src":412,"dataGaName":409,"dataGaLocation":404},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1758203875/gs4c8p8opsgvflgkswz9.svg",{"text":414,"config":415},"Get Started",{"href":416,"dataGaName":417,"dataGaLocation":404},"https://gitlab.com/-/trial_registrations/new?glm_source=about.gitlab.com/get-started/","get started",{"freeTrial":419,"mobileIcon":424,"desktopIcon":426},{"text":420,"config":421},"Learn more about GitLab Duo",{"href":422,"dataGaName":423,"dataGaLocation":404},"/gitlab-duo/","gitlab duo",{"altText":406,"config":425},{"src":408,"dataGaName":409,"dataGaLocation":404},{"altText":406,"config":427},{"src":412,"dataGaName":409,"dataGaLocation":404},{"freeTrial":429,"mobileIcon":434,"desktopIcon":436},{"text":430,"config":431},"Back to pricing",{"href":186,"dataGaName":432,"dataGaLocation":404,"icon":433},"back to pricing","GoBack",{"altText":406,"config":435},{"src":408,"dataGaName":409,"dataGaLocation":404},{"altText":406,"config":437},{"src":412,"dataGaName":409,"dataGaLocation":404},{"title":439,"button":440,"config":445},"See how agentic AI transforms software delivery",{"text":441,"config":442},"Watch GitLab Transcend now",{"href":443,"dataGaName":444,"dataGaLocation":44},"/events/transcend/virtual/","transcend event",{"layout":446,"icon":447},"release","AiStar",{"data":449},{"text":450,"source":451,"edit":457,"contribute":462,"config":467,"items":472,"minimal":677},"Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license",{"text":452,"config":453},"View page source",{"href":454,"dataGaName":455,"dataGaLocation":456},"https://gitlab.com/gitlab-com/marketing/digital-experience/about-gitlab-com/","page source","footer",{"text":458,"config":459},"Edit this page",{"href":460,"dataGaName":461,"dataGaLocation":456},"https://gitlab.com/gitlab-com/marketing/digital-experience/about-gitlab-com/-/blob/main/content/","web ide",{"text":463,"config":464},"Please contribute",{"href":465,"dataGaName":466,"dataGaLocation":456},"https://gitlab.com/gitlab-com/marketing/digital-experience/about-gitlab-com/-/blob/main/CONTRIBUTING.md/","please contribute",{"twitter":468,"facebook":469,"youtube":470,"linkedin":471},"https://twitter.com/gitlab","https://www.facebook.com/gitlab","https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg","https://www.linkedin.com/company/gitlab-com",[473,520,572,616,643],{"title":184,"links":474,"subMenu":489},[475,479,484],{"text":476,"config":477},"View plans",{"href":186,"dataGaName":478,"dataGaLocation":456},"view plans",{"text":480,"config":481},"Why Premium?",{"href":482,"dataGaName":483,"dataGaLocation":456},"/pricing/premium/","why premium",{"text":485,"config":486},"Why Ultimate?",{"href":487,"dataGaName":488,"dataGaLocation":456},"/pricing/ultimate/","why ultimate",[490],{"title":491,"links":492},"Contact Us",[493,496,498,500,505,510,515],{"text":494,"config":495},"Contact sales",{"href":53,"dataGaName":54,"dataGaLocation":456},{"text":359,"config":497},{"href":361,"dataGaName":362,"dataGaLocation":456},{"text":364,"config":499},{"href":366,"dataGaName":367,"dataGaLocation":456},{"text":501,"config":502},"Status",{"href":503,"dataGaName":504,"dataGaLocation":456},"https://status.gitlab.com/","status",{"text":506,"config":507},"Terms of use",{"href":508,"dataGaName":509,"dataGaLocation":456},"/terms/","terms of use",{"text":511,"config":512},"Privacy statement",{"href":513,"dataGaName":514,"dataGaLocation":456},"/privacy/","privacy statement",{"text":516,"config":517},"Cookie preferences",{"dataGaName":518,"dataGaLocation":456,"id":519,"isOneTrustButton":27},"cookie preferences","ot-sdk-btn",{"title":89,"links":521,"subMenu":530},[522,526],{"text":523,"config":524},"DevSecOps platform",{"href":71,"dataGaName":525,"dataGaLocation":456},"devsecops platform",{"text":527,"config":528},"AI-Assisted Development",{"href":422,"dataGaName":529,"dataGaLocation":456},"ai-assisted development",[531],{"title":532,"links":533},"Topics",[534,539,544,547,552,557,562,567],{"text":535,"config":536},"CICD",{"href":537,"dataGaName":538,"dataGaLocation":456},"/topics/ci-cd/","cicd",{"text":540,"config":541},"GitOps",{"href":542,"dataGaName":543,"dataGaLocation":456},"/topics/gitops/","gitops",{"text":23,"config":545},{"href":546,"dataGaName":35,"dataGaLocation":456},"/topics/devops/",{"text":548,"config":549},"Version Control",{"href":550,"dataGaName":551,"dataGaLocation":456},"/topics/version-control/","version control",{"text":553,"config":554},"DevSecOps",{"href":555,"dataGaName":556,"dataGaLocation":456},"/topics/devsecops/","devsecops",{"text":558,"config":559},"Cloud Native",{"href":560,"dataGaName":561,"dataGaLocation":456},"/topics/cloud-native/","cloud native",{"text":563,"config":564},"AI for Coding",{"href":565,"dataGaName":566,"dataGaLocation":456},"/topics/devops/ai-for-coding/","ai for coding",{"text":568,"config":569},"Agentic AI",{"href":570,"dataGaName":571,"dataGaLocation":456},"/topics/agentic-ai/","agentic ai",{"title":573,"links":574},"Solutions",[575,577,579,584,588,591,595,598,600,603,606,611],{"text":131,"config":576},{"href":126,"dataGaName":131,"dataGaLocation":456},{"text":120,"config":578},{"href":103,"dataGaName":104,"dataGaLocation":456},{"text":580,"config":581},"Agile development",{"href":582,"dataGaName":583,"dataGaLocation":456},"/solutions/agile-delivery/","agile delivery",{"text":585,"config":586},"SCM",{"href":116,"dataGaName":587,"dataGaLocation":456},"source code management",{"text":535,"config":589},{"href":109,"dataGaName":590,"dataGaLocation":456},"continuous integration & delivery",{"text":592,"config":593},"Value stream management",{"href":159,"dataGaName":594,"dataGaLocation":456},"value stream management",{"text":540,"config":596},{"href":597,"dataGaName":543,"dataGaLocation":456},"/solutions/gitops/",{"text":169,"config":599},{"href":171,"dataGaName":172,"dataGaLocation":456},{"text":601,"config":602},"Small business",{"href":176,"dataGaName":177,"dataGaLocation":456},{"text":604,"config":605},"Public sector",{"href":181,"dataGaName":182,"dataGaLocation":456},{"text":607,"config":608},"Education",{"href":609,"dataGaName":610,"dataGaLocation":456},"/solutions/education/","education",{"text":612,"config":613},"Financial services",{"href":614,"dataGaName":615,"dataGaLocation":456},"/solutions/finance/","financial services",{"title":189,"links":617},[618,620,622,624,627,629,631,633,635,637,639,641],{"text":201,"config":619},{"href":203,"dataGaName":204,"dataGaLocation":456},{"text":206,"config":621},{"href":208,"dataGaName":209,"dataGaLocation":456},{"text":211,"config":623},{"href":213,"dataGaName":214,"dataGaLocation":456},{"text":216,"config":625},{"href":218,"dataGaName":626,"dataGaLocation":456},"docs",{"text":239,"config":628},{"href":241,"dataGaName":242,"dataGaLocation":456},{"text":234,"config":630},{"href":236,"dataGaName":237,"dataGaLocation":456},{"text":244,"config":632},{"href":246,"dataGaName":247,"dataGaLocation":456},{"text":252,"config":634},{"href":254,"dataGaName":255,"dataGaLocation":456},{"text":257,"config":636},{"href":259,"dataGaName":260,"dataGaLocation":456},{"text":262,"config":638},{"href":264,"dataGaName":265,"dataGaLocation":456},{"text":267,"config":640},{"href":269,"dataGaName":270,"dataGaLocation":456},{"text":272,"config":642},{"href":274,"dataGaName":275,"dataGaLocation":456},{"title":290,"links":644},[645,647,649,651,653,655,657,661,666,668,670,672],{"text":297,"config":646},{"href":299,"dataGaName":292,"dataGaLocation":456},{"text":302,"config":648},{"href":304,"dataGaName":305,"dataGaLocation":456},{"text":310,"config":650},{"href":312,"dataGaName":313,"dataGaLocation":456},{"text":315,"config":652},{"href":317,"dataGaName":318,"dataGaLocation":456},{"text":320,"config":654},{"href":322,"dataGaName":323,"dataGaLocation":456},{"text":325,"config":656},{"href":327,"dataGaName":328,"dataGaLocation":456},{"text":658,"config":659},"Sustainability",{"href":660,"dataGaName":658,"dataGaLocation":456},"/sustainability/",{"text":662,"config":663},"Diversity, inclusion and belonging (DIB)",{"href":664,"dataGaName":665,"dataGaLocation":456},"/diversity-inclusion-belonging/","Diversity, inclusion and belonging",{"text":330,"config":667},{"href":332,"dataGaName":333,"dataGaLocation":456},{"text":340,"config":669},{"href":342,"dataGaName":343,"dataGaLocation":456},{"text":345,"config":671},{"href":347,"dataGaName":348,"dataGaLocation":456},{"text":673,"config":674},"Modern Slavery Transparency Statement",{"href":675,"dataGaName":676,"dataGaLocation":456},"https://handbook.gitlab.com/handbook/legal/modern-slavery-act-transparency-statement/","modern slavery transparency statement",{"items":678},[679,682,685],{"text":680,"config":681},"Terms",{"href":508,"dataGaName":509,"dataGaLocation":456},{"text":683,"config":684},"Cookies",{"dataGaName":518,"dataGaLocation":456,"id":519,"isOneTrustButton":27},{"text":686,"config":687},"Privacy",{"href":513,"dataGaName":514,"dataGaLocation":456},[689],{"id":690,"title":18,"body":8,"config":691,"content":693,"description":8,"extension":25,"meta":697,"navigation":27,"path":698,"seo":699,"stem":700,"__hash__":701},"blogAuthors/en-us/blog/authors/julian-thome.yml",{"template":692},"BlogAuthor",{"name":18,"config":694},{"headshot":695,"ctfId":696},"","jthome",{},"/en-us/blog/authors/julian-thome",{},"en-us/blog/authors/julian-thome","60j2yTW0PuY7q83cXf4NkfzrKTRE2sUlVv5TXE6o1xM",[703,716,731],{"content":704,"config":714},{"title":705,"description":706,"authors":707,"tags":709,"heroImage":711,"category":9,"date":712,"body":713},"A complete guide to GitLab Container Scanning","Explore GitLab's various container scanning methods and learn how to secure containers at every lifecycle stage.",[708],"Fernando Diaz",[9,710],"tutorial","https://res.cloudinary.com/about-gitlab-com/image/upload/v1772721753/frfsm1qfscwrmsyzj1qn.png","2026-03-05","Container vulnerabilities don't wait for your next deployment. They can emerge at any\npoint, including when you build an image or while containers run in production.\nGitLab addresses this reality with multiple container scanning approaches, each designed\nfor different stages of your container lifecycle.\n\nIn this guide, we'll explore the different types of container scanning GitLab offers,\nhow to enable each one, and common configurations to get you started.\n\n## Why container scanning matters\n\nSecurity vulnerabilities in container images create risk throughout your application\nlifecycle. Base images, OS packages, and application dependencies can all harbor\nvulnerabilities that attackers actively exploit. Container scanning detects these risks\nearly, before they reach production, and provides remediation paths when available.\n\nContainer scanning is a critical component of Software Composition Analysis (SCA),\nhelping you understand and secure the external dependencies your containerized\napplications rely on.\n\n## The five types of GitLab Container Scanning\n\nGitLab offers five distinct container scanning approaches, each serving a specific\npurpose in your security strategy.\n\n\n### 1. Pipeline-based Container Scanning\n\n* What it does: Scans container images during your CI/CD pipeline execution,\ncatching vulnerabilities before deployment\n\n* Best for: Shift-left security, blocking vulnerable images from reaching production \n\n* Tier availability: Free, Premium, and Ultimate (with enhanced features in Ultimate)  \n\n* [Documentation](https://docs.gitlab.com/user/application_security/container_scanning/)\n\n\nGitLab uses the Trivy security scanner to analyze container images for\nknown vulnerabilities. When your pipeline runs, the scanner examines your images\nand generates a detailed report.\n\n\n#### How to enable pipeline-based Container Scanning \n\n**Option A: Preconfigured merge request**  \n\n* Navigate to **Secure > Security configuration** in your project.\n* Find the \"Container Scanning\" row.\n* Select **Configure with a merge request**.\n* This automatically creates a merge request with the necessary configuration.  \n\n**Option B: Manual configuration**  \n\n* Add the following to your `.gitlab-ci.yml`:\n\n```yaml\ninclude:\n  - template: Jobs/Container-Scanning.gitlab-ci.yml\n```  \n\n#### Common configurations\n\n**Scan a specific image:**\n\nTo scan a specific image, overwrite the `CS_IMAGE` variable in the `container_scanning` job.\n\n```yaml\ninclude:\n  - template: Jobs/Container-Scanning.gitlab-ci.yml\n\ncontainer_scanning:\n  variables:\n    CS_IMAGE: myregistry.com/myapp:latest\n```\n\n**Filter by severity threshold:**\n\nTo only find vulnerabilities with a certain severity criteria, overwrite the\n`CS_SEVERITY_THRESHOLD` variable in the `container_scanning` job. In the example\nbelow, only vulnerabilities with a severity of **High** or greater will be displayed.\n\n\n```yaml\ninclude:\n  - template: Jobs/Container-Scanning.gitlab-ci.yml\n\ncontainer_scanning:\n  variables:\n    CS_SEVERITY_THRESHOLD: \"HIGH\"\n```\n\n#### Viewing vulnerabilities in a merge request\n\nViewing Container Scanning vulnerabilities directly within merge requests makes security\nreviews seamless and efficient. Once Container Scanning is configured in your CI/CD\npipeline, GitLab automatically display detected vulnerabilities in the merge request's\n[Security widget](https://docs.gitlab.com/user/project/merge_requests/widgets/#application-security-scanning). \n\n\n![Container Scanning vulnerabilities displayed in MR](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547514/lt6elcq6jexdhqatdy8l.png \"Container Scanning vulnerabilities displayed in MR\")\n\n\n\n* Navigate to any merge request and scroll to the \"Security Scanning\" section to see a summary of\nnewly introduced and existing vulnerabilities found in your container images.\n\n* Click on a **Vulnerability** to access detailed information about the finding, including severity level,\naffected packages, and available remediation guidance.\n\n\n![GitLab Security View details in MR](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547514/hplihdlekc11uvpfih1p.png)\n\n\n\n![GitLab Security View details in MR](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547513/jnxbe7uld8wfeezboifs.png \"Container Scanning vulnerability details in MR\")\n\n\nThis visibility enables developers and security teams to catch and address container\nvulnerabilities before they reach production, making security an integral part of your\ncode review process rather than a separate gate.\n\n\n#### Viewing vulnerabilities in Vulnerability Report\n\nBeyond merge request reviews, GitLab provides a centralized\n[Vulnerability Report](https://docs.gitlab.com/user/application_security/vulnerability_report/) that gives security teams comprehensive visibility across all Container Scanning findings in your project.\n\n\n![Vulnerability Report sorted by Container Scanning](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547524/gagau279fzfgjpnvipm5.png \"Vulnerability Report sorted by Container Scanning\")\n\n\n* Access this report by navigating to **Security & Compliance > Vulnerability Report** in your\nproject sidebar.\n\n* Here you'll find an aggregated view of all container vulnerabilities detected across your branches, with powerful filtering options to sort by severity, status, scanner type, or specific container images.\n\n* You can click on a vulnerabilty to access its Vulnerablity page.\n\n\n![Vulnerability page - 1st view](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547520/e1woxupyoajhrpzrlylj.png)\n\n\n![Vulnerability page - 2nd view](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547521/idzcftcgjc8eryixnbjn.png)\n\n\n![Vulnerability page - 3rd view](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547522/mbbwbbprtf9anqqola10.png \"Vunerability Details for a Container Scanning vulnerability\")\n\n\n[Vulnerability Details](https://docs.gitlab.com/user/application_security/vulnerabilities/)\nshows exactly which container images and layers are impacted, making it easier to trace the\nvulnerability back to its source. You can assign vulnerabilities to team members, change\ntheir status (detected, confirmed, resolved, dismissed), add comments for collaboration,\nand link related issues for tracking remediation work.\n\nThis workflow transforms vulnerability management from a spreadsheet exercise into an integrated part of your development process, ensuring that container security findings are tracked, prioritized, and resolved systematically.\n\n#### View the Dependency List\n\nGitLab's [Dependency List](https://docs.gitlab.com/user/application_security/dependency_list/)\nprovides a comprehensive software bill of materials (SBOM) that catalogs every component within\nyour container images, giving you complete transparency into your software supply chain.\n\n* Navigate to **Security & Compliance > Dependency List** to access an inventory of all packages,\nlibraries, and dependencies detected by Container Scanning across your project.\n\n* This view is invaluable for understanding what's actually running inside your containers, from base OS\npackages to application-level dependencies.\n\n\n![GitLab Dependency List](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547513/vjg6dk3nhajqamplroji.png \"GitLab Dependency List (SBOM)\")\n\n\nYou can filter the list by package manager, license type, or vulnerability status to quickly\nidentify which components pose security risks or compliance concerns. Each dependency entry\nshows associated vulnerabilities, allowing you to understand security issues in the context\nof your actual software components rather than as isolated findings.\n\n\n### 2. Container Scanning for Registry\n\n* What it does: Automatically scans images pushed to your GitLab Container Registry\nwith the `latest` tag\n\n* Best for: Continuous monitoring of registry images without manual pipeline triggers  \n\n* Tier availability: Ultimate only \n\n* [Documentation](https://docs.gitlab.com/user/application_security/container_scanning/#container-scanning-for-registry) \n\n\nWhen you push a container image tagged `latest`, GitLab's security policy bot\nautomatically triggers a scan against the default branch. Unlike pipeline-based\nscanning, this approach works with Continuous Vulnerability Scanning to monitor\nfor newly published advisories.\n\n#### How to enable Container Scanning for Registry\n\n1. Navigate to **Secure > Security configuration**.\n2. Scroll to the **Container Scanning For Registry** section.\n3. Toggle the feature on.\n\n![Container Scanning for Registry](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547512/vntrlhtmsh1ecnwni5ji.png \"Toggle for Container Scanning for Registry\")\n\n#### Prerequisites\n\n- Maintainer role or higher in the project\n- Project must not be empty (requires at least one commit on the default branch)\n- Container Registry notifications must be configured\n- Package Metadata Database must be configured (enabled by default on GitLab.com)\n\nVulnerabilities appear under the **Container Registry vulnerabilities** tab in your\nVulnerability Report.\n\n\n### 3. Multi-Container Scanning\n\n* What it does: Scans multiple container images in parallel within a single pipeline \n* Best for: Microservices architectures and projects with multiple container images  \n* Tier availability: Free, Premium, and Ultimate (currently in Beta)  \n* [Documentation](https://docs.gitlab.com/user/application_security/container_scanning/multi_container_scanning/) \n\nMulti-Container Scanning uses dynamic child pipelines to run scans concurrently, significantly reducing overall pipeline execution time when you need to scan multiple images.\n\n#### How to enable Multi-Container scanning\n\n1. Create a `.gitlab-multi-image.yml` file in your repository root:\n\n```yaml\nscanTargets:\n  - name: alpine\n    tag: \"3.19\"\n  - name: python\n    tag: \"3.9-slim\"\n  - name: nginx\n    tag: \"1.25\"\n```\n\n2. Include the template in your `.gitlab-ci.yml`:\n\n```yaml\ninclude:\n  - template: Jobs/Multi-Container-Scanning.latest.gitlab-ci.yml\n```\n\n#### Advanced configuration\n\n**Scan images from private registries:**\n\n```yaml\nauths:\n  registry.gitlab.com:\n    username: ${CI_REGISTRY_USER}\n    password: ${CI_REGISTRY_PASSWORD}\n\nscanTargets:\n  - name: registry.gitlab.com/private/image\n    tag: latest\n```\n\n**Include license information:**\n\n```yaml\nincludeLicenses: true\n\nscanTargets:\n  - name: postgres\n    tag: \"15-alpine\"\n```\n\n\n### 4. Continuous Vulnerability Scanning\n\n* What it does: Automatically creates vulnerabilities when new security advisories are published, no pipeline required \n\n* Best for: Proactive security monitoring between deployments\n\n* Tier availability: Ultimate only\n\n* [Documentation](https://docs.gitlab.com/user/application_security/continuous_vulnerability_scanning/)  \n\nTraditional scanning only catches vulnerabilities at scan time. But what happens\nwhen a new CVE is published tomorrow for a package you scanned yesterday? Continuous\nVulnerability Scanning solves this by monitoring the GitLab Advisory Database and\nautomatically creating vulnerability records when new advisories affect your components.\n\n\n#### How it works\n\n1. Your Container Scanning or Dependency Scanning job generates a CycloneDX SBOM.\n\n2. GitLab registers your project's components from this SBOM.\n\n3. When new advisories are published, GitLab checks if your components are affected.\n\n4. Vulnerabilities are automatically created in your vulnerability report.\n\n\n#### Key considerations\n\n- Scans run via background jobs (Sidekiq), not CI pipelines.\n\n- Only advisories published within the last 14 days are considered for new component detection.\n\n- Vulnerabilities use \"GitLab SBoM Vulnerability Scanner\" as the scanner name.\n\n- To mark vulnerabilities as resolved, you still need to run a pipeline-based scan.\n\n\n### 5. Operational Container Scanning\n\n* What it does: Scans running containers in your Kubernetes cluster on a\nscheduled cadence\n\n* Best for: Post-deployment security monitoring and runtime vulnerability detection  \n\n* Tier availability: Ultimate only\n\n* [Documentation](https://docs.gitlab.com/user/clusters/agent/vulnerabilities/)\n\n\nOperational Container Scanning bridges the gap between build-time security and\nruntime security. Using the GitLab Agent for Kubernetes, it scans containers\nactually running in your clusters—catching vulnerabilities that emerge after\ndeployment.\n\n#### How to enable Operational Container Scanning\n\nIf you are using the [GitLab Kubernetes Agent](https://docs.gitlab.com/user/clusters/agent/install/), you can add the following to your agent configuration file:\n\n```yaml\ncontainer_scanning:\n  cadence: '0 0 * * *'  # Daily at midnight\n  vulnerability_report:\n    namespaces:\n      include:\n        - production\n        - staging\n```\n\n\nYou can also create a [scan execution policy](https://docs.gitlab.com/user/clusters/agent/vulnerabilities/#enable-via-scan-execution-policies) that enforces scanning on a schedule by the GitLab Kubernetes Agent.\n\n\n![Scan execution policy - Operational Container Scanning](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547515/gsgvjcq4sas4dfc8ciqk.png \"Scan execution policy conditions for Operational Container Scanning\")\n\n#### Viewing results\n\n* Navigate to **Operate > Kubernetes clusters**.\n\n* Select the **Agent** tab, and choose your agent.\n\n* Then select the **Security** tab to view cluster vulnerabilities.\n\n* Results also appear under the **Operational Vulnerabilities** tab in the **Vulnerability Report**.\n\n\n## Enhancing posture with GitLab Security Policies\n\nGitLab Security Policies enable you to enforce consistent security standards across your container workflows through automated, policy-driven controls. These policies shift security left by embedding requirements directly into your development pipeline, ensuring vulnerabilities are caught and addressed before code reaches production.\n\n#### Scan execution and pipeline policies\n\n[Scan execution policies](https://docs.gitlab.com/user/application_security/policies/scan_execution_policies/) automate when and how Container Scanning runs across your projects. Define policies that trigger container scans on every merge request, schedule recurring scans of your main branch, and more. These policies ensure comprehensive coverage without relying on developers to manually configure scanning in each project's CI/CD pipeline.\n\nYou can specify which scanner versions to use and configure scanning parameters centrally, maintaining consistency across your organization while adapting to new container security threats.\n\n![Scan execution policy configuration](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547517/z36dntxslqem9udrynvx.png \"Scan execution policy configuration\")\n\n\n[Pipeline execution policies](https://docs.gitlab.com/user/application_security/policies/pipeline_execution_policies/) provide flexible controls for injecting (or overriding) custom jobs into a pipeline based on your compliance needs.\n\nUse these policies to automatically inject Container Scanning jobs into your pipeline, fail builds when container vulnerabilities exceed your risk tolerance, trigger additional security checks for specific branches or tags, or enforce compliance requirements for container images destined for production environments. Pipeline execution policies act as automated guardrails, ensuring your security standards are consistently applied across all container deployments without manual intervention.\n\n![Pipeline execution policy](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547517/ddhhugzcr2swptgodof2.png \"Pipeline execution policy actions\")\n\n#### Merge request approval policies\n\n[Merge request approval policies](https://docs.gitlab.com/user/application_security/policies/merge_request_approval_policies/) enforce security gates by requiring designated approvers to review and sign off on merge requests containing container vulnerabilities.\n\nConfigure policies that block merge when critical or high-severity vulnerabilities are detected, or require security team approval for any merge request introducing new container findings. These policies prevent vulnerable container images from advancing through your pipeline while maintaining development velocity for low-risk changes.\n\n![Merge request approval policy performing block in MR](https://res.cloudinary.com/about-gitlab-com/image/upload/v1772547513/hgnbc1vl4ssqafqcyuzg.png \"Merge request approval policy performing block in MR\")\n\n\n## Choosing the right approach\n\n| Scanning Type | When to Use | Key Benefit |\n|--------------|-------------|-------------|\n| Pipeline-based | Every build | Shift-left security, blocks vulnerable builds |\n| Registry scanning | Continuous monitoring | Catches new CVEs in stored images |\n| Multi-container | Microservices | Parallel scanning, faster pipelines |\n| Continuous vulnerability | Between deployments | Proactive advisory monitoring |\n| Operational | Production monitoring | Runtime vulnerability detection |\n\n\n\nFor comprehensive security, consider combining multiple approaches. Use\npipeline-based scanning to catch issues during development, container\nscanning for registry for continuous monitoring, and operational scanning\nfor production visibility.\n\n## Get started today\n\nThe fastest path to container security is enabling pipeline-based scanning:\n\n1. Navigate to your project's **Secure > Security configuration**.\n2. Click **Configure with a merge request** for Container Scanning.\n3. Merge the resulting merge request.\n4. Your next pipeline will include vulnerability scanning.\n\nFrom there, layer in additional scanning types based on your security requirements\nand GitLab tier.\n\nContainer security isn't a one-time activity, it's an ongoing process.\nWith GitLab's comprehensive container scanning capabilities, you can detect\nvulnerabilities at every stage of your container lifecycle, from build to runtime.\n\n> For more information on how GitLab can help enhance your security posture, visit the [GitLab Security and Governance Solutions Page](https://about.gitlab.com/solutions/application-security-testing/).\n",{"slug":715,"featured":27,"template":13},"complete-guide-to-gitlab-container-scanning",{"content":717,"config":729},{"title":718,"description":719,"authors":720,"heroImage":723,"date":724,"body":725,"category":9,"tags":726},"Track vulnerability remediation with the updated GitLab Security Dashboard","Quickly prioritize remediation on high-risk projects and measure progress with vulnerability insights.",[721,722],"Alisa Ho","Mike Clausen","https://res.cloudinary.com/about-gitlab-com/image/upload/v1771438388/t6sts5qw4z8561gtlxiq.png","2026-02-19","Security teams and developers face the same frustration: thousands of vulnerabilities demanding attention, without the insights to help them prioritize remediation. Where is risk concentrated and how fast is it being remediated? Where will remediation efforts have the greatest impact? The updated GitLab Security Dashboard helps answer these questions with trend tracking, vulnerability age distribution, and risk scoring by project.\n\n## Measure remediation, not just detection\nApplication security teams don’t struggle to find vulnerabilities; they struggle to make sense of them. Most dashboards show raw counts without context, forcing teams to spend countless hours chasing remediation without understanding what vulnerabilities expose them to the greatest risks.\n\n[GitLab Security Dashboard](https://docs.gitlab.com/user/application_security/security_dashboard/#new-security-dashboards) consolidates all vulnerability data into one view that spans projects, groups, and business units.\n\nIn 18.6, we introduced the first release of the updated Security Dashboard, allowing teams to view vulnerabilities over time and filter based on project or report type. As part of the [18.9 release](https://about.gitlab.com/releases/2026/02/19/gitlab-18-9-released/), customers will be able to take advantage of new filters and charts that make it easier to slice data by severity, status, scanner, or project and visualize trends such as open vulnerabilities, remediation velocity, vulnerability age distribution, and risk score over time.\n\nRisk scores help teams prioritize remediating their most critical vulnerabilities. The risk score is calculated using factors such as vulnerability age, Exploit Prediction Scoring System (EPSS), and Known Exploited Vulnerability (KEV) scores for related repositories and their security postures. With this data, application security teams can pinpoint which areas need more attention than others. \n\nGitLab Security Dashboard helps application security and development teams:\n* **Track program effectiveness**: Monitor remediation velocity, scanner adoption, and risk posture to show measurable improvement.\n* **Focus on targeted remediation**: Fix vulnerabilities that represent the greater risk to production systems.\n* **Identify areas for remediation training**: Find which teams struggle with remediating vulnerabilities in accordance with company policy to invest in additional training. \n* **Reduce manual reporting**: Eliminate the need for external dashboards and spreadsheets by tracking everything directly within GitLab.\n\nThis update reflects GitLab’s continued commitment to making security measurable, contextual, and integrated into everyday development workflows. GitLab Security Dashboard turns raw findings into actionable insights, giving security and development teams the clarity to prioritize, reduce risk faster, and prove their progress.\n\n## See Security Dashboard in action\nAn application security leader preparing for an executive briefing can now show whether investments are reducing risk with clear trendlines: open vulnerabilities decreasing, vulnerability age decreasing, once-prevalent CWE types trending downward, and a healthy risk score. Instead of presenting raw counts, they can demonstrate how the backlog is shrinking and how risk posture is improving quarter over quarter.\n\nAt the same time, developers can see the same dashboard highlighting critical vulnerabilities in their active projects, allowing them to focus remediation efforts without exporting data or juggling multiple tools.\n\n\u003Ciframe src=\"https://player.vimeo.com/video/1166108924?badge=0&autopause=0&player_id=0&app_id=58479\" frameborder=\"0\" allow=\"autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" style=\"position:absolute;top:0;left:0;width:100%;height:100%;\" title=\"Security-Dashboard-Demo-Final\">\u003C/iframe>\u003Cscript src=\"https://player.vimeo.com/api/player.js\">\u003C/script>\n\n> For more details on how to get started with GitLab Security Dashboard today, check out our [documentation](https://docs.gitlab.com/user/application_security/security_dashboard/).",[9,727,728],"product","features",{"featured":12,"template":13,"slug":730},"track-vulnerability-remediation-with-the-updated-gitlab-security-dashboard",{"content":732,"config":742},{"title":733,"description":734,"heroImage":735,"body":736,"date":737,"category":9,"authors":738,"tags":740},"How to set up GitLab SAML SSO with Google Workspace","Learn how to automate user provisioning and sync permissions with Google groups with this step-by-step guide.","https://res.cloudinary.com/about-gitlab-com/image/upload/v1759320418/xjmqcozxzt4frx0hori3.png","Single sign-on (SSO) simplifies user authentication and improves security by allowing employees to access multiple applications with one set of credentials. For organizations using both GitLab and Google Workspace, integrating SAML-based SSO streamlines access management and ensures your teams can collaborate seamlessly.\n\nIn this guide, we'll walk through configuring SAML authentication between Google Workspace and GitLab.com, including automatic group synchronization that maps Google Workspace groups to GitLab roles. By the end, your users will be able to sign in to GitLab using their Google credentials, and their permissions will automatically reflect their Google group memberships.\n\n**Note:** This guide focuses on GitLab.com (SaaS). If you're using GitLab Self-Managed, the setup process differs slightly. Refer to the [official GitLab SAML documentation for self-managed instances](https://docs.gitlab.com/integration/saml/) for detailed instructions.\n\n## What you'll need\n\nBefore getting started, make sure you have:\n- **Google Workspace** with Super Admin access\n- **GitLab.com** with a Premium or Ultimate tier subscription\n- **Owner role** on a GitLab top-level group\n- Users already existing in Google Workspace (they'll be created in GitLab automatically on first login)\n\n## Understanding the architecture\n\nWhen you configure SAML SSO with group synchronization, here's what happens:\n\n1. **Authentication flow**: Users navigate to GitLab's SSO URL and are redirected to Google Workspace to authenticate.\n2. **SAML assertion**: After successful authentication, Google sends a SAML response containing user details and group memberships.\n3. **Automatic provisioning**: GitLab creates the user account (if needed) and assigns them to groups based on their Google group memberships.\n4. **Permission sync**: Each time users sign in, GitLab updates their group memberships and roles to match their current Google groups.\n\nThis setup provides several benefits:\n\n- **Centralized access control**: You can manage user access through Google Workspace groups.\n- **Automatic provisioning**: New users gain GitLab access on their first login.\n- **Dynamic permissions**: User roles update automatically based on group membership changes.\n- **Enhanced security**: You can leverage Google's authentication security features.\n- **Reduced administrative overhead**: There is no need to manually manage GitLab group memberships.\n\n## Part 1: Get your GitLab SAML configuration values\n\nFirst, you'll need to gather some information from GitLab that you'll use when creating the SAML application in Google Workspace. Here are the steps to take:\n\n### Step 1: Navigate to your GitLab group SAML settings\n\n1. Sign in to **GitLab.com**.\n2. Navigate to your **top-level group** (Note: SAML SSO can only be configured at the top-level group, not in subgroups).\n3. In the left sidebar, select **Settings > SAML SSO**.\n\n### Step 2: Copy the required URLs\n\nOn the SAML SSO settings page, you'll see three important URLs. Copy and save these somewhere accessible — you'll need them shortly:\n\n- **Assertion consumer service URL**: This is where Google will send SAML responses.\n  - Format: `https://gitlab.com/groups/your-group/-/saml/callback`\n\n- **Identifier**: Also called the Entity ID, this uniquely identifies your GitLab group.\n  - Format: `https://gitlab.com/groups/your-group`\n\n- **GitLab SSO URL**: This is the URL your users will use to sign in.\n  - Format: `https://gitlab.com/groups/your-group/-/saml/sso`\n\n\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090029/lrw6jbn7ussjze6lxg5o.png\" alt=\"GitLab SAML single sign-on settings\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML single sign-on settings\u003C/em>\u003C/figcaption>\n\u003C/figure>\n## Part 2: Create your SAML application in Google Workspace\n\nNow you'll create a custom SAML application in Google Workspace that connects to your GitLab group.\n\n### Step 3: Access the Google Admin Console\n\n1. Open a new browser tab and sign in to the [Google Admin Console](https://admin.google.com/) with a Super Administrator account.\n2. Click the **Menu** icon (☰) in the top-left.\n3. Navigate to **Apps > Web and mobile apps**.\n4. Click **Add App > Add custom SAML app**.\n\u003Cp>\u003C/p>\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090026/c2inhqzppdbszysupjcd.png\" alt=\"Google custom SAML app\">\n  \u003Cfigcaption>\u003Cem>Google custom SAML app\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n### Step 4: Configure the application name\n\n1. In the **App name** field, enter GitLab (or your preferred name).\n2. Optionally upload a **GitLab logo** as the app icon for easy recognition.\n3. Click **Continue**.\n\n### Step 5: Download Google identity provider details\n\nOn the **Google Identity Provider details** page, you'll need to capture two pieces of information:\n\n1. **SSO URL**: Copy this URL. It tells GitLab where to send authentication requests.\n   - Example format: `https://accounts.google.com/o/saml2/idp?idpid=C1234abcd`\n\n\n2. **Certificate**: Click the **Download** button to save the certificate file.\n   - The file will be named something like: `GoogleIDPCertificate-gitlab.pem`\n   - Save this file somewhere you can easily find it. You'll need it in the next section\n\n3. Click **Continue**.\n\n### Step 6: Configure service provider details\n\nThis is where you'll use the GitLab URLs you copied in Step 2. Enter the following:\n\n| **Field** | **Value** | **Description** |\n|-----------|-----------|-----------------|\n| **ACS URL** | Your GitLab Assertion consumer service URL | Where Google sends SAML responses |\n| **Entity ID** | Your GitLab Identifier | Unique identifier for your GitLab group |\n| **Start URL** | Leave blank | Not required for this setup |\n| **Name ID format** | Select **EMAIL** | The format for the user identifier |\n| **Name ID** | Select **Basic Information > Primary Email** | The user's primary email will be used as their identifier |\n| **Signed response** | Leave unchecked | GitLab doesn't require signed responses by default |\n\n\u003Cfigure style=\"margin: 24px 0;\">\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090028/kaui5vj14gkftbfgsbnz.png\" alt=\"GitLab SAML app details\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML app details\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n\nClick **Continue** when complete.\n\n### Step 7: Configure attribute mapping\n\nAttribute mapping tells Google which user information to send to GitLab. You'll configure both basic user attributes and group membership.\n\n#### Basic attributes\n\nAdd these three attribute mappings by clicking **Add mapping** for each:\n\n| **Google Directory attribute** | **App attribute** |\n|--------------------------------|-------------------|\n| Primary email | email |\n| First name | first_name |\n| Last name | last_name |\n\n#### Group membership configuration\n\nThis is the critical configuration that enables automatic group synchronization:\n\n1. Scroll down to the **\"Group membership (optional)\"** section.\n2. Under **\"Google groups\"**, click **\"Search for a group\"**.\n3. Search for and select each Google Workspace group you want to synchronize with GitLab.\n   - You can select up to 75 groups\n   - Examples: Engineering, DevOps, Platform-Team, Security-Team\n\n4. Under **\"App attribute\"**, enter exactly: `groups`.\n5. Click **Finish**.\n\n\u003Cp>\u003C/p>\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090027/ksuebt9uoe3w5cdzsjkl.png\" alt=\"GitLab SAML app attribute mapping\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML app attribute mapping\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n> **Critical**: The app attribute name **MUST** be exactly `groups` (lowercase). This is what GitLab expects to receive in the SAML response. Any other value or capitalization will prevent group synchronization from working.\n\n### Step 8: Enable the application for users\n\nYour SAML app is created but not yet enabled. To make it available to users:\n\n1. In the Google Admin Console, find your **GitLab** app in the Web and mobile apps list.\n2. Click on the app to open its details.\n3. In the left sidebar, click **User access**.\n4. Select one of the following:\n   - **ON for everyone** - Enables the app for all users in your organization\n   - **ON for some organizational units** - Select specific organizational units\n\n5. Click **Save**.\n\n**Note**: Changes can take up to 24 hours to propagate, but typically take effect within a few minutes.\n\n## Part 3: Convert the certificate to SHA-1 fingerprint format\n\nGitLab requires a SHA-1 certificate fingerprint, but Google's certificate download doesn't include this format directly. You'll need to convert it.\n\n### Step 9: Convert your certificate\n\nYou have two options for converting the certificate to the required format.\n\n#### Option 1: Online conversion tool\n\nThis is a viable method if you're comfortable using a third-party tool:\n\n1. **Locate the certificate file** you downloaded in Step 5:\n   - Check your Downloads folder\n   - The file name will be something like: `GoogleIDPCertificate-gitlab.pem`\n\n2. **Open the file** in a text editor:\n   - Mac: **Right-click > Open With > TextEdit**\n   - Windows: **Right-click > Open With > Notepad**\n   - Linux: Use your preferred text editor\n\n3. **Copy ALL contents** of the file, including the header and footer:\n\n\n  ```text\n  -----BEGIN CERTIFICATE-----\n  MIIDdDCCAlygAwIBAgIGAXqD...\n  (multiple lines of encoded text)\n  ...kE7RnF6yQ==\n  -----END CERTIFICATE-----\n  ```\n\n\n4. **Navigate to**: A SHA-1 fingerprint conversion tool. [This one](https://www.samltool.com/fingerprint.php) is a good example.\n5. **Paste the certificate content** into the text box.\n6. **Select \"SHA-1\"** from the algorithm dropdown (not SHA-256!).\n7. Click **\"Calculate Fingerprint\"**.\n8. **Copy the resulting fingerprint** - it will be in the format: `XX:XX:XX:XX:XX:...`.\n\n#### Option 2: Command-line conversion\n\nIf you prefer using the command line:\n\n**For Mac, Linux, or Windows with WSL:**\n\n\n  ```bash\n  cd ~/Downloads\n  openssl x509 -noout -fingerprint -sha1 -inform pem -in \"GoogleIDPCertificate-gitlab.pem\"\n  ```\n\n\nThe output will show:\n\n\n  ```text\n  SHA1 Fingerprint=XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX\n  ```\n\n\nCopy everything after `SHA1 Fingerprint=`.\n\n## Part 4: Complete your GitLab SAML configuration\n\nNow that you have the Google SSO URL and certificate fingerprint, you can complete the GitLab side of the configuration.\n\n### Step 10: Enter Google identity provider details\n\nReturn to your GitLab browser tab (**Settings > SAML SSO**) and do the following:\n\n1. **Identity provider SSO URL**:\n   - Paste the SSO URL you copied from Google in Step 5\n\n2. **Certificate fingerprint**:\n   - Paste the SHA-1 fingerprint you generated in Step 9\n   - Verify the format is correct: 59 characters with colons (XX:XX:XX:...)\n\n3. **Enable SAML authentication for this group**:\n   - Check this box to activate SAML SSO\n\n\u003Cp>\u003C/p>\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090027/ncoeqrdu7aahyuflrq7b.png\" alt=\"GitLab SAML Configuration with Google SAML values\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML Configuration with Google SAML values\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n### Step 11: Configure security settings (recommended)\n\nFor enhanced security, consider enabling these additional options:\n\n- **\"Enforce SAML authentication for web activity for this group\"**\n  - Requires users to authenticate via SAML to access the GitLab web interface\n\n- **\"Enforce SAML authentication for Git and Dependency Proxy activity for this group\"**\n  - Requires SAML authentication for Git operations and dependency proxy access\n\nClick **Save changes** to apply your configuration.\n\n### Step 12: Test your SAML configuration\n\nBefore proceeding with group synchronization, verify that basic SAML authentication works:\n\n1. Open an incognito or private browsing window.\n2. Navigate to your GitLab SSO URL.\n   - Format: `https://gitlab.com/groups/your-group/-/saml/sso`\n\n3. You should be redirected to the Google sign-in page.\n4. Sign in with a Google Workspace account that has access to the GitLab app.\n5. After successful authentication, you should be redirected back to GitLab.\n\n**If the test succeeds**, you can proceed to configure group synchronization.\n\n**If the test fails**, check the following:\n\n- Verify the certificate fingerprint is SHA-1 format (not SHA-256).\n- Confirm the SSO URL is correct.\n- Ensure the user has access to the GitLab SAML app in Google Admin Console.\n- Check that the ACS URL and Entity ID match exactly.\n\n## Part 5: Set up SAML group synchronization\n\nNow it's time to map your Google Workspace groups to GitLab roles so that permissions are automatically managed based on group membership.\n\n### Step 13: Configure default membership role\n\nAs a security best practice, set a minimal default role for users who log in but don't belong to any mapped groups:\n\n1. In your GitLab group, navigate to **Settings > General**.\n2. Expand the **Permissions and group features** section.\n3. Under **Default membership role**, select **Minimal Access or Guest**.\n4. Click **Save changes**.\n\n\u003Cp>\u003C/p>\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769097587/syi0jeaspzt9tki0w9nd.png\" alt=\"GitLab SAML Default membership setting\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML Default membership setting\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n### Step 14: Create SAML group links\n\nSAML Group Links are the mappings between Google Workspace groups and GitLab roles. Here's how to create them:\n\n1. In your GitLab group, navigate to **Settings > SAML Group Links**.\n2. Click **\"Add new SAML Group Link\"**.\n\nFor each Google Workspace group you want to sync:\n\n**SAML Group Name**:\n\n- Enter the **exact name** of your Google Workspace group\n- This is **case-sensitive** and must match perfectly\n- Example: Engineering (not engineering)\n- To find the exact name: Google Admin Console > Directory > Groups\n\n**Access Level**: Select the appropriate GitLab role:\n\n- **Minimal Access** - Can see that the group exists\n- **Guest** - Can view issues and leave comments\n- **Reporter** - Can pull code, view issues, and create new issues\n- **Developer** - Can push code, create merge requests, and manage issues\n- **Maintainer** - Can manage project settings and members\n- **Owner** - Full administrative control over the group\n\n3. Click **Save**.\n4. **Repeat this process** for each Google Workspace group you want to map.\n\n**Note:** SAML group sync rules are enforced every time a user signs in. If a user's Google group membership matches a sync rule, their GitLab role will be automatically set to the configured access level, even if you've manually changed it to something different. For example, if you set up a sync rule that grants \"Maintainer\" access and then manually promote a user to \"Owner,\" they'll be automatically downgraded back to \"Maintainer\" on their next SAML sign-in.\n\n**Best practices:** To maintain custom access levels for specific users, do one of the following:\n\n - Use SAML group sync only on your top-level group and manually manage permissions in subgroups\n\n - Create separate Google groups for users who need elevated permissions\n \n - Avoid setting up sync rules that would conflict with manual role assignments\n\n\n\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090028/etjoaiuyhnqh4gnjqcha.png\" alt=\"GitLab SAML Group Links setup\">\n  \u003Cfigcaption>\u003Cem>GitLab SAML Group Links setup\u003C/em>\u003C/figcaption>\n\u003C/figure>\n### Example group mapping configuration\n\nHere's a practical example of how you might structure your group mappings:\n\n| **Google Workspace Group** | **GitLab Role** | **Purpose** |\n|----------------------------|-----------------|-------------|\n| GitLab-Admins | Owner | Full administrative access |\n| Engineering-Team | Maintainer | Can manage projects and settings |\n| Developer-Team | Developer | Can write and push code |\n| QA-Team | Developer | Can test and manage issues |\n| Contractors | Reporter | Read-only access to code |\n| All-Employees | Minimal Access | Basic visibility |\n\n### Step 15: Verify your group links\n\nAfter creating all your group links:\n\n1. Review the complete list of SAML Group Links in **Settings > SAML Group Links**.\n2. Verify each **SAML Group Name** exactly matches the corresponding Google Workspace group.\n3. Verify each **Access Level** is appropriate for the intended purpose.\n4. Check for any typos or extra spaces.\n\n## Part 6: Test the complete configuration\n\nNow it's time to test the entire setup including group synchronization.\n\n### Step 16: Test with a real user\n\nChoose a test user who meets these criteria:\n\n- Has a Google Workspace account\n- Is a member of at least one Google Workspace group you configured\n- Has the GitLab SAML app enabled in Google Admin Console\n- Ideally is not you (to ensure a realistic test)\n\nTo perform the test:\n\n1. **Open an incognito or private browsing window**\n2. **Navigate to your GitLab SSO URL**:\n   - `https://gitlab.com/groups/your-group/-/saml/sso`\n\n3. **Sign in** with the test user's Google Workspace credentials\n4. The user should be:\n   - Authenticated successfully\n   - Redirected to GitLab\n   - Automatically added to the GitLab group\n   - Assigned the appropriate role based on their Google group membership\n\n### Step 17: Verify group membership and role assignment\n\nUsing your GitLab administrator account:\n\n1. Navigate to your group in GitLab.\n2. Select **Manage > Members** from the left sidebar.\n3. Find the test user in the members list.\n4. Verify the following:\n   - User appears in the members list\n   - User has the correct **Max role** based on their Google group(s)\n   - **Source** column shows a SAML indicator\n\n\u003Cp>\u003C/p>\n\u003Cfigure>\n  \u003Cimg src=\"https://res.cloudinary.com/about-gitlab-com/image/upload/v1769090026/hiov7kiukidsiyscfesg.png\" alt=\"Verified SAML user added\">\n  \u003Cfigcaption>\u003Cem>Verified SAML user added\u003C/em>\u003C/figcaption>\n\u003C/figure>\n\n## Part 7: Configure subgroup access (optional)\n\nFor larger organizations, you may want to provide more granular access control using GitLab subgroups. SAML Group Links can be configured at any level of your group hierarchy, allowing you to map different Google Workspace groups to specific teams or projects.\n\n### Understanding GitLab's subgroup structure\n\nGitLab supports nested group hierarchies that can mirror your organizational structure:\n\n  ```text\n  acme-corp/                          ← Top-level group (SAML configured here)\n  ├── engineering/                    ← Subgroup\n  │   ├── backend/                   ← Nested subgroup\n  │   └── frontend/                  ← Nested subgroup\n  ├── marketing/                      ← Subgroup\n  └── operations/                     ← Subgroup\n  ```\n\n\n### Creating subgroups\n\nIf you need to create additional subgroups:\n\n1. Navigate to your **parent group** (e.g., acme-corp).\n2. Click the **New subgroup** button.\n3. Configure the subgroup:\n   - **Subgroup name**: Display name (e.g., Engineering)\n   - **Subgroup URL**: URL slug (e.g., engineering)\n   - **Visibility level**: Choose Private, Internal, or Public\n\n4. Click **Create subgroup**.\n5. Repeat for other subgroups as needed.\n\n### Configuring SAML group links for subgroups\nHere are the steps to configure SAML group links for subgroups.\n\n#### Add new Google groups to the SAML app (if needed)\n\nIf you're introducing new Google Workspace groups for subgroup access:\n\n1. Go to **Google Admin Console > Apps > Web and mobile apps > GitLab**.\n2. Click **SAML attribute mapping**.\n3. Scroll to **\"Group membership (optional)\"**.\n4. Add your new groups (e.g., Backend-Team, Frontend-Team).\n5. Verify the **\"App attribute\"** is still `groups`.\n6. Click **Save**.\n\n#### Map Google groups to subgroups\n\n1. **Navigate to the specific subgroup** in GitLab\n   - Example: acme-corp/engineering/backend\n\n2. Go to **Settings > SAML Group Links**.\n3. Click **\"Add new SAML Group Link\"**.\n4. Configure the mapping:\n   - **SAML Group Name**: Backend-Team (exact Google Workspace group name)\n   - **Access Level**: Developer (or your desired role)\n\n5. Click **Save**.\nRepeat this process for all subgroups and their corresponding Google groups.\n\n### Multi-level access example\n\nHere's how permissions might work across different levels:\n\n#### Top-level group: acme-corp\n\nSAML Group Links:\n\n- \"Company-Admins\" → Owner\n- \"All-Employees\" → Minimal Access\n\n#### Subgroup: acme-corp/engineering\n\nSAML Group Links:\n\n- \"Engineering-Leads\" → Owner\n- \"Engineering-Team\" → Maintainer\n\n#### Nested subgroup: acme-corp/engineering/backend\n\nSAML Group Links:\n\n- \"Backend-Leads\" → Maintainer\n- \"Backend-Team\" → Developer\n\n### How permissions inherit and combine\n\nUnderstanding permission behavior is important:\n\n- **Role calculation**: At each level, users receive the **highest role** from all their Google groups.\n- **Inheritance**: Higher permissions at parent levels flow down to child subgroups.\n- **Independence**: Each level calculates permissions based on its own group links plus inherited permissions.\n- **No limitation**: Lower permissions at parent levels do NOT restrict higher permissions at child levels.\n\n**Example scenarios**:\n\n**User A** (member of Backend-Team only):\n\n- acme-corp: Minimal Access (from \"All-Employees\" default)\n- acme-corp/engineering: Minimal Access (inherited from parent)\n- acme-corp/engineering/backend: Developer (from \"Backend-Team\" mapping)\n\n**User B** (member of Engineering-Leads and Backend-Team):\n\n- acme-corp: Minimal Access (from \"All-Employees\" default)\n- acme-corp/engineering: Owner (from \"Engineering-Leads\" mapping)\n- acme-corp/engineering/backend: Owner (inherited from parent, which is higher than Developer)\n\n## How the synchronization works\n\nUnderstanding the mechanics of SAML group synchronization helps you manage the system effectively.\n\n### Synchronization timing\n\n- **When sync occurs**: Group memberships update **every time** a user signs in via SAML.\n- **Frequency**: Changes are not continuous — they only happen at login.\n- **Direction**: Synchronization is **one-way** from Google Workspace to GitLab.\n- **First login**: User account is created automatically and groups are assigned.\n- **Subsequent logins**: Existing group memberships are updated to match current Google groups.\n\n### Role priority and combination\n\nWhen a user belongs to multiple Google Workspace groups:\n\n- GitLab evaluates **all** the user's groups at each level of the hierarchy.\n- The user receives the **highest role** from any of their groups.\n- This calculation happens independently at each level (top-level group, subgroups, etc.).\n\n**Example**:\n\n- User in \"Developers\" (Developer role) + \"Tech-Leads\" (Maintainer role) → Gets **Maintainer**\n\n### Automatic role changes\n\nThe system automatically handles membership changes:\n\n- **User added to a Google group**: Role upgraded on next login.\n- **User removed from a Google group**: Role recalculated based on remaining groups on next login.\n- **User removed from all mapped groups**: Reverts to default membership role on next login.\n- **User added to additional groups**: Gets highest role from all groups on next login.\n\n### Propagation timing\n\nBe aware of these timing considerations:\n\n- **Google Workspace changes**: Can take up to 24 hours to propagate, though usually take only a few minutes.\n- **GitLab sync**: Happens immediately when the user logs in after Google changes are live.\n- **Testing**: Have users log out and log back in to test permission changes.\n\n## Understanding user lifecycle and edge cases\n\n### What happens when you remove a user from GitLab?\n\n**Removing permissions only:** If you remove a user from GitLab projects but leave their account active and they're still in the authorized Google groups:\n\n- They keep their same account (same user ID and username)\n- When they log in via SAML, their group memberships are automatically restored\n- They regain permissions based on their current Google group memberships\n\n**Blocking the account:**\n\n- Account exists but is locked\n- User cannot log in even if in Google groups\n- Can be unblocked later, preserving all history\n\n**Deleting the account:**\n\n- Account is permanently removed\n- If user logs in again (while still in Google groups), GitLab creates a **completely new account**\n- New account has different user ID with no connection to the old one\n\n### Proper offboarding process\n\nTo permanently revoke access, follow this order:\n\n1. **Remove from Google Workspace groups** - Prevents authentication\n2. **Block in GitLab** - Prevents account recreation and preserves audit trails\n3. **Delete account (optional)** - Only if you're certain they won't return\n\n> **Critical**: Removing a user only from GitLab without removing them from Google groups means they can simply log back in and regain access.\n\n### Google group membership propagation\n\nAccording to [Google's documentation](https://support.google.com/a/answer/11143403), group membership changes can take up to 24 hours to propagate, though typically occur within minutes.\n\n### Account recreation scenarios\n\n| **Scenario** | **User still in Google groups?** | **What happens on login** |\n|--------------|----------------------------------|---------------------------|\n| Permissions removed | Yes | Same account, group memberships restored |\n| Account blocked | Yes | Login fails |\n| Account deleted | Yes | New account created with new user ID |\n| Removed from Google groups | No | Login fails at Google |\n\n## Troubleshooting common issues\n\nEven with careful configuration, you might encounter issues. Here are solutions to the most common problems.\n\n### Users not being added to groups\n\n**Symptom**: User successfully logs in via SAML but doesn't appear in any GitLab groups, or appears with only the default role.\n\n**Possible causes and solutions**:\n\n1. **Group names don't match exactly**\n   - Check spelling and capitalization in both Google Workspace and GitLab\n   - Look for extra spaces before or after group names\n   - Verify the exact name in Google Admin Console > Directory > Groups\n\n2. **User not actually in the Google group**\n   - Verify membership: Google Admin Console > Directory > Groups > [Group] > Members\n   - Remember that nested group membership might not be included\n\n3. **Groups not configured in SAML app**\n   - Verify the groups are selected in Google SAML attribute mapping\n   - Confirm \"App attribute\" is set to `groups` (lowercase)\n   - Use \"Test SAML Login\" to inspect the SAML response\n\n4. **Timing or cache issue**\n   - Wait 24 hours for Google changes to fully propagate\n   - Have the user log out of GitLab and Google completely\n   - Clear browser cache and try again\n   - User must log in via the SAML SSO URL, not regular GitLab login\n\n### User has incorrect role\n\n**Symptom**: User has access but with the wrong permission level.\n\n**Possible causes and solutions**:\n\n1. **User belongs to multiple groups**\n   - Remember: Users get the **highest** role from all their groups\n   - Check all Google groups the user belongs to\n   - Review all SAML Group Link configurations at all levels\n\n2. **SAML Group Link misconfigured**\n   - Verify the Access Level setting in Settings > SAML Group Links\n   - Check for duplicate group mappings that might conflict\n\n3. **User hasn't logged in since changes**\n   - Roles only update when users log in via SAML\n   - Have the user log out completely and log back in via the SSO URL\n\n4. **Inherited permissions from parent groups**\n   - Check SAML Group Links in parent groups\n   - Remember that higher roles at parent levels flow down to children\n\n### SAML authentication fails completely\n\n**Symptom**: Users cannot log in at all, or receive error messages during authentication.\n\n**Possible causes and solutions**:\n\n1. **Incorrect certificate fingerprint**\n   - Verify you used SHA-1 format, not SHA-256\n   - Check the fingerprint has the correct format with colons\n   - Regenerate using the online tool or OpenSSL command\n\n2. **Wrong SSO URL**\n   - Double-check the SSO URL copied from Google\n   - Ensure there are no extra spaces or characters\n\n3. **ACS URL or Entity ID mismatch**\n   - Verify the ACS URL in Google Admin Console matches GitLab exactly\n   - Confirm the Entity ID matches between both systems\n\n4. **User doesn't have app access**\n   - Check User Access settings in Google Admin Console\n   - Verify the user's organizational unit has the app enabled\n   - Confirm the app is \"ON\" for the appropriate users\n\n5. **Certificate expired**\n   - Check certificate validity dates\n   - Download a fresh certificate if needed\n\n### Groups attribute missing from SAML response\n\n**Symptom**: Users can log in but group synchronization doesn't work at all.\n\n**Possible causes and solutions**:\n\n1. **Groups not selected in Google configuration**\n   - Return to **Google Admin > Apps > GitLab > Attribute** mapping\n   - Verify groups are selected under \"Group membership\"\n   - Confirm \"App attribute\" is exactly `groups` (lowercase)\n\n2. **User not in any configured groups**\n   - Only groups the user belongs to are sent in the SAML response\n   - Add the user to at least one selected group to test\n\n3. **Configuration hasn't propagated**\n   - Wait up to 24 hours for changes to take effect\n   - Try logging out of Google Admin Console and back in\n\n4. **Typo in app attribute name**\n   - The attribute name must be exactly `groups` (lowercase)\n   - Even a capital letter or extra space will break functionality\n\n## Best practices for managing SAML group sync\n\nFollow these recommendations to maintain a secure and efficient setup.\n\n### Security best practices\n\n1. **Maintain emergency access**\n   - Keep at least one Owner account that uses password authentication (not SAML)\n   - This provides emergency access if SAML configuration breaks\n   - Store these credentials securely\n\n2. **Use least privilege principle**\n   - Set default membership to Minimal Access\n   - Only grant higher permissions through explicit group mappings\n   - Regularly review and audit group memberships\n\n3. **Enable enforcement options**\n   - Turn on \"Enforce SAML authentication\" options\n   - This prevents users from bypassing SSO\n   - Exceptions should be rare and well-documented\n\n4. **Regular security audits**\n   - Quarterly review of Google Workspace group memberships\n   - Annual review of SAML Group Link mappings\n   - Monitor GitLab audit logs for unusual access patterns\n\n## Summary and next steps\n\nCongratulations! You've successfully configured SAML SSO and automatic group synchronization between Google Workspace and GitLab. Your setup now provides:\n\n- **Seamless authentication** - Users sign in with their familiar Google Workspace credentials.\n- **Automatic provisioning** - User accounts are created on first login without manual intervention.\n- **Dynamic permissions** - Group memberships and roles update automatically based on Google Workspace groups.\n- **Centralized access control** - Manage all access through your existing Google Workspace groups.\n- **Enhanced security** - Leverage Google's authentication infrastructure and enforce consistent policies.\n- **Reduced administrative overhead** - Eliminate manual user and permission management in GitLab.\n\n### What happens now\n\nWhen users access GitLab:\n\n1. They navigate to your GitLab SSO URL.\n2. Authenticate using their Google Workspace credentials.\n3. Get automatically added to appropriate GitLab groups.\n4. Receive permissions based on their Google group memberships.\n5. Their permissions update every time they sign in.\n\n### Additional resources\n\n- [GitLab SAML SSO Documentation](https://docs.gitlab.com/ee/user/group/saml_sso/)\n- [GitLab SAML Group Sync Documentation](https://docs.gitlab.com/ee/user/group/saml_sso/group_sync.html)\n- [Google Workspace SAML App Setup](https://support.google.com/a/answer/6087519)\n- [SAML Certificate Fingerprint Tool](https://www.samltool.com/fingerprint.php)\n\n## Related article\n* [How-to: GitLab Single Sign-on with SAML, SCIM, and Azure's Entra ID](https://about.gitlab.com/blog/how-to-gitlab-single-sign-on-with-saml-scim-and-azures-entra-id/)","2026-01-27",[739],"Omid Khan",[9,710,727,741],"google",{"featured":27,"template":13,"slug":743},"how-to-set-up-gitlab-saml-sso-with-google-workspace",{"promotions":745},[746,760,771],{"id":747,"categories":748,"header":750,"text":751,"button":752,"image":757},"ai-modernization",[749],"ai-ml","Is AI achieving its promise at scale?","Quiz will take 5 minutes or less",{"text":753,"config":754},"Get your AI maturity score",{"href":755,"dataGaName":756,"dataGaLocation":242},"/assessments/ai-modernization-assessment/","modernization assessment",{"config":758},{"src":759},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1772138786/qix0m7kwnd8x2fh1zq49.png",{"id":761,"categories":762,"header":763,"text":751,"button":764,"image":768},"devops-modernization",[727,556],"Are you just managing tools or shipping innovation?",{"text":765,"config":766},"Get your DevOps maturity score",{"href":767,"dataGaName":756,"dataGaLocation":242},"/assessments/devops-modernization-assessment/",{"config":769},{"src":770},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1772138785/eg818fmakweyuznttgid.png",{"id":772,"categories":773,"header":774,"text":751,"button":775,"image":779},"security-modernization",[9],"Are you trading speed for security?",{"text":776,"config":777},"Get your security maturity score",{"href":778,"dataGaName":756,"dataGaLocation":242},"/assessments/security-modernization-assessment/",{"config":780},{"src":781},"https://res.cloudinary.com/about-gitlab-com/image/upload/v1772138786/p4pbqd9nnjejg5ds6mdk.png",{"header":783,"blurb":784,"button":785,"secondaryButton":790},"Start building faster today","See what your team can do with the intelligent orchestration platform for DevSecOps.\n",{"text":786,"config":787},"Get your free trial",{"href":788,"dataGaName":49,"dataGaLocation":789},"https://gitlab.com/-/trial_registrations/new?glm_content=default-saas-trial&glm_source=about.gitlab.com/","feature",{"text":494,"config":791},{"href":53,"dataGaName":54,"dataGaLocation":789},1773350813432]