Principle:Treeverse LakeFS Action Script Upload
| Knowledge Sources | |
|---|---|
| Domains | Data_Quality, Automation |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Deploying action hook configurations to a repository's reserved action path activates automated validation gates for subsequent operations on that branch.
Description
Action hooks in lakeFS are stored as regular objects within the repository under the reserved _lakefs_actions/ path prefix. This design means that hook configurations are not managed through a separate administration interface -- they are uploaded, versioned, and managed using the same object storage API used for data.
When a YAML file is uploaded to a path beginning with _lakefs_actions/, lakeFS automatically recognizes it as an action definition. The hooks defined within that file become active for subsequent operations on the branch where the file exists.
Key characteristics of this approach:
- Version-controlled hooks -- Hook definitions are committed alongside data, creating a complete audit trail of what validation rules were active at any point in time
- Branch-scoped activation -- Uploading a hook to a feature branch only activates it on that branch. The hook must be merged to affect the target branch.
- Atomic deployment -- Multiple action files can be uploaded and committed together, ensuring all hooks activate simultaneously
- Testable configurations -- New hooks can be tested on feature branches before being promoted to production branches
The upload mechanism uses the standard uploadObject API endpoint. The only distinction from regular data uploads is the path prefix -- the _lakefs_actions/ prefix signals to lakeFS that the object defines hook behavior.
Usage
Use action script upload when you need to:
- Deploy new validation rules -- Upload YAML action files to activate pre-commit or pre-merge quality gates
- Update existing hooks -- Overwrite existing action files to modify hook behavior
- Remove hooks -- Delete action files from the
_lakefs_actions/path to deactivate hooks - Test hook configurations -- Upload hooks to a feature branch and verify they work before merging
- Migrate hook versions -- Update hook definitions as part of a coordinated branch-and-merge workflow
Theoretical Basis
The principle of storing hook configurations as repository objects follows the infrastructure-as-code paradigm:
Configuration as data: Rather than storing hook definitions in an external database or configuration service, lakeFS treats them as first-class repository content. This eliminates the configuration drift problem where the active hooks diverge from what is documented or expected.
Path-based convention: The _lakefs_actions/ prefix uses a convention over configuration approach. Any file placed under this well-known path is automatically interpreted as an action definition. The leading underscore signals that this is a system path not intended to hold user data.
Unified versioning model: By using the same upload API for both data and hooks, lakeFS avoids creating a separate management plane for automation. This simplifies the mental model -- everything in the repository follows the same branching, committing, and merging lifecycle.
Activation by presence: Hooks are active when their configuration files are present on a branch and inactive when absent. This creates a simple, predictable activation model that does not require explicit enable/disable operations.