1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
---
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Feature Flags **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4.
With Feature Flags, you can deploy your application's new features to production in smaller batches.
You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery.
Feature flags help reduce risk, allowing you to do controlled testing, and separate feature
delivery from customer launch.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo).
## How it works
GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature
toggle service.
By enabling or disabling a flag in GitLab, your application
can determine which features to enable or disable.
You can create feature flags in GitLab and use the API from your application
to get the list of feature flags and their statuses. The application must be configured to communicate
with GitLab, so it's up to developers to use a compatible client library and
[integrate the feature flags in your app](#integrate-feature-flags-with-your-application).
## Create a feature flag
To create and enable a feature flag:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **New feature flag** button.
1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`),
or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
1. Enter a description (optional, 255 characters max).
1. Enter details about how the flag should be applied:
- In GitLab 13.0 and earlier, add **Environment specs**. For each environment,
include the **Status** (default enabled) and [**Rollout strategy**](#rollout-strategy-legacy)
(defaults to **All users**).
- In GitLab 13.1 and later, add Feature Flag [**Strategies**](#feature-flag-strategies).
For each strategy, include the **Type** (defaults to [**All users**](#all-users))
and **Environments** (defaults to all environments).
1. Click **Create feature flag**.
You can change these settings by clicking the **{pencil}** (edit) button
next to any feature flag in the list.
## Rollout strategy (legacy)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience
the feature as enabled. Choose the percentage of users that the feature will be enabled
for. The rollout strategy will have no effect if the environment spec is disabled.
It can be set to:
- All users
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- Optionally, you can click the **Include additional user IDs** checkbox and add a list
of specific users IDs to enable the feature for.
- [User IDs](#user-ids)
## Feature flag strategies
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0.
> - It's deployed behind a feature flag, disabled by default.
> - It's enabled on GitLab.com.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-feature-flag-strategies). **(CORE ONLY)**
You can apply a feature flag strategy across multiple environments, without defining
the strategy multiple times.
GitLab Feature Flags use [Unleash](https://unleash.github.io) as the feature flag
engine. In Unleash, there are [strategies](https://unleash.github.io/docs/activation_strategy)
for granular feature flag controls. GitLab Feature Flags can have multiple strategies,
and the supported strategies are:
- [All users](#all-users)
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- [User IDs](#user-ids)
- [List](#list)
Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag),
or by editing an existing feature flag after creation by navigating to **Operations > Feature Flags**
and clicking **{pencil}** (edit).
### All users
Enables the feature for all users. It uses the [`default`](https://unleash.github.io/docs/activation_strategy#default)
Unleash activation strategy.
### Percent rollout (logged in users)
Enables the feature for a percentage of authenticated users. It uses the
[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid)
Unleash activation strategy.
For example, set a value of 15% to enable the feature for 15% of authenticated users.
The rollout percentage can be from 0% to 100%.
CAUTION: **Caution:**
If this strategy is selected, then the Unleash client **must** be given a user
ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
### User IDs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6.
Enables the feature for a list of target users. It is implemented
using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
Enter user IDs as a comma-separated list of values. For example,
`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on.
CAUTION: **Caution:**
The Unleash client **must** be given a user ID for the feature to be enabled for
target users. See the [Ruby example](#ruby-application-example) below.
### List
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1.
Enables the feature for lists of users created with the [Feature Flag User List API](../../../api/feature_flag_user_lists.md).
Similar to [User IDs](#user-ids), it uses the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
### Enable or disable feature flag strategies
This feature is under development, but is ready for testing. It's
deployed behind a feature flag that is **disabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
can enable it for your instance.
To enable it:
```ruby
Feature.enable(:feature_flags_new_version)
```
To disable it:
```ruby
Feature.disable(:feature_flags_new_version)
```
## Disable a feature flag for a specific environment
In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621),
to disable a feature flag for a specific environment:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, click the Pencil icon.
1. To disable the flag:
- In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the
environment spec, on the right, click the **Remove (X)** icon.
- In GitLab 13.1 and later: For each strategy it applies to, under **Environments**, delete the environment.
1. Click **Save changes**.
## Disable a feature flag for all environments
To disable a feature flag for all environments:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, slide the Status toggle to **Disabled**.
The feature flag is displayed on the **Disabled** tab.
## Integrate feature flags with your application
To use feature flags with your application, get access credentials from GitLab.
Then prepare your application with a client library.
### Get access credentials
To get the access credentials that your application needs to communicate with GitLab:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **Configure** button to view the following:
- **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 a production server, the application name would be
`production` or similar. This value is used for the environment spec evaluation.
NOTE: **Note:**
The meaning of these fields might change over time. For example, we are not sure
if **Instance ID** will be single token or multiple tokens, assigned to the
**Environment**. Also, **Application name** could describe the version of
application instead of the running environment.
### Choose a client library
GitLab implements a single backend that is compatible with Unleash clients.
With the Unleash client, developers can define, in the application code, the default values for flags.
Each feature flag evaluation can express the desired outcome if the flag isn't present in the
provided configuration file.
Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations).
### Feature flags API information
For API content, see:
- [Feature Flags API](../../../api/feature_flags.md)
- [Feature Flag Specs API](../../../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).)
- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md)
- [Legacy Feature Flags API](../../../api/feature_flags_legacy.md)
### Golang application example
Here's an example of how to integrate feature flags in a Golang application:
```golang
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))
}
```
### Ruby application example
Here's an example of how to integrate feature flags in a Ruby application.
The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**.
```ruby
#!/usr/bin/env ruby
require 'unleash'
require 'unleash/context'
unleash = Unleash::Client.new({
url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
app_name: 'production',
instance_id: '29QmjsW6KngPR5JNPMWx'
})
unleash_context = Unleash::Context.new
# Replace "123" with the id of an authenticated user.
# Note that the context's user id must be a string:
# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"
if unleash.is_enabled?("my_feature_name", unleash_context)
puts "Feature enabled"
else
puts "hello, world!"
end
```
|