Implementation:Treeverse LakeFS Commit With Hooks

Knowledge Sources	lakeFS lakeFS API Reference
Domains	Data_Quality, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for creating commits with pre-commit hook validation gates provided by the lakeFS REST API.

Description

This implementation documents the commit API endpoint in the context of pre-commit and post-commit hook execution. When action hooks are configured under _lakefs_actions/ on the target branch, the commit operation triggers hook evaluation as part of its execution.

The key behavioral difference from a hookless commit is the HTTP 412 Precondition Failed response: when any pre-commit hook fails (webhook returns non-200, Lua script errors), the commit is rejected with this status code. The staged changes remain on the branch and can be committed after the validation issue is resolved.

Post-commit hooks fire asynchronously after the commit succeeds. Their execution status can be queried via the Actions API (listRepositoryRuns).

Usage

Use this API when you need to:

Commit data changes that must pass pre-commit validation hooks
Create auditable commit records with metadata for compliance tracking
Trigger post-commit notifications and downstream pipeline execution
Understand why a commit was rejected by inspecting hook failure responses

Code Reference

Source Location

Repository: lakeFS
File: api/swagger.yml (lines 4252-4292)
Hook integration: esti/hooks.go (lines 49, 156)

Signature

# API Endpoint
POST /api/v1/repositories/{repository}/branches/{branch}/commits

# Operation ID
operationId: commit

# Content Type
Content-Type: application/json

# Path Parameters
repository: string              # Repository name
branch: string                  # Branch to commit on

# Request Body: CommitCreation
CommitCreation:
  message: string               # Commit message (required)
  metadata:                     # Optional key-value metadata
    key1: value1
    key2: value2
  date: integer                 # Optional epoch timestamp override
  allow_empty: boolean          # Optional, allow commits with no changes

# Response 201: Commit
Commit:
  id: string                    # Commit SHA reference
  parents: [string]             # Parent commit IDs
  committer: string             # User who created the commit
  message: string               # Commit message
  creation_date: integer        # Epoch timestamp
  meta_range_id: string         # Meta-range identifier
  metadata:                     # Commit metadata
    key: value

# Response 412: Precondition Failed (hook rejection)
Error:
  message: string               # Hook failure description

Import

import requests
# or
import lakefs_sdk
from lakefs_sdk.api import commits_api

I/O Contract

Inputs

Name	Type	Required	Description
`repository`	string (path)	Yes	Name of the repository
`branch`	string (path)	Yes	Branch to commit to
`message`	string (body)	Yes	Commit message describing the changes
`metadata`	map[string]string (body)	No	Key-value pairs attached to the commit
`date`	integer (body)	No	Override commit timestamp (Unix epoch seconds)
`allow_empty`	boolean (body)	No	Allow creating a commit with no changes (default: false)

Outputs

Name	Type	Description
`Commit` (HTTP 201)	object	Successful commit with ID, parents, message, metadata, and creation date
HTTP 400	error	Bad request (e.g., empty message)
HTTP 401	error	Unauthorized (missing or invalid credentials)
HTTP 404	error	Repository or branch not found
HTTP 409	error	Conflict (concurrent commit or no changes without `allow_empty`)
HTTP 412	error	Precondition Failed -- a pre-commit hook rejected the commit

Usage Examples

Commit With Pre-Commit Hook Validation

# Commit data changes -- pre-commit hooks will execute automatically
curl -X POST \
  "https://lakefs.example.com/api/v1/repositories/my-repo/branches/feature-ingest/commits" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Add daily sales data for 2026-02-07",
    "metadata": {
      "source": "sales-etl-pipeline",
      "ticket": "DATA-1234"
    }
  }'

# On success (HTTP 201): commit created, post-commit hooks fire asynchronously
# On hook failure (HTTP 412): commit rejected, response contains failure details

Handling Hook Rejection in Python

import lakefs_sdk
from lakefs_sdk.api import commits_api
from lakefs_sdk.model.commit_creation import CommitCreation
from lakefs_sdk.exceptions import ApiException

configuration = lakefs_sdk.Configuration(
    host="https://lakefs.example.com/api/v1",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    commits = commits_api.CommitsApi(api_client)

    try:
        result = commits.commit(
            repository="my-repo",
            branch="feature-ingest",
            commit_creation=CommitCreation(
                message="Add daily sales data for 2026-02-07",
                metadata={
                    "source": "sales-etl-pipeline",
                    "ticket": "DATA-1234"
                }
            )
        )
        print(f"Commit successful: {result.id}")
    except ApiException as e:
        if e.status == 412:
            print(f"Pre-commit hook rejected the commit: {e.body}")
        else:
            raise

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment