Getting started with GitLab feature flags in Python

GitLab feature flags let teams deploy code without immediately exposing it to users, reducing the risk of production failures and eliminating redeployments for rollbacks. Using the Unleash Python SDK, a Flask application can retrieve flag definitions from GitLab, cache them locally, and evaluate them quickly without a network request on every check. The tutorial demonstrates a practical setup using configurable rollout strategies such as user targeting, percentage rollouts, and all-user releases.

Requirements and Project Setup

• A GitLab project with Feature Flags enabled under Settings > General > Visibility, project features, permissions.
• A fork or clone of the demo repository:
  • app.py contains the Flask and Unleash integration.
  • requirements.txt lists dependencies.
  • .env.example documents required configuration.
  • templates/index.html and static/styles.css provide the demo interface.
• The example repository is available at gitlab.com/omid-blogs/gitlab-feature-flags-demo.

How the Unleash Integration Works

• GitLab provides an Unleash-compatible API for each project, so no separate Unleash server is required.
• The SDK downloads flag definitions when the application starts.
• It refreshes the cached configuration periodically; the demo uses a 15-second interval.
• Calls to is_enabled() evaluate flags locally, avoiding a network request for each check.
• Local evaluation makes flag checks fast and more resilient to temporary connectivity problems.

Creating Feature Flags

The tutorial creates four active flags, initially using the All users strategy:

• dark_mode enables a dark color scheme.
• holiday_banner displays a festive banner.
• new_layout changes the card grid to a single-column layout.
• fun_fonts applies a playful handwritten font.

A flag must be both Active and assigned at least one strategy. An active flag without a strategy is evaluated as disabled.

Choosing Rollout Strategies

GitLab supports several built-in strategies:

• Percent rollout: Gradually enables a feature based on user ID, session ID, or random assignment.
• Percent of users: Targets a percentage of authenticated users.
• User IDs: Limits access to explicitly named users, useful for QA.
• User list: Enables a feature for a predefined user group.
• All users: Enables the feature for everyone.

A typical release process is to begin with QA users, move to a 10% rollout, and eventually enable the feature for all users entirely through GitLab’s UI.

Configuring Unleash Credentials

From the project’s Feature Flags page, the Configure panel provides:

• UNLEASH_URL, such as https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>
• UNLEASH_INSTANCE_ID, a project-scoped read-only token
• UNLEASH_APP_NAME, used to identify the application, for example production

The Instance ID can read flag state but cannot modify flags. It should still be treated as a secret because it can expose project flag information.

Running the Application Locally

• Install dependencies with:

  pip install -r requirements.txt
  

• Copy .env.example to .env and replace the placeholders with the GitLab credentials.
• Export the variables from the .env file or define them directly in the terminal.
• The three environment variables driving the integration are:
  • UNLEASH_URL
  • UNLEASH_INSTANCE_ID
  • UNLEASH_APP_NAME
• Never commit .env; the repository’s .gitignore excludes it because the Instance ID is sensitive.

The recommended approach is to use the UnleashClient Python SDK to handle polling, caching, and local feature-flag evaluation, while GitLab remains the control center for changing rollout behavior.