How do user permissions work?

Git Fusion authenticates users through HTTP or SSH and authorizes them for pull and push transactions through Helix Core group membership and permissions.

Authentication

Git Fusion uses HTTP or SSH to authenticate Git client requests (such as git clone, git pull, and git push). In a standard Git implementation, each Git user connects to a remote repo by establishing an individual account on the server that hosts the repo. In Git Fusion, all of your organization’s Git users gain access through a Git Fusion service user UNIX account (git, in the default OVA installation) on the Git Fusion server, where either a web server or SSH daemon performs the authentication and invokes a python script that redirects the request to Git Fusion.

Authorization

While authentication to the Git Fusion server is handled by HTTP or SSH, access to Git Fusion repos is handled by Helix Core permissions and groups.

If you are not familiar with Perforce permissions functionality, see Helix Versioning Engine Administrator Guide: Fundamentals.

Git Fusion users

When we discuss Git Fusion permissions, it is helpful to understand the following Git roles -- and to understand that a single Git user can occupy more than one of these roles in any given Git transaction:

It is also important to understand that, while Git Fusion maps Git users to Helix Core users for authorization, Git Fusion connects to Helix Core as a single user, git-fusion-user, which functions as P4USER for all Helix Core operations.

Helix Core protections

Any Git user who pushes changes to a Git Fusion remote repo must have write access to the Helix Core depot locations that comprise the repo. By default, Git pull transactions do not require read access. Permission to pull from Git Fusion remote repos is handled instead by membership in a Git Fusion pull group (see How do user permissions work?). However, there is an option to require that all pull transactions check that the puller has Helix Core read permissions for the depot locations included in the repo. For more information, see Enforce read permissions on Git pull.

The git-fusion-user must have write access to all of the Helix Core depot locations that include Git Fusion repo content, as well as the //.git-fusion depot, where Git Fusion metadata is stored.

Permission groups

Git Fusion uses Helix Core groups to enforce what the user can push and pull. Each Git puller and pusher maps to a corresponding Helix Core user, and that Helix Core user must (with exceptions, noted below) be a member of a pull or push permissions group. Pushers must also have write access to the Helix Core depot locations included in the repo.

Git Fusion provides three mechanisms for determining pull and push permissions:

Pull groups enable git clone, git fetch, and git pull. Push groups add git push.

When determining a user’s pull and push permissions, Git Fusion iterates through these mechanisms, from the repo-specific groups to the global groups to the p4 key, continuing until it finds and returns the first matching permission.

The global groups and the default permissions p4 key are automatically generated by the User and Client Initialization script (p4gf_init.py). The repo-specific permission groups are automatically generated by the Repo Initialization script (p4gf_init_repo.py). You can run these scripts any time after Git Fusion has been initialized into your Perforce service with the Super User Initialization script (p4gf_super_init.py). If p4gf_init.py has not been run, p4gf_init_repo.py will invoke it automatically. If neither has been run, the first push or clone against the Git Fusion server invokes them both automatically.

Permissions for git-fusion-user

The Super User Initialization script (p4gf_super_init.py) automatically creates the git-fusion-user account, which performs all transactions with the Perforce service. The script grants admin privileges to this account and inserts the git-fusion-user in the bottom row of the protections table. Consequently, Git users are able to read (pull) and write (push) based on the permissions set for their corresponding Helix Core user and also the permissions assigned to the git-fusion-user.

Note that the git-fusion-user must be the owner of all global and repo-specific permission groups.

Permission validation logic

Git Fusion and the Perforce service validate pull and push requests using the following logic:

  1. Prior to processing a pull or push request, the Perforce service verifies that the git-fusion-user has the appropriate permissions for that action. If not, the Perforce service rejects the request.

  2. Git Fusion verifies that the Git user maps to a Helix Core user with appropriate pull or push permission for that Git Fusion repo.

    Git Fusion iterates through the repo-specific permission groups, the global permission groups, and the default permission p4 key until it finds and returns the first matching permission.

  3. If the request is a pull (git clone, git fetch, git pull), permission group membership or the default permission p4 key value determines access to the repo; Git Fusion does not check the Helix Core protections table for the puller's read access to the files in the Helix Core depot, unless an administrator has enabled the option to require a read-access check for all pull transactions. For more information, see Enforce read permissions on Git pull.

  4. If the request is git push, the Git Fusion server verifies that both the Git author and the Git pusher have Helix Core write permissions set for the files in the depot. If either user does not, the Git Fusion server rejects the push.

    The requirement that the Git author have write permission is subject to some exceptions. The push can succeed even if the Git author has no associated Helix Core user -- or if the Git author's Helix Core user does not have write permission -- if one or more of the following criteria are met:

    For more information about unknown_git, ignore-author-permissions, and change-owner, see Enable pushes when Git authors lack permissions

Effect of permissions on push requests

The following table shows how Git Fusion handles push requests, depending on permissions set for the Git pusher, the Git author, and the unknown_git user, along with the ignore-author-permissions property for the repo.

Note that this table does not display the effect of setting the change-owner property to pusher. This is because that setting makes the other settings irrelevant: as long as the Git pusher has write access to the correct locations in the Helix Core depot, the change will be submitted successfully, with the Git pusher as changelist owner and the author's, committer's, and pusher's names appearing in the changelist description.

A dash (-) indicates that the column has no significance in a row where it appears; the value could be Yes or No.

Table 1. Effect of permissions on push requests

Git pusher has write access

P4USER unknown_ git exists

P4USER unknown_ git has write access

Git author is P4USER

Git author has write access

ignore-author-permissions flag is set

Result

Yes

-

-

Yes

Yes

-

Changelists appear as submitted by Git author's Helix Core user ID, and the author's, committer's, and pusher's names appear in the changelist.

Yes

-

-

Yes

No

Yes

Changelists appear as submitted by Git author's Helix Core user ID, and the author's, committer's, and pusher's names appear in the changelist.

Yes

Yes

Yes

No

-

-

Changelists appear as submitted by unknown_git, and the author's, committer's, and pusher's names appear in the changelist.

Yes

Yes

No

No

-

Yes

Changelists appear as submitted by unknown_git, and the author's, committer's, and pusher's names appear in the changelist.

Yes

-

-

Yes

No

No

Git Fusion prohibits the push and displays the following error message:

remote: import failed: user Git Author's P4USER not authorized to submit file(s) in git commit

Yes

Yes

No

No

-

No

Git Fusion prohibits the push and displays the following error message:

remote: import failed: user unknown_git not authorized to submit file(s) in git commit

Yes

No

-

No

-

-

Git Fusion prohibits the push and displays the following error message:

remote: import failed: user Git Author's email not permitted to commit

No

-

-

-

-

-

Git Fusion prohibits the push and displays the following error message: remote: import failed: user Pusher's P4USER not authorized to submit file(s) in git commit