- Overview
- How it works
- Adding a new feature flag
- Define environment specs
- Integrating with your application
Feature Flags
Introduced in GitLab 11.4.
Feature flags allow you to ship a project in different flavors by dynamically toggling certain functionality.
Overview
Feature Flags offer a feature toggle system for your application. They enable teams to achieve Continuous Delivery by deploying new features to production at smaller batches for controlled testing, separating feature delivery from customer launch. This helps reducing risk and allows you to easily manage which features to enable.
GitLab offers a Feature Flags interface that allows you to create, toggle and remove feature flags.
How it works
Underneath, GitLab uses unleash, a feature toggle service. GitLab provides an API where your application can talk to and get the list of feature flags you set in GitLab.
The application must be configured to talk to GitLab, so that’s up to the developers to use a compatible client library and integrate it in their app.
By setting a flag active or inactive via GitLab, your application will automatically know which features to enable or disable respectively.
Adding a new feature flag
To add a new feature flag:
- Navigate to your project’s Operations > Feature Flags.
- Click on the New Feature Flag button.
-
Give it a name.
Note: A name can contain only lowercase letters, digits, underscores (_
) and dashes (-
), must start with a letter, and cannot end with a dash (-
) or an underscore (_
). - Give it a description (optional, 255 characters max).
- Define environment specs. If you want the flag on by default, enable the catch-all wildcard spec (
*
) - Click Create feature flag.
Once a feature flag is created, the list of existing feature flags will be presented with ability to edit or remove them.
To make a feature flag active or inactive, click the pencil icon to edit it, and toggle the status for each spec.
Define environment specs
Introduced in GitLab 11.8.
In general, an application is deployed to multiple environments, such as production, staging and review apps. For example, you may not want to enable a feature flag on production until your QA team has first confirmed that the feature is working correctly on testing environments.
To handle these situations, you can enable a feature flag on a particular environment with Environment specs. You can define multiple specs per flag so that you can control your feature flag more granularly.
To define specs for each environment:
- Navigate to your project’s Operations > Feature Flags.
- Click on the New Feature Flag button or edit an existing flag.
- Set the status of the default spec (
*
). This status will be used for all environments. - If you want to enable/disable the feature on a specific environment, create a new spec and type the environment name.
- Set the status of the additional spec. This status takes precedence over the default spec’s status since we always use the most specific match available.
- Click Create feature flag or Update feature flag.
Integrating with your application
In order to use Feature Flags, you need to first get the access credentials from GitLab and then prepare your application and hook it with a client library.
Configuring Feature Flags
To get the access credentials that your application will need to talk to GitLab:
- Navigate to your project’s Operations > Feature Flags.
- Click on the Configure button to see the values:
- API URL: URL where the client (application) connects to get a list of feature flags.
- Instance ID: Unique token that authorizes the retrieval of the feature flags.
-
Application name: The name of the running environment. For instance,
if the application runs for production server, application name would be
production
or similar. This value is used for the environment spec evaluation.
Client libraries
GitLab currently implements a single backend that is compatible with Unleash clients.
Unleash clients allow the developers to define in the app’s code the default values for flags. Each feature flag evaluation can express the desired outcome in case the flag isn’t present on the provided configuration file.
Unleash currently offers a number of official SDKs for various frameworks and a number of community contributed libraries.
Official clients:
- unleash/unleash-client-java
- unleash/unleash-client-node
- unleash/unleash-client-go
- unleash/unleash-client-ruby
Community contributed clients:
- stiano/unleash-client-dotnet (.Net Core)
- onybo/unleash-client-core (.Net Core)
- aes/unleash-client-python (Python 3)
Golang application example
Here’s an example of how to integrate the feature flags in a Golang application:
package main
import (
"io"
"log"
"net/http"
"github.com/Unleash/unleash-client-go"
)
type metricsInterface struct {
}
func init() {
unleash.Initialize(
unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
unleash.WithAppName("production"),
unleash.WithListener(&metricsInterface{}),
)
}
func helloServer(w http.ResponseWriter, req *http.Request) {
if unleash.IsEnabled("my_feature_name") {
io.WriteString(w, "Feature enabled\n")
} else {
io.WriteString(w, "hello, world!\n")
}
}
func main() {
http.HandleFunc("/", helloServer)
log.Fatal(http.ListenAndServe(":8080", nil))
}
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc