GitCentric User s Help

Transcription

1 AccuRev GitCentric User s Help Version Revised 10/7/13

2 Copyright and Trademarks Copyright AccuRev, Inc ALL RIGHTS RESERVED This product incorporates technology that may be covered by one or more of the following patents: U.S. Patent Numbers: 7,437,722; 7,614,038. AccuRev and TimeSafe are registered trademarks of AccuRev, Inc. AccuBridge, AccuReplica, AccuSync, AccuWork, Kando, GitCentric, and StreamBrowser are trademarks of AccuRev, Inc. All other trade names, trademarks, and service marks used in this document are the property of their respective owners.

3 Table of Contents Preface... vii Audience...vii Using This Book...vii Typographical Conventions... viii Contacting Technical Support... viii License Issues... viii Other Support Issues... viii Other Resources...ix 1. Concepts and Overview... 1 What is AccuRev GitCentric?...1 Where to go for More Information...1 A Note About Terminology...2 Basic Architecture...3 GitCentric Users...4 GitCentric Administrators and Mapping Branches to Streams...4 Basic Rules...5 Mapped Behavior...5 Best Practices When Planning Your Installation...5 Keeping Git Merges and AccuRev Promotes in Sync...6 Best Practice for Keeping Merges and Promotes in Sync...7 Scenarios for Mapping Multiple Repositories to a Single Stream...7 Multiple Repos and Multiple Servers...8 AccuRev Replica Server Restriction...9 Configuring for Security...9 Configuring Multiple Git Repos with AccuRev and EACLs...10 Getting Started How to Procedures for All Users...13 Get Started...13 Define and Display a Site Header or Footer for Gerrit Code Review...17 Configure the Clone for Code Review (Optional)...18 Configure the Clone for Direct Push...18 Troubleshoot Git Clone Issues...18 Configure GitCentric...21 Remove a Branch...23 Remove a Repository...23 A Note About AccuRev Depots...23 Import a Snapshot of the Latest Heads into AccuRev...24 Import Complete Git History into AccuRev [BETA only]...25 GitCentric User s Help iii

4 General Procedure for Setting ACLs...30 Configuring ACLs for Code Review...32 Configuring GitCentric ACLs for Direct Push...34 Specify the Server and Service Account...34 Map the Branch to the Stream...36 Registering an AccuRev Server...39 Configuring the AccuRev Server...40 Configure Multiple AccuRev Servers...41 To View and Access Groups...42 Add a Group...42 Add a Member to a Group...42 AccuRev Groups...43 Allowing Self-Reviews...44 Disabling Code Review...44 Overview...45 Registering the GitCentric Bridge SSH Key with Gerrit...45 Modifying the replication.config File...45 AccuRev to Git...47 Git to AccuRev My Account Menu Options...49 Profile...49 Watched Repositories (Projects)...50 Contact Information...51 Public Keys...51 AccuRev Servers...51 HTTP Password...51 People Code Review Overview of Gerrit Code Review...53 Differences from Standalone Gerrit Code Review...53 Code Review for Users of Differing Backgrounds...54 Gerrit Code Review and AccuRev Mappings...54 Troubleshooting Administration Repositories...58 To Create a New Repository...58 To Configure an Existing Repository...58 Support for Hooks...63 People...64 AccuRev Servers...65 A Note about the CLI Path Setting...65 GitCentric User s Help iv

5 A. The kandomaintain Utility Using kandomaintain...67 Backup and Restore...67 kandomaintain Command Reference...67 Commands...67 Options...69 GitCentric Bridge Configuration Settings...71 Examples...71 B. Backup and Restore The Backup Process...73 What are the GitCentric Databases?...73 Best Practices...73 Backing Up GitCentric...74 What Gets Backed Up?...74 Where the Backup File Gets Created...74 Before You Begin...74 How to Back Up GitCentric...74 Restoring GitCentric...75 Restore Scenarios...75 Before You Begin...76 How to Restore GitCentric...76 C. Command-Line Reference Basic Syntax...79 Spaces and Quoting...79 CLI Example...85 D. GitCentric Glossary Index GitCentric User s Help v

6 GitCentric User s Help vi

7 Preface This document serves as both the on-line help and the User s Guide for AccuRev GitCentric. This documentation covers both GitCentric end user and administrator audiences. GitCentric provides most functionality through a Web UI, but also provides three administrative CLI commands. Audience This document is intended for GitCentric end users and administrators. End users are assumed to be familiar with Git source control, and possibly Gerrit Code Review. Administrators are assumed to be familiar with these topics and also with Linux operating systems, as well as AccuRev and AccuWork concepts. Using This Book This book assumes you are familiar with your operating system(s) and their commands, as well as with AccuRev, AccuWork, and Git. The following table summarizes the chapters and appendixes in this book. Chapter Description Audience Chapter 1 Concepts and Overview Chapter 2 How to... Chapter 3 My Account Chapter 4 Code Review Chapter 5 Administration Appendix A The kandomaintain Utility Appendix B Backup and Restore Introduces basic GitCentric concepts and architecture. Provides a series of common tasks that you perform to configure and use GitCentric. Provides the ability to register yourself with GitCentric, and to set your preferences and contact information. Gives you access to optional third-party Gerrit Code Review functionality. Summarizes the features for configuring and maintaining repositories, groups, and AccuRev servers, including security configuration. Provides links to conceptual and task-based sections of this document. Describes the command line kandomaintain utility for upgrading and administering the GitCentric database. Summarizes procedures and best practices for backing up your GitCentric-related repositories and database files. End users and administrators End users and administrators End users and administrators End users and administrators Administrators Administrators Administrators GitCentric User s Help vii

8 Chapter Description Audience Appendix C Command-Line Reference Appendix D GitCentric Glossary Summarizes the syntax and usage of the GitCentric administration commands, typically used for scripting administrative functions. Note: Although these commands are generally considered administrator commands, any registered user may use the ls-repo command to view the repos to which they have access. A list of GitCentric-related terms and their definitions. Typographical Conventions This book uses the following typographical conventions: Administrators End users and administrators Convention blue sans-serif bold light italic blue italic Used for sample code or output. Description Used for command names, and button names in the GitCentric user interface Used for emphasis, book titles, and for first use of important terms Identifies a hyperlink (to a page or Web URL, for example) Contacting Technical Support AccuRev offers a variety of options to meet your technical support needs. For complete information about AccuRev technical support services, visit our Web site: License Issues If you are having trouble with a license for your AccuRev product, visit the License Self Help page first to see if there is a solution for your problem: Other Support Issues To obtain technical support for an AccuRev product: Go to Or write AccuRev technical support at support@accurev.com When you contact AccuRev technical support, please include the following information: The AccuRev product and version (for example, AccuRev 5.4.1, GitCentric ) The operating system viii GitCentric User s Help

9 A brief description of the problem you are experiencing. Be sure to include which AccuRev interface you were using (Web user interface, Java GUI, or CLI), any error messages you received, what you were doing when the error occurred, whether the problem is reproducible, and so on. A description of any attempts you have made to resolve the issue, including using the resources described in Other Resources. A simple assessment of how the issue affects your organization. Other Resources In addition to contacting AccuRev technical support, consider taking advantage of the following resources: AccuRev Known Problems and Solutions -- The AccuRev Known Problems and Solutions page describes known problems in released versions of AccuRev products. The Troubleshooting section of the GitCentric Installation and Release Notes. AccuRev User Forum -- The AccuRev User Forum is a valuable resource. In addition to access to AccuRev s international user community, the User Forum is the place to go for resources like: The AccuRev knowledge base The AccuRev FAQ Register as a User Forum member today. AccuRev documentation -- This page provides access to AccuRev product documentation for all current and previous releases of most AccuRev products. GitCentric User s Help ix

10 x GitCentric User s Help

11 1. Concepts and Overview This chapter provides an introduction to the concepts behind AccuRev GitCentric. What is AccuRev GitCentric? AccuRev GitCentric is a bridge between two worlds: the open source Git revision control system the Enterprise-capable AccuRev source control management (SCM) system Git is popular with many developers for its simplicity and speed. However, professional enterprises need more control and scalability for their large investment in intellectual property. Many developers prefer AccuRev s interface; release engineers require AccuRev s stream architecture for capturing the exact revisions needed for a build environment, and managers require AccuRev s TimeSafe auditablility and its ACL-based security. How does an organization meet these differing requirements and preferences? AccuRev GitCentric provides enterprises with the solution: developers who embrace Git can continue using Git the same way they do today, while other development groups, release and test engineers, and managers who require AccuRev s power, functionality, and security can work together via the AccuRev GitCentric interface. GitCentric also incorporates the open source Gerrit Code Review package for optional code review functionality. In the most basic terms, Git repository branches are mapped to AccuRev streams, so that the two stay in sync. Changes to the Git repository get transmitted to the AccuRev depot, and changes in the AccuRev depot get transmitted to the Git repository. Updates happen automatically. Git users do not need change their work practices for the AccuRev environment, since GitCentric is transparent to them. GitCentric functionality applies to two audiences: Regular users can register themselves, maintain their preferences, and (if implemented at their site) access the optional code review functionality. Administrators can configure and maintain repositories, their security, and their branch mappings to AccuRev streams. Where to go for More Information When using GitCentric, the documentation you need depends on what component you are using. For GitCentric installation, see the AccuRev GitCentric Installation and Release Notes. GitCentric User s Help 1

12 For GitCentric administration and use, you re already here: the AccuRev GitCentric User s Help (available in both PDF and HTML) from the GitCentric web interface: For help with Gerrit Code Review, see the Gerrit Code Review documentation here: For Git documentation, you can use git help from the command line. You can also use a search engine to locate several good tutorials and discussions available on the web. For AccuRev documentation, access the complete documentation set in HTML and PDF from the Help Contents & Manuals menu in the AccuRev Java GUI: The AccuRev Installation and Release Notes are available from the documentation download page on the AccuRev web site: A Note About Terminology Because GitCentric spans the environments of AccuRev, Git, and Gerrit Code Review, you may encounter some conflicts or overlaps in terminology. For example, Gerrit Code Review often uses the term project to refer to a repository. AccuRev uses the terms repository or repo when referring to a repository, and reserves the term project for referring to specific Gerrit functionality, or when referring to some kind of planned or defined undertaking. See Appendix D GitCentric Glossary for definitions of terms used in GitCentric. 2 GitCentric User s Help

13 Basic Architecture The following diagram shows the basic configuration of a very simple GitCentric environment where the Git repository, Tomcat web server, and AccuRev server with databases for both GitCentric and AccuRev reside on the same server: Figure 1. Basic Architecture In this simple configuration, the GitCentric server hosts: a Tomcat web server configured with two GitCentric apps (a bridge and an administrative GUI) an AccuRev server which includes a PostgreSQL database, and which functions as both the GitCentric AccuRev server and a production SCM AccuRev server with a trigger (server_master_trigger) to notify GitCentric of changes in AccuRev a GitCentric installation directory, which generally (but not necessarily) contains a storage area for one more Git repositories which include triggers (pre-receive and update) and configuration files. (The triggers are Git hooks that gets copied to your GitCentric repos and which help keep AccuRev synchronized with your repo. Search the web for more information about Git hooks.) In this simple environment, the AccuRev server hosts both the AccuRev depot containing the streams that are mapped to branches in the Git repo, along with the database server for both GitCentric and AccuRev, and another trigger that keeps your repo synchronized with AccuRev. In fact the Tomcat server is also a part of the AccuRev installation, under the <ac_home>/webui directory. Note that configurations can be much more complex, with a Git repo on one machine, the Tomcat server on another machine, the AccuRev GitCentric server on yet another machine, and remote production AccuRev servers on even more machines. Additional Git repos, hosted either on GitCentric server local storage or on a SAN (Storage Area Network), and multiple AccuRev servers on remote hosts, can be added to the mix. In fact, for a large environment, it is likely that the production AccuRev servers would be on remote hosts, and that the AccuRev server on the GitCentric host would be used strictly for the GitCentric database. But GitCentric User s Help 3

14 for evaluations, or for smaller installations, it is fine for the GitCentric AccuRev server to function as both the GitCentric database server and the AccuRev production server. For the sake of this discussion, we will assume the simpler configuration where the Git repo and the AccuRev server (which includes the Tomcat server, the GitCentric database, and the production SCM database) all reside on the same machine. Regardless of the complexity of the installation, the basic GitCentric process remains the same: Git users push and pull files between their local Git repos and the GitCentric Git repo. AccuRev users promote and update files between their workspaces and the AccuRev Server. And GitCentric keeps the branches in the Git repos synchronized with streams in the AccuRev servers. GitCentric Users All GitCentric users -- whether they are Git developers or GitCentric administrators -- use GitCentric to self-register their accounts and their SSH public keys, and to maintain their account preferences. If code review is configured, then Git developers will also access Gerrit Code Review through GitCentric. However, many GitCentric features are geared toward administrators so that they configure AccuRev servers and their mappings to Git repository branches. GitCentric Administrators and Mapping Branches to Streams A GitCentric administrator uses the GitCentric GUI (and optionally the GitCentric CLI commands) to configure the mapping between Git branches and AccuRev streams. A Git repository ( repo ) is associated with a single AccuRev server, and with an AccuRev username (the service account ) for performing GitCentric administrative tasks. Once this association is defined, a GitCentric administrator can proceed to map Git repo branches to AccuRev streams on that server. The directory within a stream that is mapped to a Git branch is called the mount point. After the mapping has been done, the GitCentric bridge webapp uses triggers to automatically keep the Git repo and the AccuRev depot in sync, while the GitCentric GUI gives you the ability to create repos, map branches to streams, set ACLs, etc. Note that you can have multiple GitCentric AccuRev user accounts: administrative users who interactively log into the GitCentric GUI (and any related AccuRev servers), for manual administrative tasks service account users, accessed internally by the GitCentric bridge, for automatically syncing the Git repos and their mapped AccuRev streams Service account users must be defined (either as an individual user, or as a group) in the AccuRev server acserver.cnf file(s), using the ASSIGN_USER_PRIVILEGE setting in AccuRev 5.4 or later. Note: Best practice is to assign this to a group, so different members of the group can have different access rights. For example, one member of the group might be from an off-shore organization, with different access rights than another member of the group. The syntax for the entry in acserver.cnf is ASSIGN_USER_PRIVILEGE = <user_or_group_name> If you specify multiple ASSIGN_USER_PRIVILEGE settings, only the first one is honored. 4 GitCentric User s Help

15 Basic Rules Regardless of how many Git repositories or AccuRev servers you configure, when you associate a repo with a server, you map them at the branch and stream level: a Git branch is mapped to an AccuRev stream. You can map multiple Git branches (and multiple Git repositories) to a single AccuRev stream. You can map a Git branch to any directory within an AccuRev stream You cannot map a Git branch to multiple AccuRev streams. You cannot map a Git branch to the root stream in an AccuRev depot. (If you need to do this, simply create a new stream off the root, and then map to that.) Mapped Behavior If you push a file to the repository and it would require merging with the version of the file on the mapped AccuRev stream, GitCentric cancels the push and informs the user that he or she must pull the latest changes, merge and retry the push, the same way Git always handles these situations. When you first map a Git branch to an AccuRev stream, you can specify whether the files in Git or on AccuRev take precedence. Since AccuRev streams inherit versions from their backing streams, it is important to remember that if any element is promoted to a backing stream above a stream that is mapped to a repo, that element will automatically be pushed to the repo from AccuRev. Best Practices When Planning Your Installation GitCentric reflects the flexibility of both the Git and AccuRev environments, and it is possible to configure your repositories and streams in countless ways. However, AccuRev recommends keeping the following thoughts in mind: Git repositories are smaller, coherent groups of functionality. You do not merge files, you merge the whole repository. AccuRev depots tend to be large sets of files related to entire products, or multiple products. Therefore, you probably do not want to create a repository that maps to an entire depot. You want your Git branches to map to directories within AccuRev streams that contain smaller, independent sections of functionality. As with any new tool, it is important that you first understand what your current process is. If you are an existing Git shop, make sure that you have a clear picture of how your repositories and branches are configured, and what your workflow is. In evaluating this, you may find that you need to better define your current environment. If you have never gone through this exercise, consider searching for the following terms on the web: git, workflow, and model. This will point you to some good discussions about successful Git implementations. Once this is done, then you will be in a better position to decide how to map your branches to AccuRev streams. Also, remember that both Git and AccuRev bring different strengths to your organization. Git provides a convenient, distributed version control system to your development end users. AccuRev provides powerful, centralized version control for users such as build administrators, release engineers, product managers, etc. Git branches can be somewhat transient -- if you start to develop something on a branch and then change your mind, you can delete the branch. AccuRev is TimeSafe -- all versions and transactions are captured permanently in the AccuRev database. When carefully planned, mapping between these environments means that GitCentric provides the best of both worlds to your organization. GitCentric User s Help 5

16 Keeping Git Merges and AccuRev Promotes in Sync When you configure a Git repository to work with AccuRev through GitCentric, you map a Git branch to an AccuRev stream. If you wish to take advantage of AccuRev promote operations, you map the parent AccuRev Stream to one branch, and the child AccuRev stream to another branch. Figure 2. Git Merges and AccuRev Promotes If you configure things correctly and follow a few basic rules, then: Merges between the mapped branches in Git will result in an AccuRev promote between the corresponding streams. Promotes from the child stream to the parent stream in AccuRev will result in a merge between the corresponding branches in the Git repository if the content under the mount point is empty in the child stream. (That is, the merge will happen if the child stream is completely inherited so that it is the same as the parent at the mount point). Note that the desired condition when these operations are completed is for the default group in AccuRev stream C to be empty. (The default group is the set of elements or files in a stream that are under current development. A file is removed from a stream s default group when that file is either promoted or revert to back ed (or purged). See the AccuRev documentation for more details.) To ensure that this happens reliably and predictably, configure your system so that: 1. One stream is the parent of another stream, and each of these streams are mapped to branches in the Git repository. In this example, the parent stream is called P and the child stream is called C 2. There is no timestamp on AccuRev stream C. (A timestamp will prevent a stream default group from being cleared.) 3. The mount point must be the same in each AccuRev stream for the branches that are mapped to them. (If one branch is mapped to one mount point in one stream, and the other branch is mapped to a different mount point in the other stream, the files will never line up.) 6 GitCentric User s Help

17 4. Any AccuRev rules that are applied to the C stream are also applied to the P stream. (For example, avoid include/exclude rules one stream that cause that cause its contents to differ relative to the other stream. And do not use cross-links on writable elements.) From a Git viewpoint, this ensures that the branches point to the same commit graphs when their contents are identical. From an AccuRev viewpoint, this ensures that the default groups in the streams get cleared out when appropriate, and do not keep growing to include (potentially) all files in the system. Best Practice for Keeping Merges and Promotes in Sync AccuRev recommends that you merge into the child branch first, and then fast forward merge the parent branch. If you merge into the child branch first, AccuRev will reflect this by performing a promote from the child stream to the parent stream. However, if you merge into the parent branch first, AccuRev will achieve the desired zero default group state by performing an Accurev purge on the child stream. The Git commands for merging into the child branch are: 1. git checkout C 2. git merge P 3. git checkout P 4. git merge C (This will be a fast-forward merge. Existing merge commit will be reused.) 5. git push Scenarios for Mapping Multiple Repositories to a Single Stream There are two common reasons for mapping two different Git repositories to the same AccuRev stream: Project-based Security-based Project-based Figure 3. Project-based (same stream, different mount points) GitCentric User s Help 7

18 In this case, you might have two different parts of a product in two different directory structures in the same stream, such as a GUI development tree and a database development tree. In the Git environment, you could have the GUI work being done in one repository and the database work being done in another. By mapping the branches in these repositories to the correct mount points in the same stream, you can keep the work separate. (Keeping the branch names consistent across repos will be helpful if you need to make branch-mapping changes en masse using the children-of option in the SSH config-branch CLI command.) Security-based Figure 4. Security-based (same stream, same mount point, different service account) In this case, you could have two different sets of users with different access privileges accessing the same files. Privileged Git developers in corporate headquarters could have one repo mapped to the mount point with one service account having lenient AccuRev ACLs (see below). Less privileged off-shore contract developers could have a different repo mapped to the same mount point with a different service account having much more restrictive AccuRev ACLs. See Configuring for Security on page 9 for more information about ACLs and security. Also, by mapping branches from different repos to a single AccuRev stream, you can automate the process of updating repos with changes: when a change gets pushed to a repo that is mapped to an AccuRev stream, that change gets propagated to all other branches that are mapped to that stream (assuming that the AccuRev ACLs allow a repo to see the changed file). Multiple Repos and Multiple Servers Figure 1 above illustrates a simple case of a single Git repository being associated with a single AccuRev server through GitCentric. Figure 3 and Figure 4 above illustrate multiple repositories being mapped to a single AccuRev server. However, GitCentric can also configure multiple Git repositories with multiple AccuRev servers. For example, you could have one repo associated with one AccuRev server, and two other repos associated with a different AccuRev server. (However, a single repo cannot be associated with multiple AccuRev servers. And having multiple GitCentric servers configured with the same AccuRev server is not supported.) 8 GitCentric User s Help

19 If you choose to configure multiple AccuRev servers, AccuRev strongly recommends that you use the same GitCentric administrator user and password for all AccuRev servers to avoid the need to constantly log in and out as you move between servers. Figure 5. Multiple AccuRev Servers Note that if you choose, you can administer your Git repos with GitCentric and not have their branches mapped to any AccuRev streams at all. You do need to associate a Git repository with an AccuRev server for security purposes, but you do not need to have its branches mapped to use GitCentric. AccuRev Replica Server Restriction If your AccuRev installation has one or more replica servers, you should always try to associate GitCentric with the AccuRev master (if possible), and NOT a replica. Even if your GitCentric installation is physically located in close proximity to a replica server, you should try to configure GitCentric to work with the remote master AccuRev server, not the geographically closer replica server. (This may not be possible if your installation has implemented firewalls and VPN or some other kind of security that prevents you from communicating directly with a remote master server.) Configuring for Security As touched upon in Figure 4 on page 8, one of the advantages of using AccuRev GitCentric in a Git environment is that you can use both GitCentric and AccuRev security features to control access to files, a feature not natively provided by Git. GitCentric User s Help 9

20 GitCentric makes use of two kinds of Access Control Lists ( ACLs ): GitCentric group-based ACLs, which define access to Git repositories. AccuRev Element ACLs, which define permissions on the AccuRev server down to the individual element level. Using these two types of ACLs, you can approach GitCentric security in two ways: Using GitCentric group-based ACLs to specify allow and deny privileges on a repository ( project ) basis. Mapping multiple repos as different views on AccuRev-controlled elements. The AccuRevcontrolled elements may optionally be secured with AccuRev Element ACLs (EACLs). GitCentric Group-Based ACLs On the Git side, you define group-based ACLs and apply them to repositories, to control what kind of access group members have to GitCentric-controlled Git repos and branches. (GitCentric group-based ACLs are different than -- and should not be confused with -- AccuRev Element ACLs or EACLs, which control access to files on the AccuRev server.) GitCentric provides five system or pre-defined internal or groups: Administrators (internal) Anonymous Users (system) Non-interactive Users (internal) Repository ( Project ) Owners (system) Registered users (system) You can define more groups as necessary. GitCentric is installed with a basic set of ACLs on a special, system-defined project named All-Projects, from which all repos inherit their base set of ACLs. These basic ACLs are set to be highly secure, so you will need to customize them for your site before your users can use GitCentric. The general topic of group-based ACLs is beyond the scope of this document, so you will need to learn about them from the Gerrit Code Review documentation referenced below, but at a very high level: Every user account is a member of one or more groups, and access and privileges are granted to those groups. You cannot grant access rights to individual users. Access rights are then assigned to these groups per repo (or project ). Access rights granted to parent repos are inherited by child repos. Access rights defined for the All-Projects project are inherited by all other projects. For information about creating and configuring GitCentric group ACLs from the GitCentric UI, see Configure Access Rights (ACLs) for a Repo on page 30. Because GitCentric group ACLs are derived from Gerrit Code Review, they are documented in detail in the Gerrit Code Review documentation. See the Access Controls topic in the Gerrit Code Review documentation for more information. Configuring Multiple Git Repos with AccuRev and EACLs In AccuRev, it is a fairly common practice to configure depots and files with ACLs so that only certain users can access them. For example, assume that you hire an off-shore contract company to develop code 10 GitCentric User s Help

