feat(api): add support for project feature flags

amimas · amimas · commit de83fe49aedb · 2026-03-15T17:53:35.000-04:00
Add support for the Project Feature Flags API.

- Add `ProjectFeatureFlag` and `ProjectFeatureFlagManager`.
- Add `project.feature_flags` manager.
- Add functional tests for API and CLI.
- Handle JSON parsing for `strategies` attribute in
CLI commands by overriding create/update methods in the manager.
diff --git a/gitlab/v4/objects/__init__.py b/gitlab/v4/objects/__init__.py
@@ -24,6 +24,7 @@
 from .epics import *
 from .events import *
 from .export_import import *
+from .feature_flags import *
 from .features import *
 from .files import *
 from .geo_nodes import *
diff --git a/gitlab/v4/objects/feature_flags.py b/gitlab/v4/objects/feature_flags.py
@@ -0,0 +1,80 @@
+"""
+GitLab API:
+https://docs.gitlab.com/ee/api/feature_flags.html
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from gitlab.base import RESTObject
+from gitlab.mixins import CRUDMixin, ObjectDeleteMixin, SaveMixin
+from gitlab.types import RequiredOptional
+
+__all__ = ["ProjectFeatureFlag", "ProjectFeatureFlagManager"]
+
+
+class ProjectFeatureFlag(SaveMixin, ObjectDeleteMixin, RESTObject):
+    _id_attr = "name"
+
+
+class ProjectFeatureFlagManager(CRUDMixin[ProjectFeatureFlag]):
+    _path = "/projects/{project_id}/feature_flags"
+    _obj_cls = ProjectFeatureFlag
+    _from_parent_attrs = {"project_id": "id"}
+    _create_attrs = RequiredOptional(
+        required=("name",), optional=("version", "description", "active", "strategies")
+    )
+    _update_attrs = RequiredOptional(optional=("description", "active", "strategies"))
+    _list_filters = ("scope",)
+
+    def create(
+        self, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> ProjectFeatureFlag:
+        """Create a new object.
+
+        Args:
+            data: Parameters to send to the server to create the
+                         resource
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Returns:
+            A new instance of the managed object class build with
+                the data sent by the server
+        """
+        # Handle strategies being passed as a JSON string (e.g. from CLI)
+        if "strategies" in kwargs and isinstance(kwargs["strategies"], str):
+            kwargs["strategies"] = json.loads(kwargs["strategies"])
+        if data and "strategies" in data and isinstance(data["strategies"], str):
+            data["strategies"] = json.loads(data["strategies"])
+
+        return super().create(data, **kwargs)
+
+    def update(
+        self,
+        id: str | int | None = None,
+        new_data: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Update an object on the server.
+
+        Args:
+            id: ID of the object to update (can be None if not required)
+            new_data: the update data for the object
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Returns:
+            The new object data (*not* a RESTObject)
+        """
+        # Handle strategies being passed as a JSON string (e.g. from CLI)
+        if "strategies" in kwargs and isinstance(kwargs["strategies"], str):
+            kwargs["strategies"] = json.loads(kwargs["strategies"])
+        if (
+            new_data
+            and "strategies" in new_data
+            and isinstance(new_data["strategies"], str)
+        ):
+            new_data["strategies"] = json.loads(new_data["strategies"])
+
+        return super().update(id, new_data, **kwargs)
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
@@ -49,6 +49,7 @@
 )
 from .events import ProjectEventManager  # noqa: F401
 from .export_import import ProjectExportManager, ProjectImportManager  # noqa: F401
+from .feature_flags import ProjectFeatureFlagManager  # noqa: F401
 from .files import ProjectFileManager  # noqa: F401
 from .hooks import ProjectHookManager  # noqa: F401
 from .integrations import ProjectIntegrationManager, ProjectServiceManager  # noqa: F401
@@ -201,6 +202,7 @@ class Project(
     environments: ProjectEnvironmentManager
     events: ProjectEventManager
     exports: ProjectExportManager
+    feature_flags: ProjectFeatureFlagManager
     files: ProjectFileManager
     forks: ProjectForkManager
     generic_packages: GenericPackageManager
diff --git a/tests/functional/api/test_project_feature_flags.py b/tests/functional/api/test_project_feature_flags.py
@@ -0,0 +1,58 @@
+import pytest
+
+from gitlab import exceptions
+
+
+@pytest.fixture
+def feature_flag(project):
+    flag_name = "test_flag_fixture"
+    flag = project.feature_flags.create(
+        {"name": flag_name, "version": "new_version_flag"}
+    )
+    yield flag
+    try:
+        flag.delete()
+    except exceptions.GitlabDeleteError:
+        pass
+
+
+def test_create_feature_flag(project):
+    flag_name = "test_flag_create"
+    flag = project.feature_flags.create(
+        {"name": flag_name, "version": "new_version_flag"}
+    )
+    assert flag.name == flag_name
+    assert flag.active is True
+    flag.delete()
+
+
+def test_create_feature_flag_with_strategies(project):
+    flag_name = "test_flag_strategies"
+    strategies = [{"name": "userWithId", "parameters": {"userIds": "user1"}}]
+    flag = project.feature_flags.create(
+        {"name": flag_name, "version": "new_version_flag", "strategies": strategies}
+    )
+    assert len(flag.strategies) == 1
+    assert flag.strategies[0]["name"] == "userWithId"
+    assert flag.strategies[0]["parameters"]["userIds"] == "user1"
+    flag.delete()
+
+
+def test_list_feature_flags(project, feature_flag):
+    flags = project.feature_flags.list()
+    assert len(flags) >= 1
+    assert feature_flag.name in [f.name for f in flags]
+
+
+def test_update_feature_flag(project, feature_flag):
+    feature_flag.active = False
+    feature_flag.save()
+
+    updated_flag = project.feature_flags.get(feature_flag.name)
+    assert updated_flag.active is False
+
+
+def test_delete_feature_flag(project, feature_flag):
+    feature_flag.delete()
+    with pytest.raises(exceptions.GitlabGetError):
+        project.feature_flags.get(feature_flag.name)
diff --git a/tests/functional/cli/test_cli_project_feature_flags.py b/tests/functional/cli/test_cli_project_feature_flags.py
@@ -0,0 +1,143 @@
+import json
+
+import pytest
+
+
+@pytest.fixture
+def feature_flag_cli(gitlab_cli, project):
+    flag_name = "test_flag_cli_fixture"
+    cmd = [
+        "project-feature-flag",
+        "create",
+        "--project-id",
+        str(project.id),
+        "--name",
+        flag_name,
+    ]
+    gitlab_cli(cmd)
+    yield flag_name
+    try:
+        cmd = [
+            "project-feature-flag",
+            "delete",
+            "--project-id",
+            str(project.id),
+            "--name",
+            flag_name,
+        ]
+        gitlab_cli(cmd)
+    except Exception:
+        pass
+
+
+def test_project_feature_flag_cli_create_delete(gitlab_cli, project):
+    flag_name = "test_flag_cli_create"
+    cmd = [
+        "project-feature-flag",
+        "create",
+        "--project-id",
+        str(project.id),
+        "--name",
+        flag_name,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+    assert flag_name in ret.stdout
+
+    cmd = [
+        "project-feature-flag",
+        "delete",
+        "--project-id",
+        str(project.id),
+        "--name",
+        flag_name,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+
+
+def test_project_feature_flag_cli_create_with_strategies(gitlab_cli, project):
+    flag_name = "test_flag_cli_strategies"
+    strategies_json = (
+        '[{"name": "userWithId", "parameters": {"userIds": "user1,user2"}}]'
+    )
+
+    cmd = [
+        "project-feature-flag",
+        "create",
+        "--project-id",
+        str(project.id),
+        "--name",
+        flag_name,
+        "--strategies",
+        strategies_json,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+
+    cmd = [
+        "-o",
+        "json",
+        "project-feature-flag",
+        "get",
+        "--project-id",
+        str(project.id),
+        "--name",
+        flag_name,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+    data = json.loads(ret.stdout)
+    assert len(data["strategies"]) == 1
+    assert data["strategies"][0]["name"] == "userWithId"
+
+
+def test_project_feature_flag_cli_list(gitlab_cli, project, feature_flag_cli):
+    cmd = ["project-feature-flag", "list", "--project-id", str(project.id)]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+    assert feature_flag_cli in ret.stdout
+
+
+def test_project_feature_flag_cli_get(gitlab_cli, project, feature_flag_cli):
+    cmd = [
+        "project-feature-flag",
+        "get",
+        "--project-id",
+        str(project.id),
+        "--name",
+        feature_flag_cli,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+    assert feature_flag_cli in ret.stdout
+
+
+def test_project_feature_flag_cli_update(gitlab_cli, project, feature_flag_cli):
+    cmd = [
+        "project-feature-flag",
+        "update",
+        "--project-id",
+        str(project.id),
+        "--name",
+        feature_flag_cli,
+        "--active",
+        "false",
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+
+    cmd = [
+        "-o",
+        "json",
+        "project-feature-flag",
+        "get",
+        "--project-id",
+        str(project.id),
+        "--name",
+        feature_flag_cli,
+    ]
+    ret = gitlab_cli(cmd)
+    assert ret.success
+    data = json.loads(ret.stdout)
+    assert data["active"] is False
