github.com/treeverse/lakefs@v1.24.1-0.20240520134607-95648127bfb0/design/accepted/protected-branches.md (about)

     1  # Protected Branches
     2  
     3  ## Requirements
     4  
     5  1. As a lakeFS user, I should be able to mark branches as "protected" - from the UI, CLI and API.
     6  1. Writes and commits on protected branches will be blocked.
     7  1. Forbidden actions to protected branches should fail with a meaningful error message.
     8  1. The implementation should be flexible to adding more constraint types in the future (example: require PR before merging).
     9  
    10  ## Where to save the model
    11  
    12  ### Suggestion 1 (@johnnyaug)
    13  
    14  Save protection rules as a JSON object under the repository's __lakefs_. This is similar to what we do with retention rules.
    15  
    16  Pros:
    17  - rules can be patterns and not just concrete branches, similar to GitHub's protected branches.
    18  - native to the storage
    19  - flexible: structure can easily change to accommodate for more complex constraints. 
    20  
    21  Cons:
    22  - UI will probably be a multiline textbox where you can edit the json, otherwise consistency problems.
    23  - CLI will also need to get the full JSON, or we need to do some locking on the server-side to add/remove protection rules.
    24  
    25  ### Suggestion 2 (@ariels)
    26  
    27  Branch protection rules are part of the repository data, saved under a dedicated lakeFS directory, similar to GitHub's (and our) Actions.
    28  
    29  Pros:
    30  - Reuse the Hooks mechanism for enforcement.
    31  - Use lakeFS IAM to give permissions to edit protection rules.
    32  
    33  Cons:
    34  - As a repository owner, I need to manage rules in multiple branches. For example, if I want to add rules to existing branches, I need to merge these rules to all of my developer's branches.
    35  - Can currently only be used to block commits, and not the staging area.
    36   
    37  Pro/con:
    38  - Changing protection rules is a commit visible in the log
    39  
    40  ### Decision
    41  
    42  After a meeting discussing the matter, we decided to go with suggestion #1, but to add a repository-level settings feature to be used in order to store the branch protection rules. See the [issue](https://github.com/treeverse/lakeFS/issues/2406).
    43  
    44  ## Implementation - Suggestion 1
    45  
    46  ### Example Branch Protection JSON
    47  
    48  ```json
    49  [
    50  	{
    51  		"branch_name_pattern": "main",
    52  		"blocked_actions": ["staging_write", "commit"]
    53  	},
    54  	{
    55  		"branch_name_pattern": "stable/*",
    56  		"blocked_actions": ["staging_write", "commit"]
    57  	}
    58  ]
    59  ```
    60  
    61  When a branch matches a protection rule, the operations described in the rule's `blocked_actions` will be blocked. 
    62  Blocked actions can be:
    63  1. `staging_write`: any write operation on the staging area, including: upload, delete, revert changes.
    64  2. `commit`: a simple commit, not including merges and reverts.
    65  
    66  For now, we will always add both blocked actions for all rules. In the future we will allow more flexibility.
    67  
    68  ### Runtime
    69  
    70  The enforcement of the protection depends on the constraint type.
    71  In the future we may want to add an option to force these operations.
    72  
    73  #### Constraint type: block commits
    74  
    75  * When performing a commit, the protection rules of the repository will be fetched from the storage.
    76  * Right before executing the pre-commit hooks, check whether the branch name matches any of the protection rules.
    77  * If so, the commit will fail with a dedicated error type.
    78  
    79  #### Constraint type: block staging area
    80  
    81  * In Graveler, before every Staging Manager write operation (Set, Drop, DropKey) - fetch the rules.
    82  * If the branch name matches a rule, fail the operation with a dedicated error type.