21 for an optional feature to your main product line. You might want to give staff in corporate headquarters access to all files and directories, while restricting access of the off-shore team to just those files and directories that they need to get the job done. By setting up ACLs in the AccuRev environment, and then mapping Git repositories and branches to these AccuRev depots and streams, you can give the off-shore team access to just the repo containing their files, while giving your domestic teams access to the repo that contains all your files (see Figure 4 on page 8). For information about setting up ACLs in the AccuRev environment, see the following AccuRev documentation: On-Line Help Guide: Chapter 8, Security Administrator s Guide: Chapter 9, AccuRev Security Overview CLI User s Guide: eacl, setacl, lsacl, and mkuser command descriptions in Chapter 2, AccuRev Command Line Reference Getting Started Once you have completed this chapter, and after you have installed GitCentric as described in the AccuRev GitCentric Installation and Release Notes, you should proceed to Get Started on page 13 in Chapter 2 How to... to learn how to configure your GitCentric environment and use it for the first time. GitCentric User s Help 11

22 12 GitCentric User s Help

23 2. How to... This chapter describes how to perform basic tasks with the AccuRev GitCentric GUI. (For an example of performing some of these tasks with CLI commands, see CLI Example on page 85.) For procedures that apply to all users, proceed to the next section. For procedures that apply only to Administrator users, see Procedures for Administrators Only on page 19. Procedures for All Users The procedures within this section apply to both regular users and administrators. Table 1. Summary of Common GitCentric Procedures for ALL Users To: Go to page: Get Started 13 Create an SSH key 13 Log In to GitCentric 14 Register with GitCentric 15 Set Preferences 16 Create a Clone From a GitCentric Repository 17 Switch Between Gerrit Code Review and GitCentric 19 Get Started This section assumes that you have completed the basic installation steps described in the AccuRev GitCentric Installation and Release Notes. Now you will perform some configuration steps and actually use the GitCentric GUI for the first time. Note: Note: Administrators -- Before you begin to associate Git repositories and branches with AccuRev depots and streams, you must have a solid understanding of your current Git and AccuRev processes. Please be sure to read through Chapter 1 Concepts and Overview, particularly GitCentric Administrators and Mapping Branches to Streams on page 4, Mapped Behavior on page 5, and Best Practices When Planning Your Installation on page 5. Create an SSH key This section applies to all GitCentric users, whether you are an administrator or an end user. Note: General SSH documentation is beyond the scope of this document. We recommend that you use your favorite search engine to find information about the topic. However, GitCentric administrators should know that the GitCentric installer now includes an SSHD daemon, and the product now GitCentric User s Help 13

24 includes a self-registration feature. This means that unlike the Kando release, you no longer need to manually install and configure an SSH server, and you no longer need to create and register SSH keys for your users. 1. If you know what an SSH public key is, and you know that you have one, and you know where your public key file is, you are all set! You can skip ahead to the next section. 2. If you need to generate a key, use the following syntax: ssh-keygen -t rsa -C <your_ >@<your_domain> Note: If you are an end-user on a Windows machine, you should install a Git Windows client such as msysgit, which includes ssh-keygen. See for more information. Make note of where your public key is stored. Typically it is in ~/.ssh/id_rsa.pub (or C:\users\<youraccount>\.ssh\id_rsa.pub on Windows). You will need it when you first log in to GitCentric. Log In to GitCentric The first step in using the GitCentric web GUI is logging in with your web browser. 1. Point your browser to the GitCentric web server. For example: You will see the following log-in screen and the GitCentric menus will be displayed, although some will be disabled until you log in. Note: The very first user to log in to GitCentric, who should be the administrator that installed it, will see a slightly different log-in screen, which includes a field for specifying a CLI Path. This initial login screen and procedure is described in the GitCentric Installation and Release Notes. 2. Here are the fields that you may encounter with either of these dialogs. Most are relatively selfexplanatory so long as you know that the Username and Password are your credentials on the AccuRev server. 14 GitCentric User s Help

25 AccuRev Server: From the pull-down menu, select the host name of the AccuRev server that you wish to associate with a Git branch, and where you have a login account. For example: acserver2:5050, or <ip_address>:5050 or localhost:5050. This may or may not be the same AccuRev server where the GitCentric database resides. In a simple configuration, this is may be the same host that you just connected to with your web browser, or it may be a remote server. Note that if localhost appears as an option, it refers to an AccuRev server on the host you are connecting to, not your local machine where you started your browser. User Name: -- The AccuRev user account on this server that you use. If you are an administrator, this would be the account that you use for GitCentric configuration, and might be an account such as acserver if you have legacy AccuRev systems. See the GitCentric Installation and Release Notes for a discussion about user accounts. Password: -- The password for the specified AccuRev user. Click Login when done. If this is your first time logging into GitCentric, you will be taken through the self-registration process described in the next section. Otherwise, you will be taken to the GitCentric UI. Register with GitCentric When you log in to GitCentric for the first time, you are prompted through a self-registration process. This is provided so that users with valid AccuRev accounts will not need to involve an administrator in getting set up on GitCentric: Enter your information as follows: 1. Full Name: Your real name (unless this is an account for a role such as Guest User. GitCentric User s Help 15

26 2. Register New ...: You should enter the same address here that you specified when you specified your user. configuration for your Git clone(s). You can specify multiple addresses and switch between them as necessary with the Preferred setting. Note: If your AccuRev user account is associated with an address, that address will be automatically inserted in this field. 3. Preferred Enter the same address here that you specify for the Git user. configuration for your clones. If these do not match, pushes from your clone will fail. If you need to maintain multiple addresses, you can add them later at My Account -> Contact Information. (See Contact Information on page 51.) 4. SSH key: Click the Add button and copy the contents of your SSH public key file here (see Create an SSH key on page 13) and Save it. (Note: If your AccuRev user account is associated with an SSH public key, that key will be automatically inserted in this field.) Your public SSH key file is typically ~/.ssh/id_rsa.pub. You can choose to do this later through My Account -> Public Keys (see Public Keys on page 51), but until this is set, you will only be able to use the code review features of GitCentric. 5. Click Continue when done. Set Preferences GitCentric provides a dialog for controlling various aspects of your display. 1. Click My Account in the upper-right corner of the window. 2. In the resulting My Account menu, click Preferences. 16 GitCentric User s Help

27 3. Most of these settings are self-explanatory, and are summarized on the reference page at Preferences on page 50. However, the Show Site Header setting is non-obvious and requires some set-up to make it work. Use the following procedure to set up a site header (and footer) within Gerrit Code Review. Define and Display a Site Header or Footer for Gerrit Code Review Gerrit Code Review provides the option of displaying a header and/or a footer in its web UI: 1. Create an image file or files that you want displayed for the header and/or footer. Place the file or files in <gc_home>/site/static 2. Create an XML-compliant file named GerritSiteHeader.html in <gc_home>/site/etc. Include a pointer to the image file or files in <gc_home>/site/static that you want to use for the header. Note that this file must be valid XHTML. It is not sufficient for it to be valid HTML. For example, the following example would not work if you left out the superfluous </img> closing tags. This example creates a site header from two image files displayed horizontally as a table row, with a link to the AccuRev web site from the splash image. Example: <div id="gerrit_header"> <table border="0" cellpadding="0" cellspacing="0" id="masthead" width="100%"> <tbody><tr><td valign="center"> <a href=" <img height="150" src="static/splash.jpg"></img></a> </td> <td width="100%"></td> <td align="right" valign="bottom"> <img height="150" src="static/titletop.png"></img> </td> </tr> </tbody> </table> </div> 3. If you also want a site footer, repeat the previous step for a file named GerritSiteFooter.html. 4. To enable the display of the header and footer, in the Web UI click Settings -> Preferences -> Show Site Header. Create a Clone From a GitCentric Repository The procedure for creating a local clone from a GitCentric repository is a basic Git operation: 1. git clone ssh://<gitcentriclogin>@<gitcentricserver>:<port>/<reponame> <clonename> where: <gitcentriclogin> is the AccuRev username you specified in Log In to GitCentric on page 14. <gitcentricserver> is the host where GitCentric is installed (the same you specify in the URL in Log In to GitCentric on page 14. <port> is the SSHD listener port (typically 29418). <reponame> is the name of the GitCentric repo. <clonename> is the name of the clone you are making of GitCentric repo. Notes about repo and clone names: Typically <reponame> and <clonename> will be the same, but they do not need to be. If the repo has a ".git" extension, you do NOT need to specify it in this command. GitCentric User s Help 17

28 By convention, only bare repos have a.git extension. Working repos do not. In general, you should NOT specify ".git" extensions when working with GitCentric. 2. Prepare to configure the clone: cd <clonetopdirectory> 3. Configure your username: git config user.name "<yourrealname>" 4. Configure your address: git config user. "<your address>" Note: This must be the same as your "Preferred " as registered with GitCentric in Register with GitCentric on page 15, or else git push operations will fail. Configure the Clone for Code Review (Optional) If you will be using GitCentric s optional Gerrit Code Review functionality as part your development, you MUST configure your clone as follows: git config remote.origin.push 'refs/heads/*:refs/for/*' This causes files to be pushed to a special branch for code review. If you will not be using Gerrit Code Review, and you are pushing directly to the repository, then leave this step out. In either case, ensure that your GitCentric administrator has set "push" and other ACL permissions correctly for either the Gerrit Code Review or direct push environment. (See Configure Access Rights (ACLs) for a Repo on page 30.) Configure the Clone for Direct Push If your site does not use the GitCentric s optional Gerrit Code Review functionality, you must ensure that the line push = refs/heads/*:refs/for/* (added by the git config command described in the previous section) does NOT appear in the [remote "origin"] section of your clones config file. Troubleshoot Git Clone Issues If you have a problem cloning a repository, or using it once it has been created, check the following: Ensure that the user has gone through initial GitCentric login and has the correct username, , and ssh. Test the ssh configuration with this command: ssh -p <gc_user>@<gitcentricserver> gitcentric --help This should return a usage message that refers to the config-branch, config-repo, and ls-repo commands. If the command returns an error message, ssh has not been set up correctly. In this case, try the command again using a -v switch to obtain additional messages that might be useful for debugging. Make sure that the path in the git clone call is correct. If you have an authorization error, have an administrator check the ACLs in Administration -> Repositories -> <reponame> -> Access. Have an administrator check the bare repo in the GitCentric storage directory. Use commands such as git log, git branch, and git cat-file p master. If it is empty, check the log files for initial import/export failure. 18 GitCentric User s Help

29 Note: Git does not track empty directories although AccuRev does. Therefore, if you have empty directories in your AccuRev stream, these will NOT appear in a Git clone of a repository that is mapped to that AccuRev stream. Switch Between Gerrit Code Review and GitCentric GitCentric incorporates the open-source Gerrit Code Review tool. Your site may or may not have made code review mandatory. If it is mandatory, then when you push your changes in Git, they must be approved by other reviewers before they are accepted into the repository. You may be asked to be a reviewer for other people s changes. If code review is not mandatory at your site, then when you push your changes, they go directly into the repository. To use GitCentric s optional Gerrit Code Review feature, click Code Review at the top of the Git Centric UI. Gerrit Code Review has its own documentation, which you can find here: If you are in the Gerrit Code Review tool, and need to return to the GitCentric UI, click the Settings choice on the Admin menu in the upper-right corner of the Gerrit Code Review UI. Experienced users of Gerrit Code Review should note that all administrator and user profile functions are accessed through the GitCentric UI. Procedures for Administrators Only The procedures in this section apply to only members of the Administrators group. Users that do not belong to this group cannot access this functionality, and cannot view items to which they do not have permissions. Table 2. Summary of Common GitCentric Procedures for Administrators To: Go to page: Configure AccuRev 20 GitCentric User s Help 19

30 Configure AccuRev Table 2. Summary of Common GitCentric Procedures for Administrators To: Go to page: Create a Repository for GitCentric 21 Remove a Branch or a Repository 23 Remove a Repository 23 Import an Existing Git Repo 23 Set General Attributes for a Repo 29 Create Branches for a Repo 30 Configure Access Rights (ACLs) for a Repo 30 Map a Git Branch to an AccuRev Stream 34 Unmap a Git Branch from an AccuRev Stream 38 Add an AccuRev Server 39 Manage GitCentric Groups 42 Configure AccuRev Element ACLs (EACLs) 43 Enable/Disable Code Review 44 Enable Gerrit Code Review Replication 45 Enable and Use Change Packages On the AccuRev server, make sure that server_master_trig.pl and Kando.xml files have been installed in the directory <ac_home>/storage/site_slice/triggers See the GitCentric Installation and Release Notes for details. (You will need to do this for each AccuRev server that works with GitCentric. For now, we assume that you are configuring just your first AccuRev server.) 2. Configure a stream to which your Git repository branch will map. Some guidelines: Identify the stream where you will be sharing files between AccuRev and Git. Determine which directory in this stream will be the mount point. Alternatively, if you need include/exclude rules to control which elements are visible to GitCentric, create a pass-through stream underneath the target stream, configure your include/ exclude rules on the pass-through stream, and map to that instead. (For best performance, if the target stream contains cross-links, create a pass-through stream and exclude the crosslinks.) You cannot use the root stream of a depot for GitCentric, so if you are targeting the root, you must create a sub-stream to map. If you will be using AccuRev element ACLs to control access to AccuRev-controlled files, make sure that your users, groups, and EACLs are defined and applied the way you want them. For example, you may plan to have one Git repository available to an off-shore team that will 20 GitCentric User s Help

31 have only limited access to your files, while another Git repo is used by your own, domestic development team that will expect to have access to all Engineering files. In this case, you would want to set up your EACLs in AccuRev so that the off-shore user group will see only the files they need. See the EACL documentation in the AccuRev Administrator s Guide for information about configuring this aspect of security. Configure GitCentric Once your AccuRev server is configured, use the procedures in this chapter to create and configure your Git repositories: 1. Log in to GitCentric (see Log In to GitCentric on page 14). 2. Add the AccuRev server to the GitCentric database (see Add an AccuRev Server on page 39). 3. Add a repository using GitCentric and map it to an AccuRev stream (see Create a Repository for GitCentric on page 21). 4. Set the security for the repository (see Access on page 60). Create a Repository for GitCentric A common task you will perform as a GitCentric administrator is creating a new Git repository for use with GitCentric, and optionally, mapping its branches to AccuRev streams. (If you have an existing repo that you wish to register with GitCentric, proceed to Import an Existing Git Repo on page 23.) The following procedures assume that: You have installed GitCentric as described in the AccuRev GitCentric Installation and Release Notes. You have read through Chapter 1 Concepts and Overview, particularly GitCentric Administrators and Mapping Branches to Streams on page 4, Mapped Behavior on page 5, and Best Practices When Planning Your Installation on page 5. The AccuRev server that was added to GitCentric during the initial login process is the server that contains a stream that you want to map to a Git branch. If you need to make another AccuRev server known to GitCentric before mapping a Git branch, proceed to Add an AccuRev Server on page 39, and then return here when done. To create a new repo: 1. Log in to GitCentric as described in Log In to GitCentric on page 14. GitCentric User s Help 21

32 2. When the GitCentric GUI appears, click the Administration menu. (See Administration on page 57 for reference information.) 3. Click the Add button and populate the fields in the resulting panel. Repository Name: Do not specify a ".git" extension for the repository name. GitCentric adds them on creation. Rights Inherit From: By default, new repos inherit their rights from the system-defined All Projects. Create initial empty commit: Allows a working repo to be cloned easily. You do NOT want to check this box if you are creating a repo into which you will be importing an existing repo (see Import an Existing Git Repo on page 23). You also do not want to enable Create initial empty commit if you are creating a repo as a parent-only project. Only serve as parent for other projects: Creating a parent-only project means that you can set ACLs on it and they get inherited by all its children. This also makes it easier to change the configuration of a number of repos at one time using the --children-of option to the gitcentric config-repo and config-branch CLI commands (see Command-Line Reference on page 79). 22 GitCentric User s Help

33 4. Click Save when done. Once a repository is created, you can set general attributes on it, create branches, configure access rights, and map its branches to AccuRev streams, as described in the following sections. Remove a Branch or a Repository These operations require manual procedures as described below. Remove a Branch There is no GitCentric "Delete Branch" feature. To remove a branch that has been mapped to an AccuRev stream, use this procedure: 1. Ensure that the Force option is applied to the Push and Push Annotated Tag permissions for the repo (see Access on page 60). 2. Use the GitCentric config-branch CLI command (see config-branch on page 80) to clear any GitCentric mappings: ssh -p <username>@<server> gitcentric config-branch --branch <branchname> <reponame> --clear Alternative: On the AccuRev Connector panel (Administration > Repositories > AccuRev Connector), select the mappings associated with the branch you intend to delete and click the Delete button. 3. Use the standard Git command to delete the branch: git branch -d $branch 4. Push the change. Remove a Repository There is no "Delete Repository" feature. You should not remove a repository from disk. Instead, set the description to "OBSOLETE" and set the ACLs so that only the Administrator group can see it. Import an Existing Git Repo If you have an existing Git repository that you would like to register with GitCentric and import into AccuRev, you can do so in one of the following ways: Import a snapshot of the current state of the repository into AccuRev. [BETA ONLY:] Import the complete Git history of the repository into AccuRev. (This form of import is still under development and should only be attempted on non-production content, with the assistance of AccuRev Technical Support at support@accurev.com.) A Note About AccuRev Depots You must import a Git repository into a case-sensitive AccuRev depot, unless you are 100% certain that repo is case-insensitive. Your Git repo will be case-sensitive if it has been created and developed exclusively in a Linux/UNIX environment. If it has included any development from Windows or OS X developers, there is a good GitCentric User s Help 23

34 chance (but not 100% certainty) that the repo is case-insensitive, even if the repo itself is hosted on a Linux/UNIX server. If you attempt to map a case-sensitive repo to a case-insensitive depot, you will encounter errors, either at import time, or further down the road. By default, AccuRev depots are case-insensitive, and the depot that is created during a new AccuRev installation is always case-insensitive. If you need a case-sensitive AccuRev depot for use with GitCentric, you (or an AccuRev administrator) must create one using AccuRev depot GUI features shown in the following illustration. See the AccuRev documentation for more information, or for the equivalent CLI commands to perform the same operation. Import a Snapshot of the Latest Heads into AccuRev If you do not care about capturing the repo history, the process can be as simple as making a copy of the repository under the GitCentric repo storage directory. The next time you restart the GitCentric server the repo will be visible through the GitCentric UI. To import a repository and just capture its current state: 1. Create a copy of the repo in your GitCentric repository home. cd <gc_repo_home> (For example, /home/<gc_installer>/accurevgitcentric/site/git) cp -r <orig_repo>/<new_repo_name> 2. Restart the GitCentric server. You have two options to accomplish this: Stopping and restarting the Tomcat web server: cd <ac_home>/webui/tomcat/bin./shutdown.sh./startup.sh Flushing the cache with an SSH command (entered on a single line): 24 GitCentric User s Help

35 ssh -p gerrit flush-caches --cache projects --cache project_list 3. Configure the repository through GitCentric and allow users to clone it as necessary as described in the other sections of this chapter. Import Complete Git History into AccuRev [BETA only] Note: The import of complete Git history into your AccuRev depot is available for evaluation as BETA-release functionality. You should only use it with non-production content, and with the assistance of AccuRev Technical Support If you want to capture full Git history, you will need to identify the SHA of the commit where you want the history to begin and push that commit first into a new, empty repo created with GitCentric. Then you push the final commit. For example, if you want all history, you would create a clone of the repo, then create a new, empty repo with GitCentric, push the first commit ever made in the repo, followed by the latest. If you are interested in the history from a particular date onward, you would need to push a commit from that date, followed by the latest. Note that these kinds of history-preserving imports can take extra time to complete depending on the number of files involved with each commit. In a repo with thousands of commits, averaging several files for each commit, you might need to schedule several hours (or even a day or two) to complete the import. To import the full Git history of the repository into AccuRev, perform the following steps with the assistance of AccuRev Technical Support. Be sure to budget sufficient time for the import operation to complete using a rule of thumb of approximately one to several seconds for each commit, depending on the average number of files per commit. The following procedure consists of several sub-procedures: I. Create Bare Repo and Check Admin Group Membership 1. Create a new, empty repository as described in Create a Repository for GitCentric on page 21, but do NOT check "Initial Empty Commit". 2. Ensure that your GitCentric login account is a member of the Administrators group (see Manage GitCentric Groups on page 42). II. Set ACLs on refs/* You must temporarily set the following ACLs on refs/* to allow the import to succeed. You can do this in one of the following ways, depending on how many repos you are importing: Set the ACLs on the specific repository you are importing. This is fine if you are importing only one or two repos. Set the ACLs on All-Projects. This is more efficient if you are importing multiple repos. This should be fine so long as you only apply this to the members of the Administrator group, and this group is truly restricted to administrator users. Set the ACLs on a parent-only repo, and make all the imported repos children of this parent. This has the advantage of not changing the ACLs of all your other repos, but you may not want to end up with all your imported repos under this parent after the import is done. Note: Regardless of the approach you use, it is critical that you set the ACLs back to a more secure model after the import is done. GitCentric User s Help 25

36 Here is a summary of the ACLs that you must set on refs/* for the Administrator group. See the detailed procedure below starting at Step 1 below, and see Configure Access Rights (ACLs) for a Repo on page 30 for general information: Create Reference Forge Committer Identity Push Push Merge Commit Note: These ACL settings are only for performing the import operation. You must read and understand the ACL documentation and set the proper ACLs on the repo when you are finished to ensure that your repository is secured for production use. 1. Click Administration -> Repositories 2. Click the repository on which you want to set the ACLs, as discussed above -- either the repo itself, or All-Projects, or a parent-only repo that you have created for this import process. 3. In the resulting display, click Access (see Access on page 60). 4. Click Edit, then Add Reference. 5. In the Reference field, enter refs/*. 6. Click Add Permission and click Create Reference. 7. In the Group Name field start to type Administrators (the type-ahead feature should provide an auto-completion string that you can click). 8. Click Add. 9. Repeat Step 6 through Step 8 for the following additional permissions: Forge Committer Identity Push Push Merge Commit 10. Optionally enter a commit message. 11. Click Save Changes. 26 GitCentric User s Help

37 12. When done, your repo ACLs should include the following entries: III. Make a Clone of the Repo to be Imported Using standard Git techniques, make a local clone of the repo which you want to import into GitCentric: 1. In your operating system, go to the directory where you store your Git clones. 2. Create the clone using whatever procedure you typically use (this example uses HTTPS for a public repo): git clone <reponame> 3. Edit <reponame>/.git/config to include user.name and user. settings, and to point to the new gitcentric repo. The lines in bold are the ones you need to add or edit. This is just an example -- substitute appropriate values for your installation. [core] repositoryformatversion = 0 filemode = false bare = false logallrefupdates = true symlinks = false ignorecase = true hidedotfiles = dotgitonly [remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/* url = ssh://jsmith@mygitcentrichost:29418/import_repo [branch "master"] remote = origin merge = refs/heads/master [user] name = Jamal Smith = jsmith@mycompany.com IV. Push the First Commit 1. Identify the SHA1 value of the first in the clone. For example, run the gitk utility, navigate to the initial commit, and copy its SHA1 from the SHA1 ID: field. 2. Push the first commit in the clone: GitCentric User s Help 27

38 git push <SHA1first>:refs/heads/master or git push origin <SHA1first>:refs/heads/master 3. Check the console and ensure that there are no errors before proceeding. V. Map the Repo to AccuRev The next step associates the master branch of the repo to a stream in AccuRev. As soon as the mapping is defined, the contents of the repo will be imported into AccuRev. 1. Follow the procedure described in Map a Git Branch to an AccuRev Stream on page 34. Ensure that Initial Synchronization is set to Commit Git Content to AccuRev. 2. As soon as you click Save, the initial import from the repo to AccuRev proceeds, and you can monitor it with the status display provided on the connector page 3. The status monitor updates every five seconds. When it goes blank, the import has completed. If it remains on the same step for more than 5 or 10 seconds, the import may have failed. 4. Even if you believe the import has succeeded, review the log file at: <tomcat_home>/logs/kandobridge.log It is important to confirm that the import completed without errors. Search for strings such as "error" or "exception". One common error is "Import failed: You are not authorized to use the -U option." This indicates a problem with the ASSIGN_USER_PRIVILIGE setting in acserver.cnf. If necessary, review the explanation in the Installation chapter of the GitCentric Installation and Release 28 GitCentric User s Help

39 Notes, correct the problem, and try again. More serious errors may direct you to contact AccuRev customer service for assistance. VI. Push the HEAD Once the initial mapping and import have succeeded, you need to push the HEAD to import all of the commits between the first commit and the most recent. Each of these will be synchronized with the AccuRev stream, thereby importing all of the commit history to AccuRev. Just execute a typical push command: git push As soon as your commits get pushed to the repository, they will automatically be synchronized with AccuRev. Again, you can watch the progress of this operation on the GitCentric status monitor. Note: Any user associated with a commit in this push who is a registered AccuRev user will appear in the history imported into AccuRev. Any user that does not have an AccuRev account will be replaced by the ASSIGN_USER PRIVILEGE user. As mentioned earlier, this process can take many hours to complete, depending on the size of your repo and the number of files associated with each commit. Watch the command line console and the status monitor for indications of any issues. When done, review the log for any errors that may have occurred silently during the import. If you view the AccuRev stream, you will see a new "G" icon indicating that it is now mapped to a GitCentric repo via the AccuRev Connector. Set General Attributes for a Repo 1. Go to the Administration -> Repositories page, and click the repository you want to configure. 2. This brings up the General pane, where you can set various attributes. For a description of the various options, see the reference page for this display, at General on page 58. GitCentric User s Help 29

40 Create Branches for a Repo 1. Go to the Administration -> Repositories page, and click the repository you want to configure. 2. In the resulting display, click Branches. 3. Click Create Branch. The fields are pre-populated with prompts to assist you with branch creation (see the reference page for this at Branches on page 59 for more information). Configure Access Rights (ACLs) for a Repo GitCentric implements a group-based ACLs security model derived from Gerrit Code Review. This is a powerful tool for defining who can do what with Git repositories under GitCentric control. You will need to have a solid understanding of these group-based ACLs and do some planning before implementing them, so be sure to first read the following section: GitCentric Group-Based ACLs on page 10, and the Gerrit Code Review documentation for details. General Procedure for Setting ACLs Use the following general procedure for settings ACLs on your repos. 1. Click Administration -> Repositories: 2. Click the repository you want to configure. Selecting All-Projects will cause all other repositories to inherit whatever ACLs you apply. (Note: Only the All-Projects system-defined repo has a "Global 30 GitCentric User s Help

41 Capabilities" section with an Administrate Server permission which gives Administrators broad powers across all repos. Be extremely careful when editing this permission.) 3. In the resulting display, click Access. (Reference information is a available at Access on page 60.) 4. In the Access panel, use the Rights Inherit From: link to specify the repository from which you want the new repository to inherit its access settings. (By default, all repositories inherit access rights from the system-defined All-Projects. You can create a parent-only repository to easily apply settings such as this to all child repositories. See Create a Repository for GitCentric on page 21 for more information.) 5. Click Edit, then Add Reference. In the Reference field, you can accept the default value (refs/ heads/*) to apply the access setting to all branches in repository, or modify it to apply to a specific branch. Specifying refs/* applies the ACL to everything in the repo. 6. Select the permission that you want to apply to this repository from the drop-down menu. GitCentric User s Help 31

42 7. After selecting the permission, complete the Group Name field for whom this permission applies in the this repository. The field supports type-ahead, so, for instance, entering R will provide Registered Users as a possible completion. 8. Optionally enter a commit message. An admin user can view this when performing a git log refs/meta/config command on the repository. 9. When done, click Save Changes. Configuring ACLs for Code Review Part of enabling the GitCentric s optional Gerrit Code Review functionality involves setting ACLs for Git references as shown in the following table: Table 3. ACL Settings Required to Support Code Review Reference Permission Setting Group refs/* Forge Author Identity ALLOW Registered Users Submit refs/for/refs/* Push ALLOW Registered Users refs/heads/* Label Code-Review (range -2 to +2) ALLOW Registered Users Most of these ACLs are set automatically for the All-Projects repository when you install GitCentric. There are slight differences based on whether you installed GitCentric for the first time, or you upgraded to GitCentric from an existing installation. If you: Installed GitCentric for the first time, all ACLs listed in the preceding table are set as the default for the system-defined "All-Projects" repository. Any repository that inherits rights from "All-Projects" is also configured to support code review. Upgraded to GitCentric from a previous release and you are currently using Gerrit Code Review, you will need to manually set the Submit permission for refs/* as shown in the preceding table. All other permissions (Forge Author Identity, Push, and Label Code-Review) were set as the default for All-Projects when you installed GitCentric. If you upgraded from a previous release and are not currently using Gerrit Code Review and now wish to, you must manually set all the ACLs listed in the preceding table. See General Procedure for Setting ACLs on page 30 for more information. Once the ACLs are set, all that remains to enable code review is for your users to configure their clones to support code review. See Configure the Clone for Code Review (Optional) on page 18 for more information. 32 GitCentric User s Help

43 Additional Considerations for ACLs There is no one set of ACLs that are appropriate for every installation; you must analyze the needs of your specific installation and adjust the default ACLs as necessary. See the Access Controls topic in the Gerrit Code Review documentation, specifically the section labeled "Examples of typical roles in a project" for suggestions about setting Gerrit Code Review ACLs. The remaining topics in this section describe other considerations to evaluate when enabling code review. Label Verified The "Verified" category is generally intended to be used in continuous integration environments where Gerrit Code Review is integrated with Hudson or Jenkins. Typically, the vote for this category is set to +1 by the integration tool indicating that it was able to compile and run tests on the change, allowing the change to be submitted. If you do not have a continuous integration environment, you can either disable the "Verified" category, or configure the "Label Verified" ACL in GitCentric to allow users to manually specify a vote via the Gerrit Code Review GUI. The ACL to allow manual voting for the "Verified" category is shown in the following table. Table 4. Setting Label Verified for Code Review Reference Permission Setting Group refs/heads/* Label Verified (range -1 to +1) ALLOW Registered Users Note: Specifying the "Label Verified" ACL this way permits any Registered User to approve and submit any code review change. This may be fine for testing, but you must tighten up ACLs for production. Allowing users to set "Label Verified" manually could be redundant with the "Label Code-Review" ACL. These three approaches to configuring the "Verified" category are summarized below in the order of desirability: 1. Configure Verify with Hudson or Jenkins for automated, Continuous Integration (CI). 2. Disable Verify completely. 3. Configure the "Label Verified" ACL in GitCentric (as shown in the preceding table) to allow users to vote manually in the Gerrit Code Review UI. If you choose the third option for testing purposes, you should consider either reconfiguring it for automated CI, or disabling it completely, prior to putting GitCentric into production mode. Configuring "Verify" for Continuous Integration With Hudson or Jenkins, you would typically set the Label Verified permission for the "Non-interactive users" group. See the Hudson, Jenkins, and/or Gerrit Code Review documentation for details about configuring a Continuous Integration environment. Disabling "Verify" If you are not using Jenkins/Hudson continuous integration, you can disable the "Verified" requirement in Gerrit Code Review with the gerrit gsql command: ssh -p <your_server.com> gerrit gsql DELETE FROM approval_categories WHERE category_id = 'VRIF'; DELETE FROM approval_category_values WHERE category_id = 'VRIF'; GitCentric User s Help 33

44 Configuring GitCentric ACLs for Direct Push If you do not wish to use GitCentric s optional Gerrit Code Review functionality, you must modify the default ACLs as follows. (These are simply minimal suggestions. You must analyze your site requirements and customize these settings as appropriate for your specific site.) 1. Change the setting for the "Push" permission for refs/for/refs/* to BLOCK. 2. Add the "Push" permission for refs/* and set it to ALLOW. 3. Add the "Push Merge Commits" permission to refs/* and set it to ALLOW. You must also have your users adjust the Git config file in each of their clones to remove the following line: push = refs/heads/*:refs/for/* Map a Git Branch to an AccuRev Stream You associate Git repositories and AccuRev depots at the branch and stream level: you map a specific branch in a Git repo to a mount point (a directory) within a specific AccuRev stream. GitCentric prompts you through this mapping process: Specify the Server and Service Account 1. Go to the Administration -> Repositories page, and click the repository you want to associate with AccuRev. 2. In the resulting display, click AccuRev Connector. (Reference information is a available at AccuRev Connector on page 60.) It is important that you specify the correct account here, so read carefully. The Service Account is the robot AccuRev user account that GitCentric uses to keep Git and AccuRev in sync. You may have different Service Accounts defined for different AccuRev servers and Git repositories that are under GitCentric control. AccuRev Server: Specify the host name (or IP address) of the AccuRev server that you wish to associate with this repository. If this is a new installation, and your GitCentric AccuRev server also functions as a regular AccuRev server, then you may have only one choice here. Other AccuRev servers can be added via the Servers tab (see Add an AccuRev Server on page 39). AccuRev Username: Specify the special AccuRev user that you defined during installation to perform GitCentric automated operations. This should be an account that is a member of the group that is assigned to the ASSIGN_USER_PRIVILEGE setting in the acserver.cnf file of the AccuRev server being mapped to this GitCentric branch. By convention, this account is often gcsyncuser, but it may be something different at your site. (See the notes under Basic Architecture on page 3 for more information.) Password: Specify the password associated with the account specified in the previous field. 34 GitCentric User s Help

45 Regular Expression: Enter a regular expression to enforce Git commit comments of a specific format, to support AccuRev change packages. If your AccuRev installation does not use change packages, leave this field blank. Use the Browse button to display a list of several pre-defined regular expressions. You can select one of these and edit it if necessary for your specific installation. For more information, see About GitCentric Regular Expressions below. Using an issue tracking system other than AccuWork: If your AccuRev installation uses change packages, but has implemented a third-party issue tracking system (ITS), check this box. About GitCentric Regular Expressions One of the powers of AccuRev is to associate all of the files affected by a particular change to an issue number tracking that change. This grouping of affected files is called a change package. (See the AccuRev documentation for information about change packages.) If you have change packages enabled on your AccuRev server, either through AccuWork or through a third-party issue tracking system, you may need to enforce the practice of including the issue number in the comment related to Git commits. That is the purpose of the Regular Expression field: to specify a commit message format that users must follow when pushing a change in Git that will be synchronized to AccuRev. The default example provided in the UI (Resolves\s+([\d,]+):) forces users to start their commit messages with Resolves <issue number>:. If this is not found, the push will be rejected. A discussion of Java regular expressions is beyond the scope of this document, but here are examples of what comments would be valid for some of these predefined expressions: (?:Resolves Resolved Fixes Fixed)\s*((?:(?:US DE)[\d, ]*)*) -- This format would be useful for the Rally issue tracking system, which makes use of user stories ( US ) and defects ( DE ): The comments can start with Resolves, Resolved, Fixes, or Fixed, followed by white space, and then any number of issue numbers prefixed with US or DE : Resolves US302, DE1405, US27 Fixed DE12849 Resolved\s+([\d,]+) -- This format would be adequate for simple environments where the comment always starts with Resolved, followed by white space, followed by any number of issues, separated by commas: Resolved Resolved 34, 149, 11057, 686 Use a search engine and search for Java regular expressions for more information about these formats. GitCentric User s Help 35

46 Map the Branch to the Stream Once you have specified the server, the Service Account, and regular expression (if any) for the target stream, you can map the branch to the stream by clicking the Add button. In each of the fields in the resulting panel, you can click a Browse button to navigate to the value you wish to specify. Note: You cannot map to the root stream of a depot. The Mount Point is the directory within the stream that will synchronize AccuRev and Git content. GitCentric provides a display that allows you to navigate to the desired directory. You can select the root of the file system within this stream, or a subdirectory, which populates the field. The folder you select determines which AccuRev-controlled files will populate your repository. Note: This step assumes that 36 GitCentric User s Help

47 you have carefully planned out your branch-to-stream-mapping, and that you have either created a new stream or have identified an existing stream that is appropriate for mapping. Finally, specify in which direction the files should flow when the Git repository and the AccuRev stream are first mapped. If you are mapping a repo with content to a new stream, select Commit AccuRev content to Git. If you are mapping an existing stream with files to a new repository, select Commit Git content to AccuRev. Test Your Mapping Status When you define your mapping and click Save, GitCentric synchronizes the contents of the Git branch and the AccuRev stream by importing (branch-to-stream) and exporting (stream-to-branch) files as necessary. You can check the status of this synchronization by clicking View Details to display the Status Monitor (see Task Monitor on page 61). The Status Monitor updates every five seconds, so after initial activity, if the task Status and Elapsed Time remain blank for five seconds, you can assume that initial import/export is complete; in this case, the value displayed in the Status column on the AccuRev Connector page will be Idle. However, if the Status field is not blank, but does not change for several seconds, the import/export may have failed. Check the <ac_home>/webui/tomcat/logs/kandobridge.log for any errors. Now, when you view the AccuRev stream you will see a new "G" icon indicating that the stream is mapped to a GitCentric repo via the AccuRev Connector. Create a Clone and Test It At this point, your Git users can create clones of the repo (within the limitations of whatever security settings you define). See Create a Clone From a GitCentric Repository on page 17. Whenever new content is pushed to the repo, it will automatically be reflected in the mapped AccuRev stream. On the AccuRev side, any content that is promoted into the mapped stream will automatically appear in the repository. Troubleshooting If the initial import/export operation failed after the mapping, check the following: Check Administration -> Repositories -> <reponame>-> AccuRev Connector/Branches for the status and the current branch SHA. GitCentric User s Help 37

48 Check kandobridge.log and look for failures, exceptions, and other errors. Use the kandomaintain command (see Appendix A The kandomaintain Utility) to enable PRESERVE_TEMP_FILES and ACCUREV_COMMAND_LOG debug configuration settings, and retry, running AccuRev commands manually to debug. Unmap a Git Branch from an AccuRev Stream Unmapping a Git branch simply removes the association between the Git branch and the AccuRev stream, which prevents any future synchronization between the two. Unmapping does not remove any content from either the branch or the stream. 1. Log in to GitCentric as described above in Log In to GitCentric on page 14, specifying the server which has the stream to which the branch is mapped. 2. Click the Administration->Repositories-><repo_name>->AccuRev Connector. (See AccuRev Connector on page 60 for reference information.) 3. From the list of mapped branches, identify the one that you want to unmap, then click its checkbox and then click Delete. 38 GitCentric User s Help

49 Add an AccuRev Server If the AccuRev server you use for SCM is the same one that the original Administrator user logged into after installation, you may never need to perform the procedures described in this section. But if you have multiple AccuRev SCM servers, then you need to add them to GitCentric. Adding an AccuRev server is a two-step process: 1. Register the AccuRev server with GitCentric. You need to register an AccuRev server with GitCentric if: You are adding another AccuRev server to GitCentric Your existing AccuRev server has multiple IP addresses See Registering an AccuRev Server on page Configure the server as described in Configuring the AccuRev Server on page 40. Registering an AccuRev Server For security reasons, the GitCentric bridge accepts commands only from IP addresses that it recognizes. If you add an AccuRev server that has multiple IP addresses (for example, if the server has multiple Ethernet cards), you must register each IP address. In this case, you should perform GitCentric operations only against one of these servers entries -- typically one where you have specified a host name rather than an IP address. To register an AccuRev server: 1. Log in to GitCentric as described in Log In to GitCentric on page When the GitCentric GUI appears, click the Administration->AccuRev Servers. (See Administration on page 57 for reference information.) 3. Click the Add button. 4. The AccuRev Server and Port fields are relatively self-explanatory, but the AccuRev CLI Path may need careful reading: GitCentric User s Help 39

50 AccuRev Server: -- The host name or IP address of the AccuRev server you wish to associate with one or more repos, or the IP address for an AccuRev server with multiple IP addresses. (The name of the server you first logged in to GitCentric with -- see Log In to GitCentric on page is automatically added to the GitCentric database.) Note that if you specify localhost, this indicates an AccuRev server on the GitCentric host, not necessarily the machine where you are running your browser. Port: -- This is typically 5050 for most AccuRev servers, but the AccuRev administrator may have changed it to something different. AccuRev CLI Path: -- This is the path to the AccuRev client executable on the GitCentric server that should be used to communicate with a particular AccuRev server. For example: <ac_home>/bin/accurev For more information, see A Note about the CLI Path Setting on page Successful completion results in a refresh of the Servers list to show the server you just added. Configuring the AccuRev Server The previous procedure simply registers the AccuRev server with GitCentric. Before you can use this server with GitCentric and Git, you must configure the server using the following procedure. 1. Check to see if a triggers directory exists under <ac_home>/storage/site_slice/. If not, create it. 2. Copy the Kando.xml and server_master_trigger.pl files from <gc_home>/bin to the AccuRev server trigger directory. For example: > cd <gc_home>/bin > cp Kando.xml server_master_trig.pl <ac_home>/storage/site_slice/triggers > cd <ac_home>/storage/site_slice/triggers > chmod +x server_master_trig.pl If the AccuRev server you want to use with GitCentric is on a different machine, you will need to use another method or command to copy these files, such as scp, or first copying the files to a Network File System (NFS) server and then to the machine hosting the AccuRev server. Note: server_master_trig.pl includes several lines of documentation in comments toward the end of the file. 3. Copy the value from the UUID column (you can use the clipboard widget if you have a Flash-enabled browser), and paste it into the Kando.xml server UUID line. For example: <configuration> <bridge_uri> <server_uuid>2388eccf-29cb-41e6-97c3-8ec64d13a710</server_uuid> </configuration> Note: Make sure that the tag is server_uuid and not server_id. The latter was used in older Kando Kando.xml files. 4. See the GitCentric Installation and Release Notes for suggestions about testing newly-configured servers. 40 GitCentric User s Help

51 Configure Multiple AccuRev Servers You can configure additional AccuRev servers for GitCentric using the same procedures above. However, you should observe the following guidelines: It is critical that the Kando.xml file for each server have the correct server uuid. The server uuid is available on the Administration->AccuRev Servers page. After adding the new server through the GitCentric GUI and updating Kando.xml, you must manually copy the XML and trigger files from <gc_home>/bin to the AccuRev server trigger directory as described in Step 2 above. Use the same username and password across all servers. Otherwise, you will frequently need to reenter your login credentials. If the multiple AccuRev servers are running different AccuRev versions, you must have an AccuRev CLIENT for each version installed on the GitCentric server. When you configure a server, you must point to the correct client in the CLI Path field. For more information, see A Note about the CLI Path Setting on page 65. If you have a situation where IP addresses can change over time (such as dynamic IP addresses assigned via DNS), you may need to consider setting AC_BRIDGEAPI_SECURITY_POLICY to AllowAnyHost. Note, however, that this workaround has a security impact that you need to carefully consider before implementing it. See GitCentric Bridge Configuration Settings on page 71 for more information. GitCentric User s Help 41

52 Manage GitCentric Groups GitCentric groups are derived from Gerrit Code Review groups. See the Gerrit Code Review documentation for details about how groups are implemented. The following section describes how to administer groups in the GitCentric context. To View and Access Groups Groups can be viewed, defined, and modified by clicking People from the GitCentric Administration menu: Add a Group To add a group to GitCentric: 1. Click Administration -> People. 2. Enter a name in the Create New Group field on the Groups panel. 3. Click Create Group. Add a Member to a Group To add a user to a GitCentric group: 1. Click Administration -> People. 2. Click the target group from the groups panel. 3. Click Members on the next page. 42 GitCentric User s Help

53 4. Click the Add button for the members table. 5. Start to enter a value in the Name or field. GitCentric provides type-ahead choice of valid users. 6. Select the user you wish to add and click Save. AccuRev Groups AccuRev groups are a special case handled by GitCentric. If your account is a member of a group in AccuRev, that group will be created in GitCentric as soon as you log in, and the group will be named with the format: Accurev.<accurevGroupName> Note that AccuRev group hierarchies are not replicated in Git Centric: if you belong to Group1 and also to a subgroup of Group1 named Group2:, GitCentric creates two peer-level groups: Accurev.Group1 and AccuRev.Group2. If you have upgraded to GitCentric from the Kando release, you probably have a kando_admin administrators group on your AccuRev server. If so, when GitCentric creates the Accurev.kando_admin group, it automatically grants this group "Administer Server" permission, which can be viewed by clicking Administration->Repositories->All-Projects-> Access and viewing the Global-Capabilities section. Note: If you have multiple AccuRev servers, groups with the same name from all AccuRev servers are combined in GitCentric. AccuRev groups created in GitCentric are read-only in the UI: you can see the properties and current members, but you cannot modify them. Membership in an AccuRev group in GitCentric is only updated upon login. If you change a user's group membership in AccuRev, it will not change for the GitCentric user until that user logs out (either explicitly, or due to a session time-out) from Git Centric and then logs back in. Configure AccuRev Element ACLs (EACLs) You can configure Element ACLs (EACLs) on the AccuRev server for the GitCentric Service Account, to determine which files can be edited in the GitCentric repository. Files that cannot be edited do not appear at all in the GitCentric repository. To set up AccuRev Element ACLs, see the following AccuRev documentation: The Security chapter in the AccuRev On-Line Help The eacl command description in the AccuRev CLI User s Guide The Element-Level Security (EACLs) section in the "AccuRev Security Overview" chapter of the AccuRev Administrator s Guide GitCentric User s Help 43

54 Enable/Disable Code Review Enabling GitCentric s optional Gerrit Code Review functionality is a two-step process: 1. The ACLs required to support code review are configured automatically for all new GitCentric installations; users upgrading to GitCentric may need to configure additional ACLs. As there is no one set of ACLs that is appropriate for every installation, you, as the administrator, should review these settings and adjust them as needed. See Configuring ACLs for Code Review on page 32 for more information. 2. Your users must configure their clones by adding the following line to the [remote "origin"] section of each clone s config file: push = refs/heads/*:refs/for/* This specifies the source (refs/heads/*) and target (refs/for/*) branch mapping that will be used to push changes to a special branch for code review. Users can add this line by executing the following command on each clone: git config remote.origin.push 'refs/heads/*:refs/for/*' Allowing Self-Reviews By default, Gerrit Code Review does not allow self-reviews. If you want to configure Gerrit Code Review to allow self-reviews, you must do so in the Gerrit Code Review Prolog file, rules.pl. In new installations of GitCentric , a copy of this file is installed to the /meta/config branch of the special "All- Projects" repository. Working with the rules.pl Prolog file is beyond the scope of this document. Refer to the Gerrit Code Review documentation for more information: Disabling Code Review Disabling code review is a two-step process: 1. As the administrator, clear the Enable Code Review check box on the General panel for the repositories for which you wish to disable code review. For new installations of GitCentric , this action automatically configures the repository s ACLs to enable direct push. If you have upgraded to GitCentric , this field appears as Advanced... and you must configure the repository ACLs to enable direct push manually. See Configuring GitCentric ACLs for Direct Push on page Individual users must remove or comment out the following line in the [remote "origin"] section of each clone s config file: push = refs/heads/*:refs/for/* 44 GitCentric User s Help

55 Enable Gerrit Code Review Replication Gerrit Code Review can be configured to push changes from Git repositories to one or more remote hosts. This section describes how to enable Gerrit Code Review replication in GitCentric. For general concepts related to Gerrit Code Review replication, refer to the Gerrit Code Review documentation. Overview The basic procedure for enabling Gerrit Code Review replication is summarized here: 1. Register the SSH public key representing the GitCentric bridge account with the Gerrit Code Review administrator s account. 2. Ensure that the server running Gerrit Code Review has SSH access to the server to which changes will be replicated. If the machine running Gerrit Code Review has never connected to the replication server, it will be listed as an unknown host and Gerrit Code Review will close the connection. 3. Modify the sample Git-style configuration file, replication.config, that is installed with GitCentric. 4. Stop and restart Gerrit Code Review. The following sections provide additional detail. Registering the GitCentric Bridge SSH Key with Gerrit The SSH public key representing the GitCentric bridge account is registered automatically when you install GitCentric the first time. If you have upgraded an existing GitCentric installation, you need to register the SSH public key manually. See Public Keys on page 51 for more information. Modifying the replication.config File Gerrit Code Review uses a replication.config file to identify the URL of the server to which changes will be replicated. For example: [remote "host-one"] url = gerrit2@host-one.example.com:/some/path/${name}.git A sample replication.config is installed to <gc_home>site/etc. To use this file: 1. Uncomment the example. Tip: Consider copying the example and using that copy to specify the URLs for one or more remote hosts. 2. Change the sample values for values applicable to your environment. 3. Stop Gerrit Code Review, which you can do by stopping the Tomcat web server. For example: cd <ac_home>/webui/tomcat/bin./shutdown.sh 4. Restart Gerrit Code Review. For example: cd <ac_home>/webui/tomcat/bin./startup.sh GitCentric User s Help 45

56 Enable and Use Change Packages If you wish to use AccuRev change packages with your Git commits, you must: Ensure that change packages are configured on the relevant AccuRev server. Ensure that change packages either were enabled when the repository was registered with GitCentric, or enable them now. Ensure that your users include carefully structured comments with their commits which specify the issue(s) addressed by the commit. Here are detailed procedures: 1. For configuring change packages on AccuRev, see the AccuRev on-line Help which includes all the current AccuRev documentation. Use the index and search mechanisms in the Help utility to configure change packages, and optionally, third-party issue tracking systems (ITS) if you are using something other than AccuWork. 2. You enable change package integration when you define a Regular Expression on the "AccuRev Connector" page (see Map a Git Branch to an AccuRev Stream on page 34). You may have done this when you first defined the mapping. If not, you can go to this page now as described in the following steps. 3. Log in to GitCentric as described in Log In to GitCentric on page Go to Administration->Repositories-><repo_name>-> AccuRev Connector. 5. In the Regular Expression: field, enter a regular expression to enforce Git commit comments of a specific format, to support AccuRev change packages. If your AccuRev installation does not use change packages, leave this field blank. Use the Browse button to display a list of several pre-defined regular expressions. You can select one of these and edit it if necessary for your specific installation. For more information, see About GitCentric Regular Expressions on page If your AccuRev installation uses change packages, but has implemented a third-party issue tracking system (ITS), check the box labeled Using an issue tracking system other than AccuWork. 7. Click Save. Once change packages have been configured, you must communicate two things to your end users: The requirement to add comments to their commits, in the format dictated by the regular expression chosen in Step 5 on page 46. The fact that they may see change package error messages upon a push, and that they must contact you as the GitCentric administrator for assistance in rectifying the cause of the error. 46 GitCentric User s Help

57 These errors are generated when GitCentric synchronizes the push with the AccuRev server, and the AccuRev server encounters a problem with the elements that comprise the change package. You (the GitCentric administrator) must act as a liaison to the AccuRev side of the world, including understanding change package errors and helping your end-users correct them. For example: A Change Package Required error simply means that an issue must be included in the commit comments, in the format dictated by the regular expression that was specified when change packages were enabled. An Issue did not meet criteria error typically means that commit comment was present and generally formatted correctly, but the actual state was incorrect (for example, comment says Completed instead of WIP ). A "cpk merge required" results during parallel development when two users make changes on the same file related to the same issue. Note that if the push command proceeds far enough to scan for issues, it outputs the issue it has detected in the commit message ( Issue(s):... for example). If the push command fails, reviewing this output may provide information that can help you troubleshoot any problems with the regular expression that was used to specify the commit message. For understanding and correcting change package errors that are caused beyond the GitCentric regular expression filter, please consult the AccuRev on-line help, which includes all AccuRev documentation. Use the search mechanism for change package discussions, particularly in the Concepts Guide and Technical Notes. Troubleshoot Import/Export Operations If you encounter an issue with syncing between a Git repository and AccuRev, check the following. AccuRev to Git Check the triggers.log and ensure that the trigger has fired. Check the KandoBridge.log and ensure that the trigger is reaching the bridge. Test server_master_trig.pl as described in the GitCentric Installation and Release Notes to check for missing dependencies. Check that Kando.xml exists in parallel with server_master_trig.pl in the AccuRev triggers directory, and that it points to the correct URL. To test the URL, manually paste it into a web browser. Check that Kando.xml server UUID is correct. Check that all necessary processes are running: postgres, tomcat, accurev_server. Retry by tickling the stream: accurev chstream E t. Git to AccuRev Check for any git push error messages. If you receive the following error, particularly when first mapping an existing Git repository to an AccuRev stream, you may be trying to map a case-sensitive Git repo to a case-insensitive AccuRev depot: GitCentric User s Help 47

58 Import: com.accurev.gemini.commonapi.ahcommonapiexception Element already exists See the Note: under Import an Existing Git Repo on page 23 for more information. If you are using Gerrit Code Review, make sure that the change is submitted (marked as review passed) after push. If you are using Gerrit Code Review and the change state is merge failed then the import failed. Import errors (which are usually push errors) appear in the Comments table at the bottom of the Gerrit Code Review Change page. Check the kandogerrit.log and ensure that the bridge is being called. Check the kandobridge.log and ensure that hooks are reaching the bridge. Check that all processes are running: postgres, tomcat, accurev_server. Check the AccuRev acserver.cnf configuration file and ensure that the service account group (typically "scm_bridge_group") is set as the value for ASSIGN_USER_PRIVILEGE, and that the group includes the actual user account (typically "gcsyncuser") as a member, and that this user account is the one that was specified when the branch was mapped to the AccuRev stream. (Note: some installations may use CC_USER rather than ASSIGN_USER_PRIVILEGE.) Retry by redoing the push. 48 GitCentric User s Help

59 3. My Account This chapter describes the features of the GitCentric My Account menu. The options on this menu are also available from the My Accounts link in the upper-right corner of the GitCentric window. Menu Options The following sections summarize the features of the My Accounts menu. Profile Displays a non-editable summary of your user information. You can change the Full Name and Address values through the Contact Information panel described below. The Username value shows your AccuRev account name. The Account ID is assigned to you automatically when you register with GitCentric. Note that ID is always the first user to register with GitCentric, and is automatically added to the Administrator users group. Note that while the information of the Registered field cannot be modified, its display format can be controlled with the Date/Time Format option under Preferences (see below). GitCentric User s Help 49

60 Preferences The Preferences page provides access to display and usability options. Field: Show Site Header Use Flash Clipboard Widget Description Enables/disables the optional header and footer images in your web UI display. See Define and Display a Site Header or Footer for Gerrit Code Review on page 17. When enabled, displays a widget on various text fields throughout the web UI that allows you to copy the contents of the field to the clipboard: CC Me on Comments I Write Display Patch Sets in Reverse Order Display Person Name in Review Category Maximum Page Size DateTime Format Note: Requires a Flash-enabled browser. When enabled, you will receive an containing comments that you submit in response to a review request. The default is to have this setting disabled, to reduce the amount of code review you receive. But if you want ed confirmation of comments published by your account, you have the option of enabling this setting. When enabled, reverses the display order of the patch sets in the Change Screen so that the latest patch set is always shown on top. This is useful when there are several patch sets for a change, and the latest patch set and the links to the diffs in the patch set end up below the fold of the Change Screen. When enabled, displays the name of the last reviewer in the R column of the Gerrit Code Review Dashboard. Specifies the maximum number of rows that will be visible in Gerrit Code Review displays. Allows you to specify one of four Date formats (three American, with month then day, using commas, hyphens, or slashes; or one European, with day then month, separated by periods), and one of two Time formats (12 hour AM/PM, or 24 hour). Watched Repositories (Projects) Note: Gerrit Code Review often uses the term Project to refer to a repository. AccuRev uses the terms repository or repo when referring to a repository, and reserves the term project when referring to specific Gerrit functionality, or when referring to some kind of planned or defined undertaking. The Watched Repositories page allows you to identify the repositories whose changes you want to track. Click the Add button to add a repository to the Watched Repositories page and to optionally configure Gerrit Code Review to send an notification whenever a change occurs in that repo. When adding a repo, use the Browse button to navigate to the repo of interest. If you want to specify conditions under which you want to be notified of a change (perhaps you are interested only in changes to a specific branch, for example), see the Searching Changes topic in the Gerrit documentation to learn more about search operations and search expression syntax. 50 GitCentric User s Help

61 Contact Information Enter the name of the currently logged-in user. You can register multiple addresses for this user, but only one can be specified as the preferred address. Public Keys You must configure SSH public key authentication before you can upload changes. If you already have an SSH key: Click Add and paste the contents of ~/.ssh/id_rsa.pub into the resulting Paste the public SSH Public Key below: field. Make sure that you do not introduce line-breaks when copy & pasting. If you need to create an SSH key: 1. If necessary, install ssh-keygen (this is normally included as part of a Git or O.S. installation). 2. > ssh-keygen -t rsa -C "<your address>@<yourdomain.com>" For more detailed information about SSH keys, see Create an SSH key on page 13, or follow the link on the dialog box. AccuRev Servers You use the AccuRev Servers page to associate a GitCentric user account with an AccuRev user account. You need to use this page only if you have multiple AccuRev servers in your environment. Otherwise, the GitCentric<-->AccuRev user account association is managed automatically, as part of the self-registration process. (See Register with GitCentric on page 15 for more information on self-registration.) Note: Although the UI does not enforce this, you should not specify multiple user accounts on the same AccuRev server here. If you specify more than one user ID on the same server, GitCentric may default to one that you did not intend. It is fine to specify multiple servers here, with one user ID each. To specify a GitCentric<-->AccuRev user account association: 1. Click the Add button. 2. On the panel that appears: a. Select the server from the AccuRev Server drop-down list. b. Enter your username on that server in the AccuRev Username field. The AccuRev user on this server that you use for GitCentric functions. If you are an administrator, this might be an account like acserver if you have legacy AccuRev systems. See the GitCentric Installation and Release Notes for a discussion about this user account. c. Enter the password associated with that username in the Password field. 4. Click the Save button to register the account. HTTP Password Some environments do not permit you to use SSH to connect across a firewall. If you cannot use SSH, but you can connect to the server with smart HTTP, you can generate a password here, and then access your Git repositories with a URL constructed with...p/<repository>. Note: GitCentric supports only Git smart HTTP not so-called dumb HTTP. Smart HTTP is documented on several Git-related sites. GitCentric User s Help 51

62 The syntax to clone a repository with smart HTTP is: git clone Example: git clone Once you have cloned, you can pull / push over HTTP just like you can over SSH. Note: If you wish to keep the <username>:<password> out of the URL for security reasons, you can create a.netrc file in your home directory ( _netrc if you are using msysgit on Windows). For example: machine localhost login testuser password PaoYhDp8BfoA People This is a read-only display of the security groups to which the logged-in user belongs. To create or modify groups, go to Administration -> Groups in the Web GUI. For details about how groups are implemented, see the Gerrit Code Review documentation. For How to information about managing groups in the GitCentric context, see Manage GitCentric Groups on page GitCentric User s Help

63 4. Code Review This chapter describes the purpose of the GitCentric Code Review menu, which serves as a gateway to the third-party Gerrit Code Review tool. To learn how to use Gerrit Code Review in GitCentric, see Enable/Disable Code Review on page 44. Overview of Gerrit Code Review GitCentric incorporates the open source Gerrit Code Review tool, which provides web-based code review and project management for Git-based projects. GitCentric administrators can decide whether or not to require users to include Code review in their workflow. Even if your site does not require you to perform code reviews, GitCentric makes use of Gerrit s group-based ACLs and administration features. Differences from Standalone Gerrit Code Review Gerrit is accessed from the GitCentric UI (from the Code Review menu shown in the illustration at the top of the page), and log-in and registration are handled through the GitCentric UI (see Log In to GitCentric on page 14). If you are familiar with Gerrit, you may notice the following differences from a standalone installation. 1. Administration features are accessed from the GitCentric UI. The Administration menu takes you to the Administration page in the GitCentric UI (see Chapter 5 Administration). GitCentric User s Help 53

64 2. User settings are adjusted from the GitCentric UI. The Settings link takes you to the My Account page in the GitCentric UI (see Chapter 3 My Account). 3. Support is handled through AccuRev Customer Service. Otherwise, all other Gerrit Code Review functionality is handled through the Gerrit UI, and documentation for Gerrit features is handled by the Gerrit on-line help. Code Review for Users of Differing Backgrounds Experienced Git users: If you are a Git user who is new to both Gerrit and AccuRev, you will continue to use Git the same way you always have. However, if code review is enforced at your site, you may now need to configure your clones to push to a special code review branch (see Create a Clone From a GitCentric Repository on page 17). Your changes will need to be approved by others, and you may be requested to approve other people s changes. In any case, once your changes are approved and pushed to the repository, GitCentric automatically synchronizes them with the appropriate stream in AccuRev. Likewise, when you do a pull, fetch, or clone, you may find that changes have been synchronized from the AccuRev stream. Experienced AccuRev users: If you are an experienced AccuRev user, your site may have you continue to manage your changes in AccuRev SCM. If so, you may never need to log into GitCentric or use code review. But if you start working in Git, you will use GitCentric to access the code review features, and to manage your account. Experienced Gerrit users: If you are an experienced Gerrit user, not much has changed: You push your updates in Git, and they get code-reviewed in Gerrit. If you are a reviewer, you will log in through GitCentric, and then go directly to Gerrit where you will perform Gerrit operations the same way you always have. However, your changes will now be automatically synced between the repository and the AccuRev stream to which it is mapped. (And if changes are made in the AccuRev stream, they will automatically be synced with the corresponding repository, and you will see them the next time you do a pull/fetch/clone command.) The Settings link now goes to the GitCentric UI, and administrators will find that all administrative functions now appear through the GitCentric UI. Regardless of your experience and your expertise, you should be aware that the four components that you may work with (Git, Gerrit, GitCentric, and AccuRev) each have their own documentation and knowledge base. Several excellent sites exist on the web for Git and Gerrit; and Gerrit, GitCentric, and AccuRev all have extensive on-line help. And you should have at least one experienced user or administrator at your site who is knowledgeable about each of these technologies. Gerrit Code Review and AccuRev Mappings The mapping between Git repositories and AccuRev streams is generally transparent to Gerrit Code Review users, but you should be aware of the added meaning of the Merged status when a change has been approved: in a mapped GitCentric environment, merged not only indicates that the changes have been merged in the repository, but they have also been successfully imported to the AccuRev stream. If you cannot get to the Merged status, you should check for error messages on the Gerrit Code Review page and troubleshoot any issues preventing the import. 54 GitCentric User s Help

65 Troubleshooting If you have difficulty submitting an approved change and cannot import it to AccuRev (as indicated by a Merge Pending or some other status), check the following: Look for error messages in the Change comments area Have an administrator check that the following group ACLs are correct for the repository: Submit, Label Code Review, and Label Verified Ensure that the commit parentage is up to date, and rebase if necessary Examine the dependencies list for any changes that need to be submitted before the current change will merge Check the kandogerrit.log for errors Check the kandobridge.log for errors GitCentric User s Help 55

66 56 GitCentric User s Help

67 5. Administration This chapter provides reference information for the features of the Administration menu: The Administration menu allows you to configure: repositories groups AccuRev servers For task-oriented procedural information about using this page, see Chapter 2 How to... GitCentric User s Help 57

68 Repositories The Repositories page (shown in the screenshot above) lists the repositories that are currently registered with GitCentric, and provides the ability to create a new one. To Create a New Repository Click the Add button to create a new repository. Procedures for using this panel are found at Create a Repository for GitCentric on page 21. Table 1. Create repository options Repo Name Field Rights Inherit From: Create initial empty commit Only serve as parent for other repos Description Enter any valid string for the new repository. Keep it URL-friendly: just letters, digits, and dashes; no whitespace. Character length is only limited by your OS. There is no database limit on the text field. By default, your repo inherits access rights from the top-level Code Review repo ( project ) named All-projects. However, you can specify a different repo for more control. When creating a new repo, it s good practice to make an initial empty commit to simplify any subsequent creation of clones and pushing from or pulling to them. Use this option if you wish to create a repo with specific access rights which other repos can inherit. In the GitCentric world, this can be especially useful if you need to migrate old-style Kando Named ACLs. See the GitCentric Installation and Release Notes for more details. To Configure an Existing Repository 1. Click on a repository name. 2. Select General, Branches, Access, or AccuRev Connector. General The General panel allows you to specify basic repo properties, primarily associated with Gerrit Code Review features. The various fields are described in Table 2 below. Table 2. General Repo Settings Description Setting Description Enter a string that will appear in the Repository Description column of the repository lists. 58 GitCentric User s Help

69 Table 2. General Repo Settings Setting Git Repository Options Gerrit Repository Options Description Ignore Case -- When checked, sets core.ignorecase=true in the repository s.git/config file. Ignore Symbolic Links -- When checked, sets core.symlinks=false in the repository s.git/config file. Submit Type -- Options that allow you to control how to merge changes: Fast Forward Only Merge if Necessary Always Merge Cherry Pick For a discussion of these merge options, see the Project Configuration topic in the Gerrit Code Review documentation. State -- Determines the accessibility of the repository: Active -- Users can view, pull from, clone, or push to this repository (assuming that they have the correct access rights). Read Only -- Users can see and pull from this repository (assuming that they have read permission) but cannot modify or push to it. Hidden -- Only Owners can see the repo. Contributor Agreement Basic Permissions Clone Command Automatically Resolves Conflicts -- By default, Code Review attempts merges only if there is no path conflict. Enabling this option forces Code Review to attempt the merge even if a path conflict occurs. Require Change-Id in commit message -- For a discussion of Change-Ids, see the Change-Ids topic in the Gerrit Code Review documentation. (Note: Does not apply to commits pushed directly to a branch or tag.) Require Signed-off-by in commit message -- For a discussion of Signed-off-by lines, see the Signed-off-by Lines topic in the Gerrit Code Review documentation. Enable Code Review -- Indicates whether or not GerritCode Review is enabled for the current repository. By default, this field is checked. See Enable/Disable Code Review on page 44 for more information. Lets you quickly copy the git clone command for the current repository specified using either the HTTP or SSH protocol. Branches The Branches panel displays the existing branches associated with this repo, and provides the ability to delete a branch or create a new one. See Create Branches for a Repo on page 30 for a description of how to use this section. The labels in this section are relatively self-explanatory: Branch Name: See the Git documentation for git-check-ref-format for restrictions regarding Git branch names. Initial Revision: This is typically either HEAD, or the name of another branch, or the SHA1 hash for a specific commit. GitCentric User s Help 59

70 Access The Access panel allows you to apply GitCentric group-based permissions (ACLs) on your repositories. These ACLs are derived from Gerrit Code Review ACLs. Procedural information for setting ACLs is provided at Configure Access Rights (ACLs) for a Repo on page 30. Overview and detailed information about group-based ACLs is provided at: GitCentric Group-Based ACLs on page 10 The Change-Ids topic in the Gerrit Code Review documentation. 1. Most ACLs take Allow, Deny, or Block. values. However, Label Verified and Label Code-Review take numeric values which are displayed as reviewer options on the Code Review page. 2. Each permission provides an Exclusive checkbox, which grants an exclusive ref-level access control so that only members of a specific group can perform an operation on a repository/ reference pair. See the Access Controls topic in the Gerrit Code Review documentation for more information. 3. The Push and Push Annotated Tag permissions also provide a Force Push option, which allows an existing branch to be deleted. Since a force push is effectively a delete immediately followed by a create, but performed atomically on the server and logged, this option also permits forced push updates to branches. Enabling this option allows existing commits to be discarded from a project history. AccuRev Connector Use the AccuRev Connector panel to define the mapping between branches in your Git repositories and mount points in your AccuRev streams. The procedure for using this panel is found at Map a Git Branch to an AccuRev Stream on page 34. Table 3. AccuRev Connector Settings Section Field Description Server AccuRev Server: The AccuRev server where the stream to be mapped exists. AccuRev Username: The <gc_user> account that is a member of the group that is set to ASSIGN_USER_PRIVILEGE. Password: The password for <gc_user>. Regular Expression: If AccuRev uses an issue tracking system (either AccuWork, or a third-party system such as Rally), you can specify a regular expression here to enforce comment requirements for AccuRev change packages. Populating this field enables change package integration; leaving it blank disables it. Using an issue tracking... By default, change package integration assumes that you are using AccuWork for your issue tracking system. If you are using a thirdparty system such as Rally instead, then click this checkbox. Add Branch Branch: The branch that you want to map to an AccuRev stream. AccuRev Depot: The AccuRev depot containing the stream that the Git branch is mapped to. 60 GitCentric User s Help

71 AccuRev Stream: Mount Point: Initial Synchronization: Table 3. AccuRev Connector Settings Section Field Description The AccuRev stream to which the current branch is to be mapped. The directory in the mapped stream to which the branch is to be synchronized. Navigate to the mount point in the graphical tree and click it to populate the Mount Point field This determines in which direction the first mapping will occur. If you are importing an existing repo into AccuRev, select Commit Git content to Accurev. If you are exporting the existing content of an AccuRev stream to a newly mapped repo, select Commit Accurev content to Git. The informational line between the server and branch panels shows any existing mappings. The Status column shows Active whenever an import or export is occurring between the branch and the stream. Click View Details to display a real-time Task Monitor. Task Monitor The Task Monitor displays a variety of status entries telling you what the GitCentric bridge is doing and generally where it currently is in the process. It tracks phases per commit, so if you do a multi-commit push (such as a push on an existing repository to import commit history import into AccuRev), you will see these phases repeat over and over for each commit import. The Task Monitor updates every five seconds during an import or export operation. If the information in the Status row display does not change after several seconds, check the Tomcat logs for errors. The following table summarizes the task type information displayed in the Task Monitor Status row. GitCentric User s Help 61

72 Table 4. Repo Status Entries Task Type: Phase: Steps: IncrementalImport (16 phases total) Initialization doimport - Cleanup Workspace doimport - Parse Commit Messages doimport - Process Commit Diff setuppromote - processemptydirs setuppromote - processmoveaside setuppromote - checkeviltwinformove setuppromote - checkundefunctfiles setuppromote - checkundefunctdirs setuppromote - checkeviltwinfiles setuppromote - undefunctelements setuppromote - cofiles setuppromote - processelinks setuppromote - popfiles setuppromote - movefiles setuppromote - deletefiles setuppromote - blobfiles setuppromote - addfiles setuppromote - keepfiles setuppromote - linkfiles setuppromote - mergefiles setuppromote - chmodfiles setuppromote - removeoverlaps doimport - Promote files 1 "step" 1 "step" 1 "step" n "diffs" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step" n "elements" 1 "step" n "elements" 1 "step" n "elements" 1 "step" n "blobs" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step 1 "step" 1 "step" 62 GitCentric User s Help

73 Task Type: Phase: (Continued) Steps: FullImport (19 phases total) FullExport (4 phases total) IncrementalExport or CatchUpExport (6 phases total) Support for Hooks Initialization streamtocommit - Init streamtocommit - Process Elements streamtocommit - Finalize Commit doimport - Cleanup Workspace doimport - Parse Commit Messages doimport - Process Commit Diff setuppromote - processemptydirs setuppromote - processmoveaside setuppromote - checkeviltwinformove setuppromote - checkundefunctfiles setuppromote - checkundefunctdirs setuppromote - checkeviltwinfiles setuppromote - undefunctelements setuppromote - cofiles setuppromote - processelinks setuppromote - popfiles setuppromote - movefiles setuppromote - deletefiles setuppromote - blobfiles setuppromote - addfiles setuppromote - keepfiles setuppromote - linkfiles setuppromote - mergefiles setuppromote - chmodfiles setuppromote - removeoverlaps doimport - Promote files Initialization streamtocommit - Init streamtocommit - Process Elements streamtocommit - Finalize Commit exportsingle - Init doexport - gettransinfo doexport - getchangeset doexport - generatefastimport doexport - gitfastimport exportsingle - Check null commit 1 "step" 1 "step" n "elements" 1 "step" 1 "step" 1 "step" n "diffs" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step" n "elements" 1 "step" n "elements" 1 "step" n "elements" 1 "step" n "blobs" 1 "step" 1 "step" 1 "step" 1 "step" 1 "step 1 "step" 1 "step" 1 "step" 1 "step" n "elements" 1 "step" 1 "step" 1 "step" 1 "step" n "changes" 1 "step" 1 "step" GitCentric supports both Git and Gerrit Code Review hooks. AccuRev recommends using Gerrit hooks when your environment requires hooks. For more information about Gerrit Code Review hooks, see the Gerrit Code Review documentation, here: GitCentric User s Help 63

74 Migrating Existing Git Hooks Two Gerrit hooks, ref-update and ref-updated, are installed to <gc_home>/site/hooks and are used to migrate any Git hooks you might have created in the <gc_home>/site/git/<reponame>.git/hooks directory. Note that the ref-update and ref-updated hooks require Perl and expect to find it at /usr/bin/perl. If you have Perl in a different location, you will need to update these hooks with the correct path. People Group membership determines access rights in GitCentric. Use the Groups panel to list existing groups, create a new group, and to access details about an existing group. See Manage GitCentric Groups on page 42 for information about using this panel. 64 GitCentric User s Help

75 AccuRev Servers The AccuRev Servers panel displays information about configured AccuRev Servers and allows you to add or remove them from GitCentric. When you click the Add button, the AccuRev Servers panel expands to display the fields you use to add an AccuRev server to GitCentric. These fields are summarized in the following table: Server Field: AccuRev Server Port AccuRev CLI Path Description The host of the AccuRev server that GitCentric associates with one or more repos. This can be an IP address or the name of the server. Note that if you are connecting to a remote GitCentric server and you specify localhost, this indicates an AccuRev server on the GitCentric host, not your local machine. This is typically 5050 for most AccuRev servers, but the AccuRev administrator may have changed it to something different. The path to the AccuRev client executable installed on the GitCentric server (not the remote AccuRev server). For example: /opt/accurev/bin/accurev. For more information, see A Note about the CLI Path Setting on page 65. See Add an AccuRev Server on page 39 for information about using this panel to add a server. A Note about the CLI Path Setting When logging into GitCentric for the first time, or when configuring an AccuRev server to work with GitCentric, you are prompted to enter a value for the CLI Path. This is the full path to the AccuRev client executable on the GitCentric server that should be used to communicate with the AccuRev server. For example: <ac_home>/bin/accurev where <ac_home> is the actual install directory, such as /opt/accurev. When you are connecting to the GitCentric AccuRev server, where its client and GitCentric home typically all reside on the same machine, this may seem redundant. But if you are pointing to AccuRev servers on other machines, you must have compatible clients installed on the GitCentric server machine, and this is what this path is set to. This becomes exceptionally important if you have multiple AccuRev servers and they are at different release levels. For example, if you need to work with two AccuRev servers -- one GitCentric User s Help 65