Skip to content

feat(api): add support for project feature flags and feature flag user lists#3366

Open
amimas wants to merge 16 commits intopython-gitlab:mainfrom
amimas:issue-3350
Open

feat(api): add support for project feature flags and feature flag user lists#3366
amimas wants to merge 16 commits intopython-gitlab:mainfrom
amimas:issue-3350

Conversation

@amimas
Copy link
Contributor

@amimas amimas commented Mar 9, 2026

Changes

This change introduces support for managing Project Feature Flags and Feature Flag User Lists via the API and CLI.

It adds the ProjectFeatureFlag and ProjectFeatureFlagUserList objects and their corresponding managers, which are exposed on the Project object as project.feature_flags and project.feature_flags_user_lists.

To support the specific data formats required by these GitLab APIs, this change also introduces:

  • JsonAttribute: A new attribute type to handle the strategies field, which is sent as a JSON object.
  • CommaSeparatedStringAttribute: A new attribute type to handle the user_xids field, which is sent as a comma-separated string.

Additionally, a custom save() method has been implemented for ProjectFeatureFlag to correctly handle renaming, as the flag's name is also its unique identifier.

The implementation includes:

  • API object and manager definitions.
  • Functional API tests.
  • Functional CLI tests.
  • Unit tests for the new attribute types and the custom renaming logic.

Documentation and testing

Please consider whether this PR needs documentation and tests. This is not required, but highly appreciated:

Documentation updates:

  • Added new documentation pages for Project Feature Flags and Feature Flag User Lists.
  • Renamed the existing features.rst to gitlab_features.rst and updated its content to clearly distinguish that this API/feature is for admin-only GitLab Development Feature Flags - not for project-level feature flags.

References:

Support for following API is being included in this PR

Documentation changed/clarified related to following existing feature in python-gitlab

closes #3350

@codecov
Copy link

codecov bot commented Mar 10, 2026

Codecov Report

❌ Patch coverage is 95.83333% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.75%. Comparing base (3eda669) to head (6726189).

Files with missing lines Patch % Lines
gitlab/v4/objects/feature_flags.py 92.10% 3 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #3366   +/-   ##
=======================================
  Coverage   95.75%   95.75%           
=======================================
  Files          98      100    +2     
  Lines        6054     6125   +71     
=======================================
+ Hits         5797     5865   +68     
- Misses        257      260    +3     
Flag Coverage Δ
api_func_v4 83.62% <90.27%> (-0.14%) ⬇️
cli_func_v4 78.57% <70.83%> (-0.10%) ⬇️
unit 90.23% <94.44%> (+0.06%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
gitlab/types.py 98.52% <100.00%> (+0.28%) ⬆️
gitlab/utils.py 98.59% <100.00%> (ø)
gitlab/v4/objects/__init__.py 100.00% <100.00%> (ø)
gitlab/v4/objects/feature_flag_user_lists.py 100.00% <100.00%> (ø)
gitlab/v4/objects/projects.py 98.95% <100.00%> (+0.01%) ⬆️
gitlab/v4/objects/feature_flags.py 92.10% <92.10%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds support for managing Project Feature Flags and Feature Flag User Lists in python-gitlab, enabling users to interact with the GitLab Feature Flags API and Feature Flag User Lists API via both the Python API client and CLI.

Changes:

  • Adds two new API object files (feature_flags.py and feature_flag_user_lists.py) with custom save() logic in ProjectFeatureFlag to support renaming via the original name in the URL
  • Introduces two new GitlabAttribute types: JsonAttribute (for parsing/sending JSON from the CLI) and CommaSeparatedStringAttribute (for transforming lists to CSV strings in POST/PUT bodies), plus a transform_in_post hook in utils._transform_types
  • Adds unit tests for the new attribute types and renaming logic, functional API tests, functional CLI tests, and updated/new documentation pages

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
gitlab/v4/objects/feature_flags.py New ProjectFeatureFlag and ProjectFeatureFlagManager with custom save/rename logic
gitlab/v4/objects/feature_flag_user_lists.py New ProjectFeatureFlagUserList and ProjectFeatureFlagUserListManager
gitlab/v4/objects/__init__.py Adds exports for the two new object modules
gitlab/v4/objects/projects.py Attaches the two new managers to Project
gitlab/types.py New JsonAttribute and CommaSeparatedStringAttribute types
gitlab/utils.py Extended _transform_types with transform_in_post support
tests/unit/test_types.py Unit tests for the two new attribute types
tests/unit/objects/test_project_feature_flags.py Unit test for rename save behavior
tests/unit/objects/test_project_feature_flag_user_lists.py Unit test for list→CSV transformation in POST body
tests/functional/api/test_project_feature_flags.py Functional API tests (CRUD + rename + strategy/scope deletion)
tests/functional/api/test_project_feature_flag_user_lists.py Functional API tests (CRUD + search)
tests/functional/cli/test_cli_project_feature_flags.py Functional CLI tests (CRUD + strategy creation)
tests/functional/cli/test_cli_project_feature_flag_user_lists.py Functional CLI tests (CRUD)
docs/gl_objects/project_feature_flags.rst New documentation page for feature flags
docs/gl_objects/project_feature_flag_user_lists.rst New documentation page for user lists
docs/gl_objects/gitlab_features.rst Renamed/clarified admin-only GitLab dev features doc
docs/gl_objects/projects.rst Added references to the two new documentation pages
docs/api-objects.rst Updated ToC to reference renamed and new docs

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

@amimas
Copy link
Contributor Author

amimas commented Mar 10, 2026

/rerun-workflow "Test / functional (cli_func_v4)"

@amimas
Copy link
Contributor Author

amimas commented Mar 10, 2026

/rerun-workflow "Test / functional (api_func_v4)"

amimas added 10 commits March 18, 2026 20:43
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.
Add `JsonAttribute` to `gitlab.types` to handle JSON parsing for CLI
arguments.

Update `ProjectFeatureFlagManager` to use `JsonAttribute` for the
`strategies` attribute, replacing custom `create` and `update` overrides.
This adds support for managing user lists for project feature flags.
It introduces the `ProjectFeatureFlagUserList` object and manager,
and exposes it via `project.feature_flags_user_lists`.

New type `CommaSeparatedStringAttribute` is added to handle
comma-separated string values in API requests.
Add functional tests to ensure that feature flag strategies and scopes
can be removed using the `_destroy` flag in the update payload, as
supported by the GitLab API.
The `ProjectFeatureFlag` object uses `name` as its ID attribute.
Previously, modifying the `name` of a flag object and calling `save()`
would fail because the library would attempt to send a PUT request to
the *new* name, which does not yet exist, resulting in a 404 error.

This change overrides the `save()` method in `ProjectFeatureFlag` to
correctly handle renaming. It now detects when the `name` attribute has
been modified and uses the original name for the API request URL, while
sending the new name in the request body.

This makes renaming feature flags more intuitive and consistent with the
behavior of other objects in the library.
This adds the documentation for Project Feature Flags and Feature Flag
User Lists.

It includes:
- New documentation pages for Feature Flags and User Lists.
- Updates to the Project documentation to reference the new managers.
The existing documentation for `features.rst` covered the API for
managing GitLab's internal development feature flags, which requires
administrator access. This was easily confused with the newly added
project-level feature flags API.

To prevent ambiguity for users, this commit refactors the documentation by:
- Renaming `features.rst` to `gitlab_features.rst`.
- Updating the title and adding a note to clarify its specific,
  admin-only purpose.
- Adding a cross-reference to the new project-level feature flag
  documentation.
This adds unit tests for the new logic introduced with the feature
flags API.

- Verifies the custom `save()` method in `ProjectFeatureFlag` correctly
  handles renaming by using the old name in the URL and the new name
  in the request body.
- Verifies the `CommaSeparatedStringAttribute` correctly converts a
  Python list to a comma-separated string for API calls.
- Verifies the `JsonAttribute` correctly handles JSON string parsing.
The title overline in `docs/gl_objects/project_feature_flag_user_lists.rst`
was shorter than the title text, causing a Sphinx warning.
This commit refactors the unit tests for `ProjectFeatureFlag` and
`ProjectFeatureFlagUserList` to use the shared `project` fixture from
`conftest.py`.

This change removes duplicated local fixture definitions, improving
code consistency and maintainability, and addresses feedback from
the pull request review.
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copy link
Member

@JohnVillalovos JohnVillalovos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amimas Thanks for the PR!

I left some comments/questions.

amimas added 2 commits March 21, 2026 10:42
This change uses current/latest URL format used by GitLab for
documenting their APIs.
Some test cases overwrote the fixture originally used by the test.
Ideally fixtures shouldn't be overwritten. This change refactored
those tests so that a new variable is used within the test code
instead of using the same name as the fixture.
…prove docs

The `transform_in_post` attribute controls whether data transformation
(via `get_for_api`) occurs for request bodies. Since this applies to
PUT and PATCH requests as well as POST, `transform_in_body` is a more
accurate name.

This change also improves code documentation to clarify the data
transformation flow between `types.py` and `utils.py`.
amimas added 2 commits March 21, 2026 16:11
Previously, providing malformed JSON to CLI options (such as `--strategies`)
resulted in a raw Python traceback (`JSONDecodeError`) surfacing to the user.
Additionally, whitespace-only input was implicitly converted to `None`,
causing the CLI to send `null` in the API request body, which could be
rejected by the GitLab API.

This change updates `JsonAttribute` to:
- Catch `ValueError` and `TypeError` during JSON parsing.
- Raise a `GitlabParsingError`, which the CLI catches to display a
  user-friendly error message.
- Treat whitespace-only strings as invalid JSON rather than `None`,
  requiring the user to be explicit (e.g. passing `'[]'` or `'{}'`).

Tests have been updated to verify the new error handling behavior.
This adds the `--new-name` option to the `project-feature-flag update` command,
allowing users to rename feature flags via the CLI.

The `ProjectFeatureFlagManager.update()` method is overridden to handle the
`new_name` parameter, mapping it to `name` in the API payload, while the
original `name` is used as the resource ID in the URL.

A functional test `test_project_feature_flag_cli_rename` is added to verify
this behavior.
@amimas
Copy link
Contributor Author

amimas commented Mar 21, 2026

@JohnVillalovos - Thanks for reviewing this PR. I believe I've addressed all the feedbacks so far. Please take a look when you get a chance.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

docs/gl_objects/gitlab_features.rst:3

  • The overline/underline for the RST title is shorter than the title text (32 # vs 33 characters), which can cause Sphinx/reStructuredText formatting warnings or misrendering. Extend the delimiter lines so they are at least as long as the title.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Used `responses.matchers.json_params_matchers` in unit test to validate
request body instead of manual assertion.

Modified the `update` method of `ProjectFeatureFlagManager` so that
caller provided data is not mutated or updated.
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copy link
Member

@JohnVillalovos JohnVillalovos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @amimas

LGTM, though I will want to squash it down to one commit when it gets merged.

@nejch I thought I would give you a chance to review it too.

If I don't hear anything I will plan on merging it sometime on Monday 23-Mar-2026

@amimas
Copy link
Contributor Author

amimas commented Mar 22, 2026

Thank you @JohnVillalovos . Yes, please do squash & merge. Individual commits from this feature branch wouldn't be relevant in the main branch, in my opinion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: add support for project feature flags

3 participants