The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Git-Hooks-2.5.1
River stage one • 5 direct dependents • 5 total dependents
12 ++
/ Git::Hooks::CheckAcls

NAME

Git::Hooks::CheckAcls - Git::Hooks plugin for branch/tag access control

VERSION

version 2.5.1

SYNOPSIS

As a Git::Hooks plugin you don't use this Perl module directly. Instead, you may configure it in a Git configuration file like this:

  [githooks]
    plugin = CheckAcls
    admin = joe molly

  [githooks "checkacls"]
    acl = ^.      CRUD ^refs/heads/{USER}/
    acl = ^.      U    ^refs/heads/

This allows users joe and molly do anything. Every other user can create, rewind, update, and delete branches prefixed with their own usernames, but they can only update other branches.

DESCRIPTION

This Git::Hooks plugin hooks itself to the hooks below to guarantee that only allowed users can push commits and tags to specific branches.

  • update

    This hook is invoked multiple times in the remote repository during git push, once per branch being updated, checking if the user performing the push can update the branch in question.

  • pre-receive

    This hook is invoked once in the remote repository during git push, checking if the user performing the push can update every affected branch.

  • ref-update

    This hook is invoked when a push request is received by Gerrit Code Review, to check if the user performing the push can update the branch in question.

To enable it you should add it to the githooks.plugin configuration option:

    git config --add githooks.plugin CheckAcls

NAME

Git::Hooks::CheckAcls - Git::Hooks plugin for branch/tag access control

CONFIGURATION

The plugin is configured by the following git options.

githooks.checkacls.acl ACL

The authorization specification for a repository is defined by the set of ACLs defined by this option. Each ACL specify 'who' has 'what' kind of access to which refs, by means of a string with three components separated by spaces:

    who what refs

By default, nobody has access to anything, except the users specified by the githooks.admin configuration option. During an update, all the ACLs are processed in the order defined by the git config --list command. The first ACL matching the authenticated username and the affected reference name (usually a branch) defines what operations are allowed. If no ACL matches username and reference name, then the operation is denied.

The 'who' component specifies to which users this ACL gives access. It can be specified as a username, a groupname, or a regex, like the githooks.admin configuration option.

The 'what' component specifies what kind of access to allow. It's specified as a string of one or more of the following opcodes:

  • C - Create a new ref.

  • R - Rewind/Rebase an existing ref. (With commit loss.)

  • U - Update an existing ref. (A fast-forward with no commit loss.)

  • D - Delete an existing ref.

You may specify that the user has no access whatsoever to the references by using a single hyphen (-) as the what component.

The 'refs' component specifies which refs this ACL applies to. It can be specified in one of these formats:

  • ^REGEXP

    A regular expression anchored at the beginning of the reference name. For example, "^refs/heads", meaning every branch.

  • !REGEXP

    A negated regular expression. For example, "!^refs/heads/master", meaning everything but the master branch.

  • STRING

    The complete name of a reference. For example, "refs/heads/master".

The ACL specification can embed strings in the format {VAR}. These strings are substituted by the corresponding environment's variable VAR value. This interpolation occurs before the components are split and processed.

This is useful, for instance, if you want developers to be restricted in what they can do to official branches but to have complete control with their own branch namespace.

    git config githooks.CheckAcls.acl '^. CRUD ^refs/heads/{USER}/'
    git config githooks.CheckAcls.acl '^. U    ^refs/heads'

In this example, every user (^.) has complete control (CRUD) to the branches below "refs/heads/{USER}". Supposing the environment variable USER contains the user's login name during a "pre-receive" hook. For all other branches (^refs/heads) the users have only update (U) rights.

REFERENCES

  • update-paranoid

    This script is heavily inspired (and, in some places, derived) from the example hook which comes with the Git distribution.

AUTHOR

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by CPqD <www.cpqd.com.br>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.