Implementation:Treeverse LakeFS SetGCRules

Knowledge Sources	lakeFS lakeFS GC Docs
Domains	Storage_Management, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

The setGCRules API endpoint configures garbage collection retention rules for a lakeFS repository, defining how long committed data versions are preserved before becoming eligible for deletion.

Description

This endpoint accepts a PUT request containing a JSON body that specifies a default retention period (in days) and an optional list of per-branch retention overrides. On success, the rules are persisted in the repository's settings and take effect on the next garbage collection preparation run.

The endpoint is idempotent: calling it multiple times with the same payload produces the same result. Each call replaces the entire rule set (it is not a partial update), so callers must include all desired branch overrides in every request.

Usage

Use this endpoint when:

• Initializing GC rules for a newly created repository
• Modifying the default retention period for all branches
• Adding, updating, or removing per-branch retention overrides
• Scripting GC configuration as part of infrastructure-as-code pipelines

Code Reference

Source Location

• API specification: api/swagger.yml lines 3660-3684
• Operation ID: setGCRules
• HTTP method: PUT
• Path: /api/v1/repositories/{repository}/settings/gc_rules

Signature

# Request Body Schema: GarbageCollectionRules
GarbageCollectionRules:
  type: object
  required:
    - default_retention_days
    - branches
  properties:
    default_retention_days:
      type: integer
      description: >
        The number of days to retain committed objects by default.
        Applies to all branches without an explicit override.
    branches:
      type: array
      items:
        $ref: '#/definitions/GarbageCollectionRule'
      description: >
        Per-branch retention overrides.

GarbageCollectionRule:
  type: object
  required:
    - branch_id
    - retention_days
  properties:
    branch_id:
      type: string
      description: The branch identifier to override retention for.
    retention_days:
      type: integer
      description: >
        The number of days to retain committed objects on this branch.

Import

# No SDK import required — this is a REST API call
# Use curl, httpie, or any HTTP client
curl -X PUT http://localhost:8000/api/v1/repositories/{repository}/settings/gc_rules \
  -H "Content-Type: application/json" \
  -u "access_key:secret_key"

I/O Contract

Inputs

Parameter	Location	Type	Required	Description
repository	Path	string	Yes	The repository name
default_retention_days	Body	integer	Yes	Default retention period in days for all branches
branches	Body	array of GarbageCollectionRule	Yes	Per-branch retention overrides (may be an empty array)
branches[].branch_id	Body	string	Yes	Branch identifier for the override
branches[].retention_days	Body	integer	Yes	Retention period in days for this specific branch

Outputs

Status Code	Body	Description
204	No Content	GC rules were successfully saved
401	Error	Unauthorized: invalid or missing credentials
404	Error	Repository not found
422	Error	Validation error (e.g., negative retention days)

Usage Examples

Set Default Retention With Branch Override

# Set a 14-day default retention with a 30-day override for "main"
curl -X PUT http://localhost:8000/api/v1/repositories/my-repo/settings/gc_rules \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "default_retention_days": 14,
    "branches": [
      {"branch_id": "main", "retention_days": 30}
    ]
  }'
# Expected: HTTP 204 No Content

Set Multiple Branch Overrides

# Production gets 90 days, staging gets 21 days, everything else gets 7 days
curl -X PUT http://localhost:8000/api/v1/repositories/data-lake/settings/gc_rules \
  -H "Content-Type: application/json" \
  -u "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -d '{
    "default_retention_days": 7,
    "branches": [
      {"branch_id": "main", "retention_days": 90},
      {"branch_id": "staging", "retention_days": 21}
    ]
  }'
# Expected: HTTP 204 No Content

Python SDK Example

import lakefs_sdk
from lakefs_sdk.models import GarbageCollectionRules, GarbageCollectionRule

configuration = lakefs_sdk.Configuration(
    host="http://localhost:8000/api/v1",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api = lakefs_sdk.RetentionApi(api_client)
    rules = GarbageCollectionRules(
        default_retention_days=14,
        branches=[
            GarbageCollectionRule(branch_id="main", retention_days=30),
        ],
    )
    api.set_garbage_collection_rules("my-repo", rules)

Related Pages

Implements Principle

• Principle:Treeverse_LakeFS_Retention_Rule_Configuration

Requires Environment

• Environment:Treeverse_LakeFS_LakeFS_Server_Environment