Repository Detection and Initialization#

When Flipt starts with the local storage backend, it inspects the target directory to determine its state:

• If the directory is empty, Flipt initializes a new bare Git repository. Bare repositories store Git data directly in the directory without a working tree, making them suitable for automated or server-side use cases.
• If the directory contains files, Flipt checks for a .git subdirectory. If present, it treats the directory as a normal Git repository, which includes a working tree with checked-out files. Flipt opens the repository using git.PlainOpen() and sets an internal flag to indicate it is a normal repository. If the .git subdirectory is absent, Flipt attempts to open the directory as a bare repository using git.Open(). If no repository exists, it initializes a new bare repository and marks it as empty to commit existing files. This logic ensures compatibility with both user-created and Flipt-managed repositories, and supports workflows where feature files exist before Git initialization (source).

Normal vs. Bare Git Repositories#

A normal Git repository contains a .git subdirectory and a working directory with checked-out files. This allows direct editing and synchronization of feature files on disk. A bare repository stores Git data in the root directory and does not have a working directory, making it suitable for server-side operations or remote synchronization.

Flipt distinguishes between these types by checking for the .git subdirectory. For normal repositories, Flipt ensures remote tracking references are set up and synchronizes the working directory after commits. For bare repositories, Flipt manages Git data but does not update files on disk (source).

Remote Tracking References and Synchronization#

Flipt automatically sets up remote tracking references for normal repositories. After opening or initializing a repository, Flipt creates a reference such as refs/remotes/origin/main pointing to the current HEAD commit hash. This ensures proper branch management and enables synchronization with remote repositories.

When changes are made (either via the Flipt UI or directly on disk), Flipt updates the working directory to match the latest commit by checking out the commit in the worktree. This keeps the actual feature files on disk in sync with the repository state. For bare repositories, this synchronization is a no-op, preserving existing behavior (source).

Remote URL Synchronization:

When reopening an existing git repository, Flipt checks if the remote URL specified in its configuration differs from the remote URL(s) in the local git config. If a difference is detected, Flipt automatically updates the local git config to match the remote URL(s) defined in the Flipt configuration. This ensures that changes to the remote URL in Flipt's configuration are always reflected in the local repository, supporting workflows where the remote location may change over time (source).

This synchronization applies to both adding a new remote to an existing repository and updating the URLs of an existing remote. If the repository has no remote, Flipt will add it as specified in the configuration. If the remote exists but has different URLs, Flipt will update them to match the configuration.

User Workflow: Initializing Repositories with Existing Features#

Flipt supports intuitive workflows for integrating existing feature files into Git:

# 1. Create directory structure with existing features
mkdir -p my-project/flags/production
cp existing-features.yaml my-project/flags/production/features.yaml

# 2. Initialize Git repository and commit existing files 
cd my-project/flags
git init
git add .
git commit -m "Initial features"

# 3. Run Flipt pointing to the flags directory
cd ..
flipt server --config config.yml # where config points to path: "flags"

Flipt will detect and work with the normal repository automatically. If the directory is empty, Flipt will initialize a bare repository and commit files as they are created (source).

Troubleshooting Tips#

• If Flipt fails to detect a repository or reports errors like "repository does not exist" or "reference not found", ensure the directory contains either a .git subdirectory (for normal repositories) or valid bare repository files. If you manually copied files into the storage folder, make sure to initialize Git and commit the files before starting Flipt (source).
• For persistent storage, use the local storage backend and set the path to a mounted volume directory. The default backend is in-memory and does not persist data to disk (source).
• Flipt includes fallback logic for ambiguous repository detection and robust error handling for directory reading, cloning, opening, and fetching. Review logs for detailed error messages if initialization fails.
• After committing changes in a normal repository, Flipt synchronizes the working directory to reflect the latest commit. For bare repositories, file synchronization on disk does not occur.
• The initialization logic is fully backward compatible; existing bare repository workflows continue to work unchanged, and ambiguous cases are handled gracefully (source).

For more details on configuration options and advanced workflows, refer to the Flipt documentation and repository code.

Git Fetch Policy Configuration#

Git Fetch Policy Configuration#

Flipt v2.3.0 introduces the fetch_policy configuration option for local storage git repositories. This option controls how Flipt behaves when a remote git fetch fails during startup:

• continue: Flipt will continue operating using the local repository data, even if the remote fetch fails. This allows the server to start and serve feature flags based on the last known state. Starting with v2.4.0, Flipt properly detects and handles DNS resolution errors and I/O timeouts when checking git repository connections. If these errors occur, the 'continue' policy ensures Flipt will still start up and operate using local data, even if the remote is temporarily unreachable.
• fail: Flipt will treat a remote fetch failure as a fatal error and will not start the server.

This option is useful for environments where remote git availability may be intermittent, or where operating with stale data is preferable to downtime. Configure fetch_policy in your Flipt server configuration file under the local storage backend settings:

storage:
  backend: local
  local:
    path: "flags"
    git:
      fetch_policy: "continue" # or "fail"

For more details, see the v2.3.0 release notes and v2.4.0 release notes.