Implementation:Treeverse LakeFS Action YAML Configuration

Knowledge Sources	lakeFS lakeFS Documentation
Domains	Data_Quality, Automation
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete pattern for defining action hook behavior through YAML configuration files stored under the _lakefs_actions/ path prefix in a lakeFS repository.

Description

Action YAML configuration files are the declarative mechanism by which lakeFS action hooks are defined. Each YAML file describes one action consisting of a name, one or more triggering events, and one or more hooks to execute when those events occur.

These configuration files are stored as regular objects within the repository under the reserved _lakefs_actions/ path prefix. Any file matching the pattern _lakefs_actions/*.yaml (or _lakefs_actions/*.yml) is automatically recognized by lakeFS as an action definition.

Because action configurations are stored as repository objects, they are:

• Version-controlled -- Changes to hook definitions are tracked through commits
• Branch-scoped -- Different branches can have different hook configurations
• Mergeable -- Hook definitions follow the same merge semantics as data objects

Usage

Use YAML action configuration when you need to:

• Define which repository events should trigger automated validation
• Specify webhook endpoints or Lua scripts for data quality checks
• Configure branch-specific hook behavior (e.g., stricter checks on main)
• Set up post-event notifications and pipeline triggers

Code Reference

Source Location

• Repository: lakeFS
• File: esti/hooks.go (lines 653-697, parseAndUploadActions function)

Schema

The YAML action configuration follows this schema:

name: string                    # Human-readable action name
description: string             # Optional description of the action
on:                             # Event triggers (one or more)
  pre-commit:                   # Event type
    branches:                   # Optional branch filter
      - "main"
      - "staging/*"
  post-merge:                   # Multiple events can be specified
    branches:
      - "main"
hooks:                          # List of hooks to execute
  - id: string                  # Unique hook identifier within this action
    type: webhook | lua         # Hook execution type
    description: string         # Optional hook description
    properties:                 # Type-specific properties
      # For type: webhook
      url: string               # Target URL for HTTP callback
      timeout: string           # Optional timeout (e.g., "1m30s")
      query_params:             # Optional query parameters
        key: value
      headers:                  # Optional HTTP headers
        key: value

      # For type: lua
      script: string            # Inline Lua script or path to .lua file
      args:                     # Optional arguments passed to script
        key: value

Supported Events

Event	Phase	Triggered By	Gate Behavior
pre-commit	Before	Commit operation	Blocks commit on failure
post-commit	After	Commit operation	Notification only
pre-merge	Before	Merge operation	Blocks merge on failure
post-merge	After	Merge operation	Notification only
pre-create-branch	Before	Branch creation	Blocks creation on failure
post-create-branch	After	Branch creation	Notification only
pre-delete-branch	Before	Branch deletion	Blocks deletion on failure
post-delete-branch	After	Branch deletion	Notification only
pre-create-tag	Before	Tag creation	Blocks creation on failure
post-create-tag	After	Tag creation	Notification only
pre-delete-tag	Before	Tag deletion	Blocks deletion on failure
post-delete-tag	After	Tag deletion	Notification only

Usage Examples

Webhook Pre-Commit Validation

name: pre-commit-schema-validation
description: Validate data schema before commits to main
on:
  pre-commit:
    branches:
      - main
      - "release/*"
hooks:
  - id: check_schema
    type: webhook
    description: Validate Parquet schema against registry
    properties:
      url: "https://my-validator.example.com/validate"
      timeout: "1m30s"
      headers:
        Authorization: "Bearer ${ENV.VALIDATOR_TOKEN}"

Lua Post-Commit Notification

name: post-commit-notify
description: Send notification after successful commits
on:
  post-commit:
    branches:
      - main
hooks:
  - id: notify_slack
    type: lua
    description: Post commit summary to Slack
    properties:
      script: |
        local json = require("encoding/json")
        local http = require("net/http")
        local action = require("lakefs/action")

        local body = json.marshal({
          text = "New commit on " .. action.branch_id .. ": " .. action.commit_id
        })

        http.request("https://hooks.slack.com/services/XXX", {
          method = "POST",
          body = body,
          headers = { ["Content-Type"] = "application/json" }
        })

Pre-Merge Quality Gate

name: pre-merge-quality-check
description: Validate data quality before merging to main
on:
  pre-merge:
    branches:
      - main
hooks:
  - id: check_row_count
    type: webhook
    properties:
      url: "https://data-quality.example.com/row-count-check"
  - id: check_freshness
    type: webhook
    properties:
      url: "https://data-quality.example.com/freshness-check"
      timeout: "2m"

Uploading an Action Configuration via curl

# Upload the action YAML file to the _lakefs_actions/ path
curl -X POST \
  "https://lakefs.example.com/api/v1/repositories/my-repo/branches/main/objects?path=_lakefs_actions%2Fpre-commit-validation.yaml" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)" \
  -H "Content-Type: multipart/form-data" \
  -F "content=@pre-commit-validation.yaml"

Related Pages

Implements Principle

• Principle:Treeverse_LakeFS_Action_Hook_Definition

Uses Heuristic

• Heuristic:Treeverse_LakeFS_Action_Cache_Wait_Tip