flipt-io · markphelps · Aug 11, 2025 · Aug 11, 2025 · Aug 11, 2025 · Aug 12, 2025
diff --git a/.github/flipt-problem-matcher.json b/.github/flipt-problem-matcher.json
@@ -0,0 +1,16 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "flipt-validate",
+      "severity": "error",
+      "pattern": [
+        {
+          "regexp": "\\{\"message\":\"([^\"]*(?:\\\\.[^\"]*)*)\",\"location\":\\{\"file\":\"([^\"]+)\",\"line\":(\\d+)\\}\\}",
+          "message": 1,
+          "file": 2,
+          "line": 3
+        }
+      ]
+    }
+  ]
+}
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build
+```bash
+npm run build          # Compile TypeScript to JavaScript (src -> lib)
+npm run package        # Bundle with ncc for distribution (creates dist/index.js)
+npm run all           # Full build pipeline: build, format, lint, package, and test
+```
+
+### Code Quality
+```bash
+npm run lint          # Run ESLint on TypeScript source files
+npm run format        # Format code with Prettier
+npm run format-check  # Check formatting without modifying files
+```
+
+### Testing
+```bash
+npm test              # Run Jest tests (looks for *.test.ts files)
+```
+
+## Architecture
+
+This is a GitHub Action for installing the Flipt CLI. The codebase follows a standard GitHub Action structure:
+
+### Key Components
+
+1. **Entry Point**: `src/main.ts`
+   - Parses action inputs (version, args, working-directory, GITHUB_TOKEN)
+   - Orchestrates Flipt CLI download and execution
+   - Handles error reporting to GitHub Actions
+   - Registers problem matchers for validate commands
+
+2. **CLI Downloader**: `src/lib/cli.ts`
+   - Downloads platform-specific Flipt binaries from GitHub releases
+   - Supports linux/darwin on x86_64/arm64 architectures
+   - Caches downloaded binaries using GitHub Actions tool cache
+   - Uses Octokit for authenticated GitHub API calls
+   - Implements intelligent version resolution for v1/v2 compatibility
+
+3. **Execution Layer**: `src/lib/exec.ts`
+   - Wrapper around @actions/exec for running shell commands
+   - Returns structured results with stdout/stderr and success status
+
+4. **Environment**: `src/lib/environment.ts`
+   - Validates required environment variables using envalid
+   - Currently requires GITHUB_WORKSPACE
+
+### Build Process
+
+The action uses a dual compilation approach:
+1. TypeScript compilation (`tsc`): src/*.ts → lib/*.js
+2. ncc bundling: Creates single dist/index.js with all dependencies
+
+The action.yml specifies `dist/index.js` as the entry point, so always run `npm run package` before committing distribution changes.
+
+### Action Inputs
+
+- `version`: Flipt version to install (default: "latest")
+- `args`: Arguments to pass to flipt command
+- `working-directory`: Directory to run flipt in (default: GITHUB_WORKSPACE)
+- `GITHUB_TOKEN`: Required for GitHub API rate limiting
+
+### Version Resolution
+
+The action supports both Flipt v1 and v2 with intelligent version resolution:
+
+| Pattern | Resolves To | Example |
+|---------|-------------|---------|
+| `latest` | Latest v1 release (backward compatible) | `latest` |
+| `v1`, `latest-v1` | Latest v1.x release | `v1` |
+| `v2`, `latest-v2` | Latest v2.x release | `v2` |
+| `vX.Y.Z` | Specific version | `v1.47.0`, `v2.0.0` |
+
+**Implementation Details:**
+- `resolveVersion()` function in `src/lib/cli.ts` handles pattern matching
+- `getLatestVersionByMajor()` filters GitHub releases by major version prefix
+- Maintains backward compatibility by defaulting `latest` to v1
+- Supports both database-backed (v1) and Git-native (v2) Flipt variants
+
+### Problem Matchers
+
+The action includes automatic problem matcher registration for `flipt validate` commands:
+
+- **File**: `.github/flipt-problem-matcher.json` - JSON configuration for parsing validation errors
+- **Auto-registration**: When `validate` command is detected, problem matcher is automatically registered
+- **JSON format**: Automatically appends `--format json` to validate commands for structured error parsing
+- **Annotations**: Creates inline GitHub annotations on PR files when validation errors occur
+
+**Implementation Details:**
+- `registerFliptProblemMatcher()` function in `src/main.ts` handles registration
+- Uses `::add-matcher::` GitHub Actions command to register the matcher
+- Regex pattern matches JSON error objects: `{"message":"...","location":{"file":"...","line":...}}`
+- Only activates for commands containing `validate` argument
+
+## Important Notes
+
+- The action runs on Node.js 20 runtime
+- Always run `npm run all` before pushing to ensure code passes all checks
+- The dist/ folder must be committed as it contains the bundled action code
+- Test files use Jest with ts-jest for TypeScript support
diff --git a/README.md b/README.md
@@ -2,11 +2,21 @@
 
 ![GitHub Release](https://img.shields.io/github/v/release/flipt-io/setup-action)
 
-This action installs [Flipt](https://flipt.io) in your GitHub Actions workflow.
+This action installs [Flipt](https://flipt.io) in your GitHub Actions workflow, supporting both Flipt v1 and v2.
 
 You can pass additional arguments to the `flipt` command using the `args` input. If no arguments are provided, `flipt` will be installed and run with the `--help` flag.
 
-Any of the [Flipt CLI commands](https://www.flipt.io/docs/cli/overview) can be run using this action.
+Both Flipt v1 and v2 CLI commands can be run using this action. The version you install determines which commands are available.
+
+## Problem Matchers
+
+When running `flipt validate`, this action automatically registers a **problem matcher** that creates GitHub annotations for validation errors directly on your PR files. This provides immediate feedback on configuration issues without having to dig through CI logs.
+
+**Features:**
+- **Inline annotations** on files with validation errors
+- **Precise line numbers** showing exactly where issues occur  
+- **Automatic activation** when using `validate` commands
+- **JSON parsing** for structured error information
 
 ## Supported Platforms
 
@@ -15,78 +25,218 @@ Any of the [Flipt CLI commands](https://www.flipt.io/docs/cli/overview) can be r
 - MacOS x86_64
 - MacOS arm64
 
-## Examples
+## Version Selection
+
+This action supports both Flipt v1 and v2. Choose your version based on your needs:
+
+- **Flipt v1**: Traditional database-backed feature flag management
+  - Docs: <https://www.flipt.io/docs>
+- **Flipt v2**: Git-native feature flag management with declarative APIs
+  - Docs: <https://docs.flipt.io/v2>
+
+### Version Resolution
+
+The `version` input supports several patterns:
+
+| Pattern     | Description                                             | Example             |
+| ----------- | ------------------------------------------------------- | ------------------- |
+| `latest`    | Latest v1 release (default, for backward compatibility) | `latest`            |
+| `v1`        | Latest v1 release                                       | `v1`                |
+| `latest-v1` | Latest v1 release (explicit)                            | `latest-v1`         |
+| `v2`        | Latest v2 release                                       | `v2`                |
+| `latest-v2` | Latest v2 release (explicit)                            | `latest-v2`         |
+| `vX.Y.Z`    | Specific version                                        | `v1.47.0`, `v2.0.0` |
+
+**Examples:**
 
-### Validate
+```yaml
+# Use latest v1 (backward compatible default)
+version: latest
+
+# Use latest v1 (explicit)
+version: v1
+
+# Use latest v2
+version: v2
+
+# Use specific versions
+version: v1.47.0
+version: v2.0.0
+```
+
+## Examples for Flipt v1
+
+### Validate (v1)
 
 Docs: <https://www.flipt.io/docs/cli/commands/validate>
 
-This example installs Flipt and runs `flipt validate` against the repository root.
+This example installs Flipt v1 and runs `flipt validate` against the repository root.
 
 ```yaml
 validate:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3
 
-    - uses: flipt-io/setup-action@v0.2.0
+    - uses: flipt-io/setup-action@v0.5.0
       with:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # required to download flipt cli without rate limiting
+        version: v1 # Use latest v1 release
         # Optional, additional arguments to pass to the `flipt` command
         # args:
-        # Optional, the version of Flipt to install, defaults to the latest release
-        # version:
         # Optional, the directory to run Flipt against, defaults to the repository root
         # working-directory:
 
     - run: flipt validate
 ```
 
-### OCI Bundle and Push
+> **💡 Pro Tip:** Problem matchers are automatically enabled! When validation errors occur, you'll see annotations directly on the affected lines in your PR.
+
+### OCI Bundle and Push (v1)
 
 Docs: <https://www.flipt.io/docs/cli/commands/bundle/build>
 
-This example installs Flipt and runs `flipt bundle build` against the repository root. It then pushes the bundle to a registry with `flipt bundle push`, allowing you to store and share your feature flag data as an OCI artifact.
+This example installs Flipt v1 and runs `flipt bundle build` against the repository root. It then pushes the bundle to a registry with `flipt bundle push`, allowing you to store and share your feature flag data as an OCI artifact.
 
 ```yaml
-validate:
+bundle:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3
 
-    - uses: flipt-io/setup-action@v0.2.0
+    - uses: flipt-io/setup-action@v0.5.0
       with:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # required to download flipt cli without rate limiting
+        version: v1 # Use latest v1 release
         # Optional, additional arguments to pass to the `flipt` command
         # args:
-        # Optional, the version of Flipt to install, defaults to the latest release
-        # version:
         # Optional, the directory to run Flipt against, defaults to the repository root
         # working-directory:
 
     - name: Get UUID
-        id: uuid
-        run: | 
-            echo "uuid=$(uuidgen)" >> $GITHUB_OUTPUT
-        
+      id: uuid
+      run: |
+        echo "uuid=$(uuidgen)" >> $GITHUB_OUTPUT
+
     # Build the bundle and push it to an ephemeral registry (available for 1 hour)
     - name: Build and Push bundle
       run: |
-        flipt bundle build {{ steps.uuid.outputs.uuid }}:latest ttl.sh/${{ steps.uuid.outputs.uuid }}:1h
+        flipt bundle build -t ttl.sh/${{ steps.uuid.outputs.uuid }}:1h
         flipt bundle push ttl.sh/${{ steps.uuid.outputs.uuid }}:1h
 ```
 
+### Import/Export (v1)
+
+Docs: <https://www.flipt.io/docs/operations/import-export>
+
+Example of importing and exporting feature flag data:
+
+```yaml
+import-export:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v3
+
+    - uses: flipt-io/[email protected]
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        version: v1
+
+    # Export flags from a running Flipt instance
+    - name: Export flags
+      run: flipt export --address http://flipt.my.org > flags.yaml
+
+    # Import flags to another instance
+    - name: Import flags
+      run: flipt import --address http://flipt-staging.my.org < flags.yaml
+```
+
+## Examples for Flipt v2
+
+### Validate (v2)
+
+Docs: <https://docs.flipt.io/v2/cli/overview>
+
+Flipt v2 uses the same `validate` command but works with Git-native storage. Note that v2 does not support bundle or import/export operations - flags are managed directly through Git.
+
+```yaml
+validate-v2:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v3
+
+    - uses: flipt-io/[email protected]
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        version: v2 # Use latest v2 release
+        # Optional, the directory to run Flipt against, defaults to the repository root
+        # working-directory:
+
+    - run: flipt validate
+```
+
+> **💡 Pro Tip:** Problem matchers are automatically enabled for validation! Any validation errors will appear as annotations on your PR files.
+
+### Working with Git Storage (v2)
+
+Flipt v2 is Git-native and can work directly with your repository:
+
+```yaml
+git-workflow-v2:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v3
+
+    - uses: flipt-io/[email protected]
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        version: v2.0.0 # Use specific v2 version
+
+    # Validate flag configurations in your Git repository
+    - name: Validate flags
+      run: flipt validate
+
+    # Work with Git-stored flags directly
+    - name: Show flipt config
+      run: flipt config
+```
+
+## Key Differences Between v1 and v2
+
+### Flipt v1
+
+- Database-backed storage (PostgreSQL, MySQL, SQLite)
+- Traditional client-server architecture
+- Bundle, Import/Export commands for data migration
+- Suitable for centralized flag management
+- CLI Docs: <https://www.flipt.io/docs/cli/overview>
+
+### Flipt v2
+
+- Git-native storage (flags stored in Git repositories)
+- Declarative API approach
+- Multi-environment support
+- Direct Git integration for flag management
+- No bundle/import/export operations (uses Git directly)
+- CLI Docs: <https://docs.flipt.io/v2/cli/overview>
+
+For more detailed information:
+
+- [Flipt v1 Documentation](https://www.flipt.io/docs)
+- [Flipt v2 Documentation](https://docs.flipt.io/v2)
+- [v2 Introduction and Differences](https://docs.flipt.io/v2/introduction)
+
 ## Customizing
 
 ### inputs
 
 Following inputs can be used as `step.with` keys
 
-| Name                | Type   | Description                                                                |
-| ------------------- | ------ | -------------------------------------------------------------------------- |
-| `working-directory` | string | **Optional**. The directory to validate, defaults to the repository root   |
-| `version`           | string | **Optional**. The version of Flipt to install, defaults to the latest release. |
-| `args`              | string | **Optional**. Additional arguments to pass to the `flipt` command |
+| Name                | Type   | Description                                                                        |
+| ------------------- | ------ | ---------------------------------------------------------------------------------- |
+| `working-directory` | string | **Optional**. The directory to validate, defaults to the repository root           |
+| `version`           | string | **Optional**. The version of Flipt to install, defaults to the latest release.     |
+| `args`              | string | **Optional**. Additional arguments to pass to the `flipt` command                  |
 | `GITHUB_TOKEN`      | string | **Required**. The GitHub token to use to download Flipt CLI without rate limiting. |
 
 ## Development