Skip to main content
Flipt v2 stores all of its resources in git repositories. This section describes how those git repositories are persisted and managed.

​
Identifiers

Each storage backend has an identifier that is used to reference the storage backend in the configuration, such as when specifying the storage backend for an environment. Identifiers can be any string value but must be unique. Flipt creates a default identifier and storage backend for you automatically if you don’t specify one. In the following example, we’ve defined two storage backends:
  • staging is a local storage backend that will serve Flipt flag state from a local directory.
  • development is a memory storage backend that will serve Flipt flag state from an in-memory store.
storage:
  staging: # id
    name: "staging"
    backend:
      type: local
      path: "/path/to/staging/repository"
  development: # id
    name: "development"
    backend:
      type: memory

​
Backends

Flipt v2 supports the following storage backends:

​
Local

The purpose of this backend type is to support serving Flipt flag state directly from your local filesystem in a git repository. This allows the the data to be persisted between server restarts. Flipt will periodically rebuild its state from the local disk every 10 seconds. 
storage:
  backend:
    type: local
    path: "."
The above configuration will create a local storage backend with the identifier default and serve Flipt flag state from the current working directory. For guidance on setting up Git repositories with existing feature files, see our Git Repository Initialization guide.

​
Memory

The purpose of this backend type is to support serving Flipt flag state from an in-memory store. This is useful for development and testing purposes where you don’t want to persist flag state to disk. 
storage:
  backend:
    type: memory
The above configuration will create a memory storage backend with the identifier default and serve Flipt flag state from an in-memory store.

​
Git Remotes

Flipt v2 supports syncing flag state to and from a remote git repository. 
storage:
  staging:
    remote: "https://github.com/flipt-io/example.git"
    branch: "main"
    poll_interval: "30s"
    fetch_policy: "strict"
    credentials: "github"
    backend:
      type: memory
This configuration will create a git storage backend with the identifier staging in memory and will sync flag state to and from the remote repository.

​
Fetch Policy

The fetch_policy configuration option controls how Flipt handles connection-related issues when attempting to fetch from a remote Git repository.

​
Available Policies

  • strict (default): Flipt will fail and return an error if it encounters connection issues when trying to fetch from the remote repository. This ensures that any connectivity problems are immediately visible and must be resolved.
  • lenient: Flipt will continue operating even if connection issues prevent fetching from the remote repository. This allows Flipt to remain functional during temporary network issues or remote repository unavailability.

​
Usage Example

storage:
  production:
    remote: "https://github.com/company/flags.git"
    fetch_policy: "strict" # Fail fast on connection issues
    backend:
      type: local
      path: "/var/lib/flipt"

  development:
    remote: "https://github.com/company/flags.git"
    fetch_policy: "lenient" # Continue operation during connection issues
    backend:
      type: memory
In production environments, consider using strict to ensure that connectivity issues are detected and resolved promptly, preventing potential configuration drift between your remote repository and running Flipt instances.

​
Conflict Resolution

Conflicts can occur when syncing flag state to and from a remote repository. The conflict resolution strategy in Flipt v2 is currently rudimentary and we aim to improve this in future releases. When syncing flag state to and from a remote repository, Flipt will behave as follows:
  • Remote state is synced to the local storage backend using the configured poll_interval
  • On writes to the Flipt server, the local storage backend will create a new commit and push it to the remote repository
  • Flipt keeps track of the last commit hash for each storage backend
  • If a write is made to a flag state file that has been modified since the last commit, Flipt will refuse to push the changes to the remote repository and will instead return an error
  • If a write is made to a flag state file that has not been modified since the last commit, Flipt will push the changes to the remote repository

​
Credentials

Credentials enable the ability to authenticate with remote repositories. Supported authentication schemes are:
  • basic
  • ssh
  • access_token
  • github_app
Credentials are configured using the credentials configuration section and use identifiers to reference the credentials in the configuration.
This means that you can use the same credentials for multiple storage backends if needed.

​
Basic

Basic authentication is a username and password pair. 
credentials:
  github:
    type: basic
    basic:
      username: < username >
      password: < github-personal-access-token >

​
SSH

In order to configure a git remote with SSH, you will need to generate an SSH key-pair and configure your repository provider with the public key. GitHub has some excellent documentation regarding how to generate and install your credentials here. Once you have your private key credentials you will need to configure Flipt to use them. This can be done via the storage.git.authentication.ssh configuration section: 
credentials:
  github:
    type: ssh
    ssh:
      user: git
      private_key_path: ~/.ssh/id_rsa
      private_key_bytes: <raw-key-bytes> # alternatively pass the raw bytes inline
insecure_ignore_host_key is not encouraged for production use, and is false by default. Instead, you are advised to put the key fingerprint in the known hosts file where you are running Flipt. For example, for GitHub you can do ssh-keyscan github.com >> ~/.ssh/known_hosts on the Flipt host.Container Deployment: When running Flipt in containers, mount the known_hosts file to the system-wide SSH path instead of a user directory. For example, with Docker
volumes:
  - /path/to/your/known_hosts:/etc/ssh/ssh_known_hosts:ro

​
Access Token

Access tokens are a type of credential that are used to authenticate with a remote repository. These can be used for any remote repository provider that supports access tokens such as GitHub, GitLab, Gitea, and Azure DevOps. 
credentials:
  github:
    type: access_token
    access_token: < github-access-token >

​
GitHub App

GitHub App authentication provides a more secure alternative to personal access tokens (PATs) for authenticating with GitHub repositories. GitHub App tokens are short-lived, offer higher rate limits, and provide more granular permissions. To use this credential type, you need to create a GitHub App and install it on your repository or organization. You can provide the private key either as a file path or as raw bytes inline: 
credentials:
  github:
    type: github_app
    github_app:
      client_id: < github-app-client-id >
      installation_id: < github-app-installation-id >
      private_key_path: /path/to/private-key.pem
Alternatively, you can pass the private key bytes inline: 
credentials:
  github:
    type: github_app
    github_app:
      client_id: < github-app-client-id >
      installation_id: < github-app-installation-id >
      private_key_bytes: < raw-private-key-bytes >
You must provide either private_key_path or private_key_bytes, but not both.
For GitHub Enterprise Server, you can optionally specify a custom API URL: 
credentials:
  github:
    type: github_app
    github_app:
      client_id: < github-app-client-id >
      installation_id: < github-app-installation-id >
      private_key_path: /path/to/private-key.pem
      api_url: "https://github.example.com/api/v3"