|
| 1 | +--- |
| 2 | +title: Git Repository Initialization |
| 3 | +description: Learn how to initialize Git repositories for existing feature flag configurations in Flipt v2. |
| 4 | +--- |
| 5 | + |
| 6 | +This guide explains how to set up Git repository initialization for existing feature flag configurations in Flipt v2. This is particularly useful when you already have `features.yaml` or `features.yml` files but need to initialize version control for them. |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +Flipt v2 supports automatic Git repository detection and initialization for existing feature files when using the local storage backend. This addresses the common workflow where you have existing feature flag configurations but no Git repository initialized yet. |
| 11 | + |
| 12 | +Previously, when users had existing feature files but no Git repository, Flipt would fail with errors like: |
| 13 | + |
| 14 | +- `"repository does not exist"` |
| 15 | +- `"reference not found"` |
| 16 | + |
| 17 | +With the enhancements introduced in Flipt v2, you can now follow an intuitive workflow to initialize Git repositories for your existing feature configurations. |
| 18 | + |
| 19 | +## Supported File Formats |
| 20 | + |
| 21 | +Flipt v2 supports both YAML file extensions for feature configurations: |
| 22 | + |
| 23 | +- `features.yaml` (recommended) |
| 24 | +- `features.yml` |
| 25 | + |
| 26 | +Both formats work identically and you can use whichever extension you prefer. |
| 27 | + |
| 28 | +## Basic Setup Workflow |
| 29 | + |
| 30 | +The typical workflow for initializing a Git repository with existing feature files is: |
| 31 | + |
| 32 | +### 1. Organize Your Feature Files |
| 33 | + |
| 34 | +Create a directory structure with your existing features: |
| 35 | + |
| 36 | +```bash |
| 37 | +mkdir -p my-project/flags/production |
| 38 | +cp existing-features.yaml my-project/flags/production/features.yaml |
| 39 | +``` |
| 40 | + |
| 41 | +### 2. Initialize Git Repository |
| 42 | + |
| 43 | +Navigate to your flags directory and initialize Git: |
| 44 | + |
| 45 | +```bash |
| 46 | +cd my-project/flags |
| 47 | +git init |
| 48 | +git add . |
| 49 | +git commit -m "Initial features" |
| 50 | +``` |
| 51 | + |
| 52 | +### 3. Configure Flipt |
| 53 | + |
| 54 | +Create a Flipt configuration that points to your flags directory: |
| 55 | + |
| 56 | +```yaml |
| 57 | +storage: |
| 58 | + local: |
| 59 | + name: "local" |
| 60 | + backend: |
| 61 | + type: local |
| 62 | + path: "flags" # Path to your flags directory |
| 63 | + branch: "main" |
| 64 | + |
| 65 | +environments: |
| 66 | + default: |
| 67 | + name: "Default" |
| 68 | + storage: "local" |
| 69 | + default: true |
| 70 | +``` |
| 71 | +
|
| 72 | +### 4. Start Flipt Server |
| 73 | +
|
| 74 | +Run Flipt pointing to your configuration: |
| 75 | +
|
| 76 | +```bash |
| 77 | +cd .. # Back to my-project directory |
| 78 | +flipt server --config config.yml |
| 79 | +``` |
| 80 | + |
| 81 | +## Repository Detection |
| 82 | + |
| 83 | +Flipt v2 includes enhanced repository detection logic that can handle: |
| 84 | + |
| 85 | +1. **Normal Git Repositories**: Standard repositories created with `git init` (with `.git` subdirectory) |
| 86 | +2. **Bare Repositories**: Repositories managed internally by Flipt (Git files in root directory) |
| 87 | +3. **Automatic Fallback**: Graceful handling when repository types are ambiguous |
| 88 | + |
| 89 | +The system automatically: |
| 90 | + |
| 91 | +- Detects the repository type |
| 92 | +- Creates necessary remote tracking references (`refs/remotes/origin/main`) |
| 93 | +- Sets up proper branch management for Flipt's operations |
| 94 | + |
| 95 | +## Working Directory Synchronization |
| 96 | + |
| 97 | +When you make changes through the Flipt UI, the system automatically: |
| 98 | + |
| 99 | +- Updates the actual `.yaml` files on disk for normal repositories |
| 100 | +- Maintains backward compatibility with existing bare repository workflows |
| 101 | +- Synchronizes changes back to the filesystem |
| 102 | + |
| 103 | +This means changes made in the Flipt web interface will be reflected in your actual feature files, allowing you to see modifications through standard Git tools. |
| 104 | + |
| 105 | +## Configuration Examples |
| 106 | + |
| 107 | +### Basic Local Storage |
| 108 | + |
| 109 | +```yaml |
| 110 | +storage: |
| 111 | + backend: |
| 112 | + type: local |
| 113 | + path: "." # Current directory |
| 114 | +``` |
| 115 | +
|
| 116 | +### Multiple Environments |
| 117 | +
|
| 118 | +```yaml |
| 119 | +storage: |
| 120 | + staging: |
| 121 | + name: "Staging" |
| 122 | + backend: |
| 123 | + type: local |
| 124 | + path: "flags/staging" |
| 125 | + branch: "staging" |
| 126 | + production: |
| 127 | + name: "Production" |
| 128 | + backend: |
| 129 | + type: local |
| 130 | + path: "flags/production" |
| 131 | + branch: "main" |
| 132 | + |
| 133 | +environments: |
| 134 | + staging: |
| 135 | + name: "Staging" |
| 136 | + storage: "staging" |
| 137 | + production: |
| 138 | + name: "Production" |
| 139 | + storage: "production" |
| 140 | + default: true |
| 141 | +``` |
| 142 | +
|
| 143 | +### With Remote Git Repository |
| 144 | +
|
| 145 | +You can also combine local storage with remote Git synchronization: |
| 146 | +
|
| 147 | +```yaml |
| 148 | +storage: |
| 149 | + local: |
| 150 | + name: "Local with Remote" |
| 151 | + remote: "https://github.com/your-org/feature-flags.git" |
| 152 | + branch: "main" |
| 153 | + poll_interval: "30s" |
| 154 | + credentials: "github" |
| 155 | + backend: |
| 156 | + type: local |
| 157 | + path: "flags" |
| 158 | + |
| 159 | +environments: |
| 160 | + default: |
| 161 | + name: "Default" |
| 162 | + storage: "local" |
| 163 | + default: true |
| 164 | + |
| 165 | +credentials: |
| 166 | + github: |
| 167 | + type: access_token |
| 168 | + access_token: "your-github-token" |
| 169 | +``` |
| 170 | +
|
| 171 | +## Docker Usage |
| 172 | +
|
| 173 | +When using Docker, you can initialize the repository in your container build process: |
| 174 | +
|
| 175 | +```dockerfile |
| 176 | +FROM docker-registry.example.com/base:latest as builder |
| 177 | + |
| 178 | +COPY main/features /tmp/data |
| 179 | +RUN cd /tmp/data && \ |
| 180 | + git config --global init.defaultBranch main && \ |
| 181 | + git init && \ |
| 182 | + git config user.name "Flipt Container" && \ |
| 183 | + git config user.email "[email protected]" && \ |
| 184 | + git add . && \ |
| 185 | + git commit -m "Initial commit with feature flags" |
| 186 | + |
| 187 | +FROM docker.flipt.io/flipt/flipt:v2 |
| 188 | + |
| 189 | +COPY --from=builder --chown=flipt:flipt /tmp/data /data |
| 190 | +COPY --chown=flipt:flipt main/config.yml /config.yml |
| 191 | + |
| 192 | +USER flipt |
| 193 | +EXPOSE 8080 9000 |
| 194 | + |
| 195 | +CMD ["/flipt", "server", "--config", "/config.yml"] |
| 196 | +``` |
| 197 | + |
| 198 | +## Troubleshooting |
| 199 | + |
| 200 | +### Repository Does Not Exist Error |
| 201 | + |
| 202 | +If you see this error, ensure that: |
| 203 | + |
| 204 | +1. Your `path` configuration points to a valid directory |
| 205 | +2. The directory contains your feature files |
| 206 | +3. Git is properly initialized in the directory |
| 207 | + |
| 208 | +### Features Not Loading |
| 209 | + |
| 210 | +Check that: |
| 211 | + |
| 212 | +1. Your feature files use the correct naming: `features.yaml` or `features.yml` |
| 213 | +2. The files are in the correct directory structure |
| 214 | +3. The YAML syntax is valid |
| 215 | + |
| 216 | +### Changes Not Persisting |
| 217 | + |
| 218 | +For normal Git repositories: |
| 219 | + |
| 220 | +- Changes made in the UI should automatically sync to your files |
| 221 | +- Check that Flipt has write permissions to the directory |
| 222 | +- Verify that the Git repository is properly initialized |
| 223 | + |
| 224 | +## Best Practices |
| 225 | + |
| 226 | +1. **Use Descriptive Commit Messages**: When initializing your repository, use clear commit messages that describe your feature set |
| 227 | +2. **Organize by Environment**: Structure your directories to separate different environments (staging, production, etc.) |
| 228 | +3. **Regular Commits**: Consider setting up automated commits for changes made through the UI |
| 229 | +4. **Backup Strategy**: Implement a backup strategy for your feature flag configurations |
| 230 | +5. **File Naming**: Stick to either `.yaml` or `.yml` consistently across your project |
| 231 | + |
| 232 | +## Backward Compatibility |
| 233 | + |
| 234 | +This enhancement is fully backward compatible: |
| 235 | + |
| 236 | +- Existing bare repository workflows continue to work unchanged |
| 237 | +- All existing functionality is preserved |
| 238 | +- Safe fallbacks handle edge cases gracefully |
| 239 | + |
| 240 | +You can migrate existing setups without any breaking changes. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments