Setting up Users

After you install Git Fusion, you must map your Git users to Perforce accounts and set permissions for them.

This chapter discusses the following topics:

How do user permissions work?

Git Fusion authenticates users through HTTP or SSH and authorizes them for pull and push transactions through Perforce 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 Perforce permissions and groups.

If you are not familiar with Perforce permissions functionality, see the Perforce System Administrator's Guide, Administering Perforce: Protections.

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:

  • Git author: A user who changes a file. Typically this is an individual developer or contributor.

  • Git committer: A user who checks a change into Git. Usually this is the same user as the Git author, but in some workflows, a Git author lacks easy network or write access to the main Git repo, so the author emails a patch or sends the change to a coworker, who then commits that change to the repo on behalf of the author.

  • Git puller: A user who runs git clone, git pull, or git fetch to download data into their own Git repo from another Git repository such as Git Fusion.

  • Git pusher: A user who runs git push to send changes from their own Git repo to a Git remote repo such as Git Fusion. The changes being pushed are often authored and committed by the same person doing the pushing, but not always; it is common for Git users to pull changes from coworkers, so the pushed changes might be authored or committed by anyone.

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

Perforce protections

Any Git user who pushes changes to a Git Fusion remote repo must have write access to the Perforce 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 Permission groups). However, there is an option to require that all pull transactions check that the puller has Perforce read permissions for the depot locations included in the repo. For more information, see Enforce Perforce read permissions on Git pull .

The git-fusion-user must have write access to all of the Perforce 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 Perforce groups to enforce what the user can push and pull. Each Git puller and pusher maps to a corresponding Perforce user, and that Perforce user must (with exceptions, noted below) be a member of a pull or push permissions group. Pushers must also have write access to the Perforce depot locations included in the repo.

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

  • Repo-specific permission groups: grant a Perforce user pull (git-fusion-repo_name-pull) or pull and push (git-fusion-repo_name-push) permissions for a specific Git Fusion repo view (which represents a specified set of files in the Perforce depot).

  • Global permission groups: grant a Perforce user pull (git-fusion-pull) or pull and push permissions (git-fusion-push) for all Git Fusion repos.

  • Default permissions p4 key: grants all Perforce users the ability to pull or push -- or prohibits users from doing either action -- by use of a p4 key, (git-fusion-permission-group-default).

    If you do not assign a user to either a repo-specific or global group, Git Fusion automatically assigns the user the permission specified by the p4 key. If you use the p4 key to remove access from all users, you can restrict users to repo-specific permissions. You can also use it to give access to all users when you have no need for repo-specific 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 Perforce 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 Perforce 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 Perforce protections table for the puller's read access to the files in the Perforce depot, unless an administrator has enabled the option to require a read-access check for all pull transactions. For more information, see Enforce Perforce 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 Perforce 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 Perforce user -- or if the Git author's Perforce user does not have write permission -- if one or more of the following criteria are met:

    • The unknown_git user exists and has write permissions.

    • The ignore-author-permissions property is set to Yes in the repo configuration file.

    • The change-owner property is set to pusher in the repo configuration file.

    For more information about unknown_git, ignore-author-permissions, and change-owner, see Enable pushes when Git authors lack Perforce 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 Perforce 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 Perforce 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 Perforce 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

What do I have to do?

To enable Git authors to use Git Fusion, you must:

Mapping Git users to Perforce accounts

In a standard Git Fusion implementation, each Git author who pushes or pulls Git Fusion repos must map to a Perforce account. By default, this mapping is made by comparing the email address of the Git author to the email address associated with the Perforce account, or by looking for the email address in a Git Fusion User Map file.

Note

Configure the Git author's email address to be matched against the Perforce user account's email address by issuing a git config command on the git client system.

To configure the email address for a single repository issue the following command from the git repository workspace directory.

git config  --local --replace-all user.email [email protected]

To configure the email address for all repositories issue the following command.

git config --global --replace-all user.email [email protected]

There are a number of options that enable alternatives to this default:

  • The author-source property in the global and repo-specific repo configuration files enables you to derive the Perforce account from the user.name field in the Git commit or the account portion (the part that precedes @) of the Git author's email address.

    For more information, see Table 2, “Global configuration file: keys and default values”.

  • Git authors who perform commits, but not pushes, do not necessarily need to map to Perforce accounts.

    You can extend the ability to author Git commits to Git users who do not have a Perforce account by enabling the unknown_git Perforce user. For more information about how unknown_git affects Git Fusion pushes, see Effect of permissions on push requests.

  • If the Git author is not the same as the user who performs the Git push, you can set Git Fusion to ignore the Git author's Perforce permissions entirely, relying instead on the Perforce permissions of the Git user who performs the push.

    Set the change-owner property in the global or repo-specific repo configuration file to pusher. For more information, see Table 2, “Global configuration file: keys and default values”.

Verify email address match

Whether you are mapping Git users to existing Perforce accounts or adding new Perforce accounts, the simplest way to map the users is to ensure that the email address associated with the Git user is identical to the email address for their Perforce account.

Use the Git Fusion User Map

In most implementations, establishing the association between your Git users and their Perforce accounts will involve no more than verifying that there is a one-to-one correspondence between the Git account email address and the Perforce account email address. In some cases, however, you may want to map multiple Git email accounts to a single Perforce user or use generic email accounts to mask Perforce user names.

For those scenarios, use the Git Fusion User Map (p4gf_usermap), a text file of tuples that enables you to do the following:

  • Map multiple Git email accounts to a single Perforce user.

    p4bob [email protected] "Bill Preston"
    p4bob [email protected] "Bill S. Preston, Esquire"
  • Mask Perforce user names to generic names.

    To mask a company’s employee list, run p4 users and edit the results to map each Perforce user name to a generic email account and name. Add unique identifiers to the email address and name to ensure that each commit maps to the correct user. Otherwise, commits are attributed only to the first user in the list.

    p4geddy [email protected]  "Company employee 1"
    p4alex  [email protected]  "Company employee 2"
    p4neil  [email protected]  "Company employee 3"

The map file is automatically created by the User and Client Initialization script (p4gf_init.py). The script creates the file in Perforce at //.git-fusion/users/p4gf_usermap. You can run this script 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.

Enable the unknown_git Perforce account

If you enable the Perforce user unknown_git, commits by Git authors who do not have a Perforce user account can be pushed to Git Fusion repos. The changelist for the Perforce submit will record the submitter as unknown_git. For more information about how Git Fusion handles Git authors without Perforce user accounts, see Effect of permissions on push requests. Note that, regardless of whether or not unknown_git exists, Git users who perform pushes must have a Perforce account.

To allow commits from Git users without a Perforce account:

  1. Run p4 user to create a Perforce account for the user unknown_git.

  2. Grant permissions to unknown_git using Git Fusion’s permission groups and Perforce’s p4 protect table.

Authenticating Git users

This guide assumes that you want to use HTTP to authenticate Git users. If you prefer SSH authentication, see Authenticating Git Users using SSH.

In HTTP authentication, a web server manages authentication for all git client requests. Instead of directly running git-http-backend, the standard Common Gateway Interface (CGI) program that implements server-side Git processes over HTTP, Git Fusion HTTP implementations run a Git Fusion script, p4gf_http_server.py, that is invoked by CGI. The script does the following:

  • Reads the Git Fusion environment to get the P4PORT and other options specified in the Git Fusion environment configuration file.

  • Reads the CGI environment variables to get the user, repo, and request.

  • Checks that the user is authenticated by the web server.

  • Checks that the user has Git Fusion authorization for the operation.

  • If the operation is a push, assigns the associated Perforce user as the pusher.

  • Proceeds with the translation of Git and Perforce commands.

  • Invokes git-http-backend to manage the rest of the request.

configure-git-fusion.sh will optionally configure HTTPS authentication for you. Please see Git Fusion release notes for requirements.

Note

HTTPS authentication on Centos 7.x or RedHat 7.x is not supported.

Note

configure-git-fusion.sh will configure HTTPS authentication with self-signed SSL certificates.

  • If verifiable certificates are available, put them

    • on Ubuntu 12.04 or 14.04 in:

      /etc/apache2/ssl/apache.crt and /etc/apache2/ssl/apache.key
    • on CentOS 6.x or RedHat 6.x in:

      /etc/httpd/ssl/apache.crt and /etc/httpd/ssl/apache.key
  • If you decide to use self-signed certificates, Git users should not attempt to verify certificates. Instruct your Git users to do one of the following:

    • Tell Git never to verify SSL certificates:

      $ git config --global http.sslVerify false
    • Tell Git not to verify SSL certification in the current shell session only:

      $ export GIT_SSL_NO_VERIFY=true

Note

If you have attempted to configure HTTPS authentication for Git Fusion before, or if you have a working HTTPS authentication, configure-git-fusion.sh will not fix or re-configure your existing setup.

Use existing HTTPS configuration with a different Perforce Service.

If you have an existing working HTTPS configuration, but would like to use it with a different Perforce Service, please follow these steps:

  • On Ubuntu 12.04 or Ubuntu 14.04:

    1. Stop the Apache web service.

      # service apache2 stop
    2. Open the git-fusion-ssl or git-fusion-ssl.conf Apache site configuration file.

      # vi /etc/apache2/sites-available/git-fusion-ssl

      Or

      # vi /etc/apache2/sites-available/git-fusion-ssl.conf
    3. Edit the AddExternalAuth line to include the full hostname, port and P4CHARSET of your Perforce service.

      AddExternalAuth p4_auth "/opt/perforce/git-fusion/libexec/p4auth.sh myperforceserver:port charset"
    4. Save your changes and exit vi.

      :wq
    5. Start the Apache web service.

      # service apache2 start
  • On CentOS 6.x or RedHat 6.x:

    1. Stop the Apache web service.

      # service httpd stop
    2. Open the git-fusion-ssl.conf Apache site configuration file.

      # vi /etc/httpd/conf.d/git-fusion-ssl.conf
    3. Edit the AddExternalAuth line to include the full hostname, port, and P4CHARSET of your Perforce service.

      AddExternalAuth p4_auth "/opt/perforce/git-fusion/libexec/p4auth.sh myperforceserver:port charset"
    4. Save your changes and exit vi.

      :wq
    5. Start the Apache web service.

      # service httpd start
  • Run configure-git-fusion.sh to re-configure Git Fusion to run against a different Perforce Service, and select no when prompted to set up HTTPS configuration.

Validating your HTTP authentication setup

Note

Before verifying HTTPS authentication make sure Git Fusion submit triggers are updated on your Perforce Server.

There are multiple ways to validate that your HTTP setup succeeded:

  • From the command line, run:

    curl -k --user perforce_user:perforce_user_password https://mygitfusionserver/@info
  • From a browser: go to https://mygitfusionserver/@info and log in as a Perforce user.

    The page displays your server information:

    Perforce - The Fast Software Configuration Management System.
    Copyright 2014 Perforce Software.  All rights reserved.
    Rev. Git Fusion/2014.2/896875 (2014/07/23).
    SHA1: 19786d97b2de1ace6e3694a6937aecf076455e89
    Git: git version 1.8.2.3
    Python: 3.3.2
    P4Python: Rev. P4PYTHON/LINUX35X86_64/2014.1/895961 (2014.1/821990 API) (2014/07/21).
    Server address: ssl:1666
  • From a machine other than the Git Fusion server, clone a repo using HTTP authentication.

    $ export GIT_SSL_NO_VERIFY=true
    $ git clone https://mygitfusionserver/repo_name

    The system prompts you to log in as a Perforce user.

Logs

The following logs can be helpful when you need to troubleshoot your HTTP configuration:

Ubuntu

  • /var/log/apache2/error.log

  • /var/log/apache2/gf-error.log

  • /var/log/syslog (default Git Fusion log)

CentOS and Red Hat

  • /var/log/httpd/error_log

  • /var/log/httpd/gf-error.log

  • /var/log/messages (default Git Fusion log)

  • /var/log/audit/audit.log (for SELinux denials)

Authorizing Git users

To authorize Git users to perform transactions with Git Fusion, you use the p4 protect table, Git Fusion repo-specific and global permission groups, and the default group p4 key.

For more information, see How do user permissions work?

To set up authorization:

Assign Perforce permissions to Git Fusion users

Run p4 protect to verify or add write permissions for all Perforce users associated with the Git users who will push changes to the Git Fusion repos.

To successfully perform a push, the Git pusher's Perforce user must have write permissions to the affected files. The Git author must also have write permissions, unless you use the unknown_git user, the ignore_author_permissions property, or the change-owner property to circumvent that requirement (for more information, see Enable pushes when Git authors lack Perforce permissions).

Note

As of the first 2014.1 patch, you can also configure a branch to be read-only, regardless of a user's Perforce permissions. See Repo configuration file: key definitions and samples.

Git Fusion does not check the p4 protect table for pull transactions, unless you enable the global p4gf_config property to require a read-access check for all pull transactions (see Enforce Perforce read permissions on Git pull ). If you do not enable this option, you do not need to assign permissions in the p4 protect table for users who are only performing pulls.

Create the permission groups and group p4 key

  1. Run the User and Client Initialization script (p4gf_init.py).

    The global groups and the default permission p4 key are automatically generated by the User and Client Initialization script (p4gf_init.py). By default, the group owner is set as git-fusion-user. Do not change the owner.

    You can run this script any time after Git Fusion has been initialized in 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 this Git Fusion server will invoke them both automatically.

    Important

    The default setting for the git-fusion-permission-group-default p4 key is push. Change this setting to none or pull, using p4 key, if you want to prevent authenticated users who are not members of a permission group from having push access to all Git Fusion repos by default. Note that 0 (zero) has the same effect as setting it to push.

    If you set the p4 key to none, you must run p4gf_init_repo.py.

  2. Run the Repo Initialization script (p4gf_init_repo.py) for each repo.

    p4gf_init_repo.py repo_name

    This script creates the Git Fusion push and pull permission groups for each repo you run it for. By default, the group owner is set as git-fusion-user. Do not change the owner.

    You can run this script any time after Git Fusion has been initialized in 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 this Git Fusion server will invoke them both automatically.

    For more information about the p4gf_init_repo.py script and options, see the Script Command Reference and Setting up Repos.

Populate the permission groups and set the group default p4 key

The way you use the Perforce permission groups and the group default p4 key depends on your needs.

Important

By default, pull requests only check the p4 protects table to confirm that the git-fusion-user has access to the Perforce depot location; the Git puller's read access to the Perforce location is not checked unless you have enabled the global p4gf_config property to require a read-access check for all pull transactions (see Enforce Perforce read permissions on Git pull ). Therefore, if you have not enabled this option, you must do one of the following to prevent authenticated Git Fusion users from pulling from a particular Perforce depot location, :

  • Add all Git Fusion users to repo-specific pull and push permission groups and set the git-fusion-permission-group-default p4 key to none.

  • Use p4 protects to deny the git-fusion-user (and therefore all Git Fusion users) access to that depot location.

The following are some options:

  • Restrict access strictly by repo.

    1. Enable users to push by adding them to the git-fusion-repo_name-push group for each repo they need to push to. Membership in this group also grants pull permission. Ensure that these group members also have write access to the Perforce depot locations associated with the repo being pushed.

    2. Enable users to pull by adding them to each git-fusion-repo_name-pull group they need to pull from.

    3. To prevent the global pull and push groups (git-fusion-pull and git-fusion-push) from granting access to users who are not in a repo-specific group, keep these groups empty.

    4. To prevent the git-fusion-permission-group-default p4 key from giving access to users who are not in a repo-specific group, set it to none.

  • Provide pull access to all repos, restricting push access.

    1. Add users to the git-fusion-repo_name-push group for each repo they need to push to. Ensure that these group members also have write access to the Perforce depot locations associated with the repo being pushed.

    2. Add all users to the global git-fusion-pull group or set the git-fusion-permission-group-default p4 key to pull.

  • Open push access to all Git Fusion repos for all authenticated users.

    Add all users to the global git-fusion-push group or set the git-fusion-permission-group-default p4 key to push. If you want to enable all members to pushes to all repos, ensure that these group members also have write access to the Perforce depot locations associated with all Git Fusion repos.

Git Fusion creates global groups git-fusion-pull and git-fusion-push as part of its configuration script, configure-git-fusion.sh. It creates repo groups git-fusion-repo_name-pull and git-fusion-repo_name-push during the first push or pull for that repo.

For more information about setting group permissions and p4 keys in Perforce, see the Perforce System Administrator’s Guide, Administering Perforce: Protections.

Enable pushes when Git authors lack Perforce permissions

The Git pusher is not always the same Git user as the author and committer of the changes being pushed. While the pusher must always be a licensed Perforce user with write permission for the depot locations being pushed to, you may not need all of your Git authors to be mapped to a licensed Perforce user. Git Fusion provides the following tools to enable pushes when the Git author is not a Perforce user:

  • unknown_git user

    Create this Perforce user and give it Perforce write permission for the depot locations associated with all repos for which you want to allow pushes when the Git author has no Perforce account. If your git-fusion-permission-group-default p4 key is set to pull or none, add unknown_git to the global git-fusion-push group or the relevant repo-specific push groups.

    When a Git push request is made, Git Fusion checks to see if the Git author has a mapped Perforce account. If not, and unknown_git has write permissions, the push goes through. If the author exists, the author is still recorded as the submitter in the Perforce changelist description. If the author does not exist, the submitter is recorded as unknown_git.

  • ignore-author-permissions property

    Set this configuration property to Yes in a repo-specific configuration file to enable pushes to go through even when the Git author does not have write (push) permissions for the depot locations associated with the repo.

  • change-owner property

    Set this configuration property to pusher to make the changelist owner (submitter) the Git pusher rather than the Git author (which is the default). Regardless of which user is set as the changelist submitter, the full information from the Git commit is logged in the changelist description field, including information about the Git committer, Git author, and Git pusher. You can set this configuration property in the global configuration file or a repo-specific configuration file.

For more information about repo configuration files, see Setting up Repos

Enforce Perforce read permissions on Git pull

By default, Git Fusion checks Perforce permissions only for Git push transactions, relying on user authentication to the Git Fusion server and membership in git-fusion-pull permission groups to control Git pull (read) access to Git Fusion repos. However, if you want to enforce the permissions that you have set up in the Perforce protects table on all Git pull transactions as well, you can do so by setting the read-permission-check property in the global p4gf_config file. See Global configuration file: keys and default values