Helix4Git Administrator Guide - Perforce · Helix4Git Administrator Guide ... Git users use a Git...

Helix4Git Administrator Guide2018.1

March 2018

Copyright2015-2018PerforceSoftware

Allrightsreserved.

PerforceSoftwareanddocumentationisavailablefromwww.perforce.com.YoucandownloadandusePerforceprograms,butyoucannotsellorredistributethem.Youcandownload,print,copy,edit,andredistributethedocumentation,butyoucannotsellit,orsellanydocumentationderivedfromit.Youcannotmodifyorattempttoreverseengineertheprograms.

ThisproductissubjecttoU.S.exportcontrollawsandregulationsincluding,butnotlimitedto,theU.S.ExportAdministrationRegulations,theInternationalTrafficinArmsRegulationrequirements,andallapplicableend-use,end-useranddestinationrestrictions.Licenseeshallnotpermit,directlyorindirectly,useofanyPerforcetechnologyinorbyanyU.S.embargoedcountryorotherwiseinviolationofanyU.S.exportcontrollawsandregulations.

PerforceprogramsanddocumentsareavailablefromourWebsiteasis.Nowarrantyorsupportisprovided.Warrantiesandsupport,alongwithhighercapacityservers,aresoldbyPerforceSoftware.

PerforceSoftwareassumesnoresponsibilityorliabilityforanyerrorsorinaccuraciesthatmightappearinthisbook.Bydownloadingandusingourprogramsanddocumentsyouagreetotheseterms.

PerforceandInter-FileBranchingaretrademarksofPerforceSoftware.

Allotherbrandsorproductnamesaretrademarksorregisteredtrademarksoftheirrespectivecompaniesororganizations.

AnyadditionalsoftwareincludedwithinPerforceSoftwareislistedin"LicenseStatements"onpage96.

https://www.perforce.com/

Contents

How to Use this Guide 7Feedback 7

Otherdocumentation 7

Syntaxconventions 7

Whats new in this guide 92018.1release 9

2017.2release 9

Newfeatures 9Overview 10Architectureandcomponents 11

P4Jenkinssupport 12Workflow 13

One-timetasks 13Recurringtasks 13Gitclienttasks 14

GitConnectorCommands 14

Installation and configuration 17Systemrequirements 17

InstalltheGitConnector 18

UpgradingGitConnector 20

Upgradingtoversion2017.2fromthe2017.1patch 20Upgradinghelix-git-connectorthatispriortothe2017.1patch 21

ConfiguretheGitConnector 22

PerformConnector-specificHelixServerconfigurations 24

Grantpermissions 25Creategraphdepots 26Createrepos 26Configureaclientworkspacetosyncrepos 26Syncarepo 27

SetupGituserstoworkwiththeGitConnector 27

Prerequisite 27Authentication 27SSH 28

3

HTTPS 30VerifytheGitConnectorconfiguration 30

Push,clone,andpullrepos 30

SSHsyntax 30HTTPSsyntax 31

Depots and repos 32Creategraphdepots 32

Createandviewrepos 33

Specifyadefaultbranch 34Manageaccesstographdepotsandrepos 34

Setupclientworkspaces 35

Syncfilesfromgraphdepots 36

Syncusinganautomaticlabel 37One-way mirroring from Git servers 39GitHuborGitLabconfiguration 40

GitHuborGitLabHTTP 40GitHuborGitLabSSH 42

Gerritconfiguration 44

SystemrequirementswithGerrit 44Nextstep 44Installationofthemirrorhooks 45ConfigureGerritforHTTP 45ConfigureGerritforSSH 47Testingthemirrorhook 49TroubleshootingGerritone-waymirroring 49

HelixTeamHubconfiguration 50

Overview 50Systemrequirements 51InstallationofHelixTeamHubOn-Premise 51Nextstep 51HelixTeamHubHTTP 52HelixTeamHubSSH 55

GitConnectorconfigurationforfail-overtoanotherGithost 58

Procedure 59Example 60Effect 62

4

Command-lineHelp 62NextSteps 62

Configuring Git Connector to poll repos from Helix4Git 64Procedure 64

Troubleshooting 66Connectionproblems 66

SSH:userpromptedforgitspassword 67SSLcertificateproblem 68HTTPS:userdoesnotexist 68

Permissionproblems 68

Thegconn-userneedsadminaccess 69Unabletoclone:missingreadpermission 69Unabletopush:missingcreate-repopermission 70Unabletopush:missingwrite-refpermission 70Unabletopush:notenabledbyp4protect 71Unabletopushanewbranch:missingcreate-refpermission 71Unabletodeleteabranch:missingdelete-refpermission 72Unabletoforceapush:missingforce-pushpermission 73

Branchproblems 73

PushresultsinmessageaboutHEADrefnotexisting 73Cloneresultsin"remoteHEADreferstononexistentref" 74

SpecialGitcommands 75

Glossary 78License Statements 96

5

How to Use this GuideThisguidetellsyouhowtouseHelix4Git,whichaugmentsthefunctionalityoftheHelixVersioningEngine(alsoreferredtoastheHelixServer)tosupportGitclients.Itservicesrequestsfrommixedclients,thatis,both"classic"HelixServerclientsandGitclients,andstoresGitdatainGitreposthatresidewithinaclassicHelixServerdepot.

Tip n ForhelpconfiguringHelixServerforbuildingfrommixedclients,seeP4 Command Reference

underP4 Client,thesection"IncludingGraphDepotsandreposinyourclient".

n Forin-depthadminandusageinformationpertainingtotheHelixServer,see:

l Helix Versioning Engine Administrator Guide: Fundamentals

l Helix Versioning Engine User Guide

[email protected].

Other documentationSeehttps://www.perforce.com/support/self-service-resources/documentation.

Syntax conventionsHelixdocumentationusesthefollowingsyntaxconventionstodescribecommandlinesyntax.

Notation Meaningliteral Mustbeusedinthecommandexactlyasshown.

italics Aparameterforwhichyoumustsupplyspecificinformation.Forexample,foraserveridparameter,supplytheIDoftheserver.

[-f] Theenclosedelementsareoptional.Omitthebracketswhenyoucomposethecommand.

7

http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4guide/index.htmlmailto:[email protected]://www.perforce.com/support/self-service-resources/documentation

Syntax conventions

Notation Meaning

... n Repeatsasmuchasneeded:l alias-name[[$(arg1)...

[$(argn)]]=transformation

n Recursiveforalldirectorylevels:

l clone perforce:1666 //depot/main/p4... ~/local-repos/main

l p4 repos -e //gra.../rep...

element1|element2

Eitherelement1orelement2isrequired.

8

Whats new in this guide

Whats new in this guideThissectionprovidesasummarywithlinkstotopicsinthisreference.Foracompletelistofwhat'snewinthisrelease,seetheRelease Notes.

2018.1 release

Area Feature

One-waymirroringfromGitservers

Seetheupdatedstepthatmentions"AsthesystemusergitthatiscreatedduringconfigurationofHelixConnector,configurethewebhookformirroring"at:

n Step3at"GitHuborGitLabHTTP"onpage40

n Step8at"GitHuborGitLabSSH"onpage42

n Step3at"ConfigureGerritforHTTP"onpage45

n Step8at"ConfigureGerritforSSH"onpage47

GitLargeFileStorage(LFS)

AreplicacansyncLFSfilesfromgraphdepots.Toconfigurethissupport,seethenotemarked"Important"in"One-waymirroringfromGitservers"onpage39

p4helpongraphdepotsisalsoavailableinthisguide

See"GitConnectorCommands"onpage14

2017.2 release

New featuresn "HelixTeamHubconfiguration"onpage50

n "ConfiguringGitConnectortopollreposfromHelix4Git"onpage64

n "GitConnectorconfigurationforfail-overtoanotherGithost"onpage58

9

http://www.perforce.com/perforce/doc.current/user/relnotes.txt

OverviewBenefits:

n Flexibility:syncanycombinationofrepos,branches,tags,andSHA-1hashes

n Hybridsupport:youcansyncdatathatisamixofGitrepodataandclassicHelixServerdepotdata

n Supports"One-waymirroringfromGitservers"onpage39,suchasGitHub,GitLab,andGerritCodeReview

n Automation:pollingtoautomaticallytriggerabuilduponupdatestotheworkspace,andsupportforJenkins

n Visibility:listingofbuildingcontents

Thissolution:

n storesGitreposinoneormoredepotsoftypegraph

n servicesrequestsforthedatastoredintheGitrepos

n supportsLargeFileStorage(LFS)objectsandservicerequestsusingHTTPS

n enforcesaccesscontrolonGitreposthroughtheuseofpermissionsgrantedatdepot,repo,orbranchlevel

n supportsbothHTTPSandSSHremoteprotocols

n servicesrequestsfromGitclientsusingacombinationofcacheddataandrequeststotheHelixServer

n supportsclientsaccessingreposcontainingGitLargeFileStorage(LFS)objects(butnotoverSSH)

Architecture and components 11P4Jenkinssupport 12

Workflow 13One-timetasks 13Recurringtasks 13Gitclienttasks 14

Git Connector Commands 14

10

Architecture and components

Architecture and components

Helix4Gitconsistsoftwocomponents:

n HelixServer(orp4d),thetraditionalHelixVersioningEngineaugmentedforGitsupport

n TheGitConnector,whichactsasaGitservertoGitclients,suchasHelixTeamHub,GitLab,andGitHub.

GitusersuseaGitclienttopullfilesfromthegraphdepottomakemodificationsandthenpushthechangesbackintothegraphdepot.TheGitclientcommunicateswiththeHelixServerthroughtheGitConnector.

Insupportofadvancedworkflowsforblendedassets,suchastextandlargebinariesinbuildandtestautomation,youcanalsodirectlysyncandviewgraphdepotcontentthroughacommandlineclientintoasingleclassicHelixServerworkspace.

Note Toeditthegraphdepotfilesassociatedwithaclassicworkspace,youmustuseaGitclient.

Atypicalscenario:

1. AGituserpusheschangestotheGitConnector.

2. TheGitConnectorpushesthechangestotheHelixServer.

11

P4Jenkins support

3. Acontinuousintegration(CI)server,suchasP4Jenkins,detectschangesandrunsabuildusingoneworkspacethatcanincludemultipleGitreposandclassicdepotfiles.

P4Jenkins support 12

P4Jenkins supportYoucanconnecttheworkspacetoCItools,suchasP4Jenkins.TheadvantagesofusingtheP4PluginforJenkinsasthecontinuousintegrationserverinclude:

n Efficiency:beingabletosyncaSINGLEdepotoftypegraphthatcontainsMANYrepos

n Hybridsupport:thissingledepotisabletohavealsoclassicdepotfiles

n Flexibility:syncanycombinationofrepos,branches,tags,andSHA-1hashes

n Automation:pollingtoautomaticallytriggerabuilduponupdatestotheworkspace

n Visibility:listingofbuildingcontents

TolearnhowtousetheP4PluginforJenkins,seehttps://github.com/jenkinsci/p4-plugin/blob/master/GRAPH.md

12

https://github.com/jenkinsci/p4-plugin/blob/master/GRAPH.mdhttps://github.com/jenkinsci/p4-plugin/blob/master/GRAPH.md

Workflow

Workflow1. InstalltheGitConnector.

2. ConfiguretheGitConnector,includingHTTPSandSSHauthentication.

3. ConfiguretheHelixVersioningEnginetoworkwiththeGitConnector.Thisincludesdepot,repo,andpermissionsconfiguration.

4. Verifytheconfiguration.

5. Runp4 syncandasubsetofotherp4commandsagainstGitreposandclassicdepotfiles.

One-time tasks 13Recurring tasks 13Git client tasks 14

One-time tasksThefollowingtablesummarizesone-timetasks:

Task More informationInstalltheGitConnector. "InstalltheGitConnector"onpage18

ConfiguretheGitConnector.

ThisincludesconfiguringHTTPSandSSHauthentication.

"ConfiguretheGitConnector"onpage22

ConfiguretheHelixServertoworkwiththeGitConnector.

Thisincludesdepot,repo,andpermissionsconfiguration.

"PerformConnector-specificHelixServerconfigurations"onpage24

Setupusers. "SetupGituserstoworkwiththeGitConnector"onpage27

VerifytheGitConnectorconfiguration. "VerifytheGitConnectorconfiguration"onpage30

Recurring tasksThefollowingtablesummarizesrecurringtasks:

Task More informationCreateandviewgraphdepots. "Creategraphdepots"onpage32

13

Git client tasks

Task More informationCreate,view,anddeleteGitrepos. "Createandviewrepos"onpage33

Managepermissionsonarepoorgroupofrepos.

Youcangrant,revoke,andshowpermissions.

Permissionsapplyattheuserorgrouplevel.

"Manageaccesstographdepotsandrepos"onpage34

Setupclientworkspaces. "Setupclientworkspaces"onpage35

Runp4syncandasubsetofotherp4commandsagainstbothGitandclassicdepotdata.

"Syncfilesfromgraphdepots"onpage36

Troubleshoot. "Troubleshooting"onpage66

Git client tasksGitclientsmustperformacoupleoftaskstointeractwiththeGitConnector:

n ObtainSSHandHTTPSURLs.See"SetupGituserstoworkwiththeGitConnector"onpage27.

n GenerateSSHkeystobeaddedtotheGitConnector,iftheSSHkeysdonotalreadyexist.

Git Connector CommandsTogetcommand-linehelp:

gconn --help > gconn_help.txt

Commandusage:

gconn command [options...] [arguments...]

Note GCONN_CONFIGvariablewiththepathtoconfigurationfilemustbeset.

Options-h | --help Showthishelpmessage.

-V | --version Showversionandcopyrightinfomation.

14

Git Connector Commands

Options-M | --mirrorhooks [-n] [args]

Add/remove/listmirroredrepos.

arguments add AddnewmirroredrepotoHelix.Tomirror

reposwithrestrictedaccess,supplyaccesstokenorcredentialsinmirrorURL.

remove DisablemirroringforanexistingmirroredHelixrepo.

list ListallmirroredreposinHelix.

setremote

ChangetheremoteurlforarepoorsetofreposmirroredbyaGconninstance.ThefirstargumentismatchedagainsttheremoteurlforallreposmirroredbythisGconninstance.Thesecondargumentreplacesthefirstargumentintheremoteurlforallmatchedrepos.Thisallowsupatingtheremoteurlforaspecificrepoorforasetofreposmatchingthefirstargumentpattern.

-n Dryrun-onlysupportedby'setremote'.

fetch Updatethemirrorbyfetchingfromtheconfiguredupstream_url.

15

Git Connector Commands

Options

examples --mirrorhooks add repo/repoA http://github.com/my/repo

--mirrorhooks add repo/repoB http://gitlab-ci-token:[email protected]/my/secret/repo

--mirrorhooks remove repo/repoA

--mirrorhooks setremote http://github.com http://gitlab.com

--mirrorhooks setremote http://github.com/my/repoa http://gitlab.com/your/repob

--mirrorhooks setremote http://github.com/my/repoa http://user:[email protected]/your/repob

--mirrorhooks fetch repo/repoA --mirrorhooks list

Commandssync-ssh-keys Forceupdateofp4pubkeysfromHelix.

ThiscommandmustberunfromOSaccountoftheuserusedforSSHauthentication(usually'git').

poll-repos UpdategraphreposfromtheHelixCentralServer.ThiscommandwillapplyupdatesfromHelixtoeachrepospecifiedinacommaorspacedelimitedlistasthevalueintheExternalAddressfieldofaGconninstance'sserverspec.TheservernameofeachGitConnectorisrecordedintheGCONN_CONFIGfileunderthegconn.serverIdfield.Therepocachedirectorydoesneednotexist.

16

Installation and configurationThischapterdescribeshowtoinstallandconfiguretheGitConnector.Theinstallationrequiresoperatingsystem-specificpackages(see"Systemrequirements"below).

System requirements 17Install the Git Connector 18Upgrading Git Connector 20Upgradingtoversion2017.2fromthe2017.1patch 20Upgradinghelix-git-connectorthatispriortothe2017.1patch 21

Configure the Git Connector 22Perform Connector-specific Helix Server configurations 24Grantpermissions 25Creategraphdepots 26Createrepos 26Configureaclientworkspacetosyncrepos 26Syncarepo 27

Set up Git users to work with the Git Connector 27Prerequisite 27Authentication 27SSH 28HTTPS 30

Verify the Git Connector configuration 30Push, clone, and pull repos 30SSHsyntax 30HTTPSsyntax 31

System requirementsTheGitConnectorrequiresaninstallationofHelixVersioningEngine2017.1orlater.

Tip WerecommendthattheGitConnectorbeonamachinethatisseparatefromthemachinewiththeHelixServer.

TheGitConnectorisavailableintwodistributionpackageformats:Debian(.deb)forUbuntusystemsandRPM(.rpm)forCentOSandRedHatEnterpriseLinux(RHEL).YoucaninstalltheGitConnectoronthefollowingLinux(Intelx86_64)platforms:

n Ubuntu14.04LTS

n Ubuntu16.04LTS

17

Install the Git Connector

n CentOsorRedHat6.x

l notrecommendedbecauseitrequiresthatyoumanuallyinstallGitandHTTPS

l iftheoperatingsystemisCentOS6.9,Security-EnhancedLinux(SELinux)andtheiptablesuse-spaceapplicationmustallow:

l theGitservertocontactthehelix/gconnserviceonport443(theHTTPSport)

l gconntocommunicatewithp4diftheyarebothonthesamemachine

n CentOSorRedHat7.x

Note "One-waymirroringfromGitservers"onpage39isnotrecommendedwithCentos6.

SpaceandmemoryrequirementsdependonthesizeofyourGitreposandthenumberofconcurrentGitclients.

TheGitConnectorworkswithGitversion1.8.5orlater.IfthedistributionpackagecomeswithanearlierreleaseofGit,upgradetoasupportedversion.

Note IfyourGitclientsworkwithreposcontaininglargefilestorage(LFS)objects,installGitLFSandselectthefilestobetracked.Fordetails,seehttps://git-lfs.github.com.GitLFSrequiresHTTPS.

Warningn TheHelix4GitconfigurationprocessremovesanySSLcertificatesin/etc/apache2/ssl

beforegeneratingsnewSSLcertificates.Therefore,existingsites,suchasHelixSwarm,mightbedisabled.

n DonotaddcustomhooksintheGitConnectorbecausetheywillnotworkasexpected.However,theHelixVersioningEnginedoessupporttriggersfordepotsoftypegraph.Seehttps://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/scripting.triggers.graph.html.

Install the Git ConnectorInstallingtheGitConnectorrequiresthatyoucreateapackagerepositoryfile,importthepackagesigningkey,andinstallthepackage.

Beforeyoustarttheinstallation,verifythatyouhaveroot-levelaccesstothemachinethatwillhosttheGitConnector.

1. Configure the Helix Versioning Engine package repository.

Asroot,performthefollowingstepsbasedonyouroperatingsystem:

18

https://git-lfs.github.com/https://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/scripting.triggers.graph.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/scripting.triggers.graph.html

Install the Git Connector

a. For Ubuntu 14.04:

Createthefile/etc/apt/sources.list.d/perforce.listwiththefollowingcontent:

deb http://package.perforce.com/apt/ubuntu trusty release

b. For Ubuntu 16.06:

Createthefile/etc/apt/sources.list.d/perforce.listwiththefollowingcontent:

deb http://package.perforce.com/apt/ubuntu xenial release

c. For CentOS/RHEL 6.x:

Createthefile/etc/yum.repos.d/Perforce.repowiththefollowingcontent:

[perforce]

name=Perforce for CentOS $releasever - $basearch

baseurl=http://package.perforce.com/yum/rhel/6/x86_64/

enabled=1

gpgcheck=1

gpgkey=http://package.perforce.com/perforce.pubkey

d. For CentOS/RHEL 7.x:

Createthefile/etc/yum.repos.d/Perforce.repowiththefollowingcontent:

[perforce]

name=Perforce for CentOS $releasever - $basearch

baseurl=http://package.perforce.com/yum/rhel/7/x86_64/

enabled=1

gpgcheck=1

gpgkey=http://package.perforce.com/perforce.pubkey

19

Upgrading Git Connector

2. Import the Helix Versioning Engine package signing key.

Asroot,runthefollowingcommand:

a. For Ubuntu 14.04 and 16.04:

$ wget -qO - http://package.perforce.com/perforce.pubkey |

sudo apt-key add -

$ sudo apt-get update

b. For CentOS/RHEL 6.x and 7.x:

$ sudo rpm --import

http://package.perforce.com/perforce.pubkey

3. Install the Git Connector package.

Asroot,runoneofthefollowingcommands:

a. For Ubuntu 14.04 and 16.04:

$ sudo apt-get install helix-git-connector

b. For CentOS/RHEL 6.x and 7.x:

$ sudo yum install helix-git-connector

4. Follow the prompts.

5. Configure the Git Connector.See"UpgradingGitConnector"belowand"ConfiguretheGitConnector"onpage22.

Upgrading Git Connector

Upgrading to version 2017.2 from the 2017.1 patch 1. VerifytheGitConnectorserverid,which,forthisexample,ismy-gconn-centos6:

*p4 servers*

Theresponseissimilarto:

my-gconn-centos6 connector git-connector ' This GitConnector service was configured on [Tue Aug 29 10:21:30 PDT 2017] by user [super]

2. MakesurethatyouprovidethevalueoftheserveridwhenupgradingtheGitConnector:configure-git-connector.sh --upgrade --serverid my-gconn-centos6

Hereisanexample:

20

Upgrading helix-git-connector that is prior to the 2017.1 patch

sudo /opt/perforce/git-connector/bin/configure-git-connector.sh --

upgrade --serverid my-gconn-centos6

hostname: Unknown host

Summary of arguments passed:

...

GitConnector SSH system user [git]

Home directory for SSH system user [/home/git]

SSH key update interval [10]

Server ID [gconn-gconn-centos6]

GitConnector hostname [(not specified)]

For a list of other options, type Ctrl-C to exit, and then run:

$ sudo /opt/perforce/git-connector/bin/configure-git-connector.sh --help

...

Would you like to perform the upgrade of this GitConnector instance? [no]:

yes

...

Moving existing configuration file to

/opt/perforce/git-connector/gconn.conf.bak

Writing GitConnector configuration file

This GitConnector instance has been successfully upgraded.

Upgrading helix-git-connector that is prior to the 2017.1 patchIfyouhaveaversionoftheGitConnectorthatispriortothe2017.1Julypatch,andyouwanttouseGerrit,upgradethepackageandre-runthepackageconfigurationscript.

21

Configure the Git Connector

1. Runasroot:

Ubuntu CentOS$ sudo apt-get update

$ sudo apt-get install helix-git-connector

# yum install helix-git-connector

2. Optionally,ifyourHelixServerconfigurationhaschanged,oryouencounterproblems,runtheconfigurationscript:

$ sudo /opt/perforce/git-connector/bin/configure-git-connector.sh

Theconfigurationscript:

n warnsyouabouttheexistingconfigurationfile

n promptsyouforP4PORT,superuser'saccountname,andsuperuserpassword

n updatestheHTTPSandSSHauthenticationconfigurations

Configure the Git Connector1. As root,runthefollowingconfigurationscriptininteractivemode:

$ sudo /opt/perforce/git-connector/bin/configure-git-connector.sh

Ininteractivemode,theconfigurationscriptdisplaysthefollowingsummaryofsettings.Somesettingshaveadefaultvalue.Othersettingsrequirethatyouspecifyavalueduringtheconfiguration.

n Helix Server P4PORT:Thehost(nameorIPaddress)andportfortheHelixServer,inthefollowingformat:host:port.

n Helix Server super-user:ThenameofanexistingHelixServeruserwithsuperlevelprivileges.Thissuper-userisusedforalltasksrelatedtotheHelixServer,suchascreatingusersandgroupsandgrantingpermissions.

n Helix Server super-user password:ThepasswordfortheexistingHelixServersuper-user.

n New Graph Depot name:TheHelixServerinstallationautomaticallycreatesadefaultdepotoftypegraphnamedrepo.Duringtheconfiguration,youcancreateanadditionalgraphdepot.

AdepotoftypegraphisacontainerforGitrepos.

Adepotnamemuststartwithaletteroranumber.

22

Configure the Git Connector

n GitConnector user password:Bydefault,theGitConnectorconfigurationcreatesaHelixServerusercalledgconn-user.ThisuserperformstheHelixServerrequests.Onlyadminsshouldknowandsetthispassword.

Note Ifyouchangethegconn-userHelixServerpassword,youneedtoresetthepasswordoneachGitConnectorbyrunningthehelperscript:/opt/perforce/git-connector/bin/login-gconn-user.sh.

n Configure HTTPS?:OptiontouseHTTPSasauthenticationmethod.HTTPSisrequiredifyouuseGitLFS.

Tip Re-runningconfigure-git-connector.shandchoosingNowhenaskedifyouwanttoconfigureHTTPSafterhavingchosenYespreviously,doesnotchangealreadyconfiguredhttps.

n Configure SSH?:OptiontouseSSHasauthenticationmethod.

n GitConnector SSH system user:ThenameoftheSSHsystemusertoconnecttotheGitConnector.Bydefault,thisisgit.

n Home directory for SSH system user:ThehomedirectoryfortheSSHsystemuser.Bydefault,thisis/home/git.

n SSH key update interval:HowoftentheSSHkeysareupdated.

Tip Wait10minutesforthekeystoupdate.Otherwise,theGitConnectorwillnothavetheupdatedSSHkeysinthelistofauthorizedkeys,andyouwillnotbeabletoconnect.

n Server ID:Thehostnameoftheserver.

23

Perform Connector-specific Helix Server configurations

2. Provide information to the configuration script.

Afterthesummary,theconfigurationscriptpromptsyouforinformationontheHelixServerP4PORT,theHelixServersuper-usersnameandpassword,whetheryouwanttocreateanotherdepotoftypegraph,andwhetheryouwanttoconfigureHTTPSorSSH.

Ateachprompt,youcanaccepttheproposeddefaultvaluebypressingEnter,oryoucanspecifyyourownvalue.Ifneeded,youcanalsosetvalueswithacommandlineargument.Forexample,tospecifyP4PORT andasuper-username:

$ sudo /opt/perforce/git-connector/bin/configure-git-

connector.sh --p4port=ssl:IP address:1666 --super=name

Afteryouanswertheprompts,thescriptcreatestheconfigurationfileaccordingtoyourchoices.Asitruns,thescriptdisplaysinformationabouttheconfigurationstakingplace.Thescriptmightpromptyouformoreinput.Forexample,ifyouoptedforHTTPSsupportandApachecomponentsarealreadypresentonyourserver.

Toseeallpossibleconfigurationoptions,runthecommand:

$ sudo /opt/perforce/git-connector/bin/configure-git-

connector.sh --help

Thisishelpfulifyoudonotwanttousethedefaultconfigurations.Forexample,theconfigurationscriptdoesnotpromptyouforthenameoftheSSHuserorthepathtothehomedirectoryofthesystemuserbecauseitusesdefaultvalues.Ifyouwanttooverwritethesevalues,youneedtopassintherespectiveparameterandargument.

3. Whentheconfigurationscripthasfinishedrunning,readthedetailstoseeifanythingstillneedstobedone.

Perform Connector-specific Helix Server configurationsAfterinstallingandconfiguringtheGitConnector,configuretheHelixServertoworkwiththeGitConnector.Tasksinclude:

n grantingrelevantpermissions

n creatingreposthatbelongtothegraphdepotsyoucreatedduringtheinstallation

n grantinguserspermissiontopushrepostotheHelixServer

n configuringaclientmappingtosyncrepos

n syncingarepo,providedtherepohasalreadybeenpushedtotheHelixServer

Formoreinformationonp4commands,seetheP4 Command Referenceorrunthep4 --helpcommand.

Grant permissions 25Create graph depots 26Create repos 26Configure a client workspace to sync repos 26

24

http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Grant permissions

Sync a repo 27

Grant permissionsTheGitConnectorauthenticatesGitusersthroughHTTPorSSH(see"SetupGituserstoworkwiththeGitConnector"onpage27)andallowsthemtoaccessresourcesbypull,push,andclonetransactionsthroughuserorgrouppermissionsintheHelixServer.

Important Becausethegconn-userperformsallHelixServerrequestsrequiredbytheGitConnector,thegconn-usermusthaveanentryintheprotectionstablewithwritepermissionandhavebeengrantedadminpermissionforallgraphdepotsmanuallycreatedaftertheinstallation.

FordetailsonHelixServerpermissions,seeSecuringtheServerinHelix Versioning Engine Administrator Guide: Fundamentals.Fordetailsonthep4 protectcommand,seep4protectintheP4 Command Reference.

Fordetailsonaccesscontrolpoliciesrelatedtographdepots,see"Manageaccesstographdepotsandrepos"onpage34.

Performthefollowingstepstogranttherequiredpermissions:

1. Addtheusergconn-usertotheprotectionstablewithwritepermission.NotethatifyouencounterareferencetoGConn P4 user,thisisthegconn-useruser.

Runthefollowingcommandtoopentheprotectionstableintextform:

$ p4 protect

AddthefollowinglinetotheProtectionsfield:

$ write user gconn-user * //...

Savethespec.

2. Foranydepotoftypegraphthatyoucreateinadditiontotheonesalreadycreatedduringtheinstallation,grantthegconn-useruseradminpermission:

$ p4 grant-permission -u gconn-user -p admin -d

graphDepotName

3. Asasuperuser,grantadminpermissiontoanotherusersothatthisusercanmanagepermissionsasrequired:

$ p4 grant-permission -u username -p admin -d graphDepotName

25

https://www.perforce.com/perforce/doc.current/manuals/p4sag/chapter.security.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Create graph depots

4. Grantuserspermissiontocreatereposforspecificgraphdepots:

$ p4 grant-permission -p create-repo -d graphDepotName -u

username

5. Grantuserspermissiontopushrepostoagraphdepot:

$ p4 grant-permission -p write-all -u username -d

graphDepotName

Tip Insteadofgrantingpermissionstosingleusers,youcancreategroups,assignuserstogroups,andsetpermissionsthatareappropriateforthatparticulargroup.SeeGrantingaccesstogroupsofusersinHelix Versioning Engine Administrator Guide: Fundamentals.

Create graph depotsTheHelixServerinstallationcreatesadefaultdepotoftypegraphcalledrepo.Ifyouneedtomanuallyaddadditionalgraphdepots,see"Creategraphdepots"onpage32.

Foranyadditionalgraphdepotsthatyoucreate,grantadminpermissiontotheusergconn-user(fordetails,seeGrantingpermissions).

Toviewalistofexistingdepots,runthep4 depotscommand.SeetheP4 Command Reference.

Create reposTocreateanewrepostoredinanexistinggraphdepot,runthefollowingcommand:

$ p4 repo //graphDepotName/repo1

Formoreinformationoncreatingrepos,see"Createandviewrepos"onpage33.

Configure a client workspace to sync reposAclientworkspaceisasetofdirectoriesonausersmachinethatmirrorsasubsetofthefilesinthedepot.Thisviewdefineswhichdepotsyoucansynctoyourclientworkspace.Classicdepotsaremappedbydefault,buttobeabletosyncreposfromagraphdepot,youneedtomanuallyedittheclientworkspacespecificationbynotingtherequiredmappings.

Formoreinformationonsettingupclients,see"Setupclientworkspaces"onpage35.

1. Runthefollowingcommandtocreateadepotclientspecificationanditsview:

$ p4 client clientName

26

http://www.perforce.com/perforce/doc.current/manuals/p4sag/chapter.security.html#protections.groupshttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Sync a repo

2. Edittheworkspaceviewtomeetyourrequirements.

Forexample,tomapagraphdepotcalledgraphDepotthatincludesarepocalledrepo1,themappingcouldlooklikethefollowing,whereworkspaceisthededicateddirectoryontheclientusersmachinethatcontainsallfileslocatedinthegraphdepot:

//graphDepot/repo1/... //workspace/graphDepot/repo1/...

Sync a repoAftersettinguptheclientworkspace,youcanupdateittoreflectthelatestcontentsofthegraphdepot.

TosyncarepoaftertherepohasbeenpushedtotheHelixServer,runthecommand:

$ p4 sync //graphDepotName/repoName/...

Formoreinformationonthep4 synccommand,seep4syncinP4 Command Reference.

Set up Git users to work with the Git Connector

Prerequisite

Important YourGitusersneedtwotypesofpermissions:

n thoseassociatedwiththe"classic"HelixServerp4protectcommand

n thoseassociatedwiththe"graphdepot"p4grant-permissioncommand

FordetailsonHelixServerpermissions,seeSecuringtheServerinHelix Versioning Engine Administrator Guide: Fundamentals.Fordetailsonthep4 protectcommand,seep4protectintheP4 Command Reference.

AuthenticationDependingonthenetworkprotocolyouselectedduringtheGitConnectorconfiguration,younowneedtosetupeitherSSHorHTTPSauthenticationforeachuserandfromeachcomputerusedtoclone,push,andpullGitrepos.

Whenthissetupiscomplete,provideSSHorHTTPSURLstoGitclientusers.TheseURLsincludetheIPaddressorhostnameoftheGitConnectorandthepathtotherespectiverepo,whichconsistsofthegraphdepotnameandthereponame.TheURLshavethefollowingformat:

27

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_sync.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_protect.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_grant-permission.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4sag/chapter.security.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

SSH

n SSH:

$ git command git@ConnectorHost:graphDepotName/repoName

n HTTPS:

$ git command

https://username@ConnectorHost/graphDepotName/repoName

SSHTheSSHkeyconsistsofapublic/privatekeypairthatyoucreateforeachuseroneachcomputerusedasaGitclient.GituserswhoalreadyhaveanSSHkeycansendthepublickeytotheiradministratorforfurtherhandling.

WhenyouhavetheSSHkey,youcansharethepublickeywiththeHelixServermachineandthenverifythekeyintheGitConnectorserver.Bydefault,ittakes10minutesfortheSSHkeysharedwiththeHelixServertobeauthorizedintheGitConnectorserver,soyouneedtowaitbeforeyouproceedtotheverificationstep.

Note HelixServeruserswhohave,ataminimum,thelistaccesstoafilenameintheprotectionstablecanaddtheirownpublicSSHkeystotheHelixServer.Forexample:

p4 pubkey -i -s scopeName < my_id_rsa.pub

AHelixServeruserwiththeaccesslevelofsuperoradmincanaddakeyforanotheruserbyspecifyingthe(-u)option.Forexample:

p4 pubkey -i -s scopeName -u bruno < bruno_id_rsa.pub

SeePrerequisitesforausertouploadakeyinP4 Command Reference.

Tip Ifyouhaveseveralpublickeys,youcandefineascopeforeachkeytobeabletoquicklydistinguishbetweenthem.Thisisusefulifyouneedtodeleteakey.Togetalistofkeysalongwiththeirscope,runthep4 -ztag pubkeyscommand.Forexamples,seehttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_pubkeys.html.

1. TocreatetheSSHkey,runthefollowingcommandandfollowtheprompts:

$ ssh-keygen -t rsa

28

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_pubkey.html#p4_pubkey.description.upload-prerequisitehttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_pubkeys.html

SSH

2. Letusassume:

n YouareauserwithadminorsuperuserprivilegeontheHelixserver,butyouareNOTloggedintoHelixserverasanadminorsuperuserfromthehostrunningthecommand

n P4PORTissetinyourenvironment

n ausernamedbruno,P4USER=bruno,hasemailedhisid_rsa.pubfiletoyouandthatfileisstoredin/drive/userA/id_rsa.pub

ToaddthekeytotheHelixServermachine,yourunthecommand:

$ p4 -u admin pubkey -u bruno -s scopeName -i <

/drive/userA/id_rsa.pub

However,ifP4PORTisNOTset,includetheservernameandportnumber:

$ p4 -p helixserver:1666 -u admin pubkey -u bruno -s

scopeName -i < /drive/userA/id_rsa.pub

Note Userswithoutadminpermissionneedtorunthiscommandwithoutthe-uoption:

$ p4 pubkey -i -s scopeName < ~/.ssh/id_rsa.pub

Otherwise,theyreceivethefollowingerrormessage:

You don't have permission for this operation.

3. Wait10minutesforthekeystoupdate.Otherwise,theGitConnectorwillnothavetheupdatedSSHkeysinthelistofauthorizedkeys,andyouwillnotbeabletoconnect.

4. HaveGitclientusersrunthefollowingcommandtoverifythattheycansuccessfullyconnecttotheGitConnector.Thiscommandissimilartothep4 infocommandinthatitdisplaysinformationabouttheinstalledapplications.

$ git clone git@ConnectorHost:@info

Note Ignorethefollowingmessage:

fatal: Could not read from remote repository. Please make sure you

have the correct access rights and the repository exists.

Ifyouseep4 infooutput,thecommandwassuccessful.

IfyouarepromptedfortheGitpassword,thisindicatesanissuewiththeSSHsetup.See"Troubleshooting"onpage66.

29

HTTPS

HTTPSUsingHTTPSrequiresthatyouhaveauseraccountandpasswordfortheHelixServer.Youneedtoenterthesecredentialswhenprompted,whichiseverytimeyoutrytoconnecttotheGitConnectortopush,pull,orclone.

n ToturnoffSSLverificationinGit,runoneofthefollowingcommands:

$ export GIT_SSL_NO_VERIFY=true

$ git config --global http.sslVerify false

Verify the Git Connector configurationYoualreadyverifiedthattheSSHkeywasaddedtothelistofauthorizedkeysintheGitConnectorserveraspartof"SetupGituserstoworkwiththeGitConnector"onpage27.Inaddition,youcanverifytheGitConnectorversioninstalledbyhavingGitusersrunthefollowingcommandontheGitclientmachine:

When using SSH:

$ git clone git@ConnectorHost:@info

When using HTTPS:

$ git clone https://ConnectorHost/@info

Push, clone, and pull repos AfteryouhaveinstalledandconfiguredtheGitConnectorandhaveverifiedtheinstallation,youcanstartpushingreposfromaGitclienttoadepotoftypegraphintheHelixServer.YoucanthenclonethoserepostootherGitclientsasneededor,ifyoualreadyhavetherepoonyourGitclient,pullchangesfromtheHelixServer.

AnyGituserwithwrite-allpermissionfortherespectivedepotsandreposintheHelixServercanpush,clone,andpullthroughtheGitConnector.Fordetails,seeGrantingpermissions.

SSH syntax 30HTTPS syntax 31

SSH syntaxTopusharepointotheHelixServerusingSSH,runthefollowingcommand:

$ git push git@ConnectorHost:graphDepotName/repoName

ToclonearepofromtheHelixServerusingSSH,runthefollowingcommand:

30

HTTPS syntax

$ git clone git@ConnectorHost:graphDepotName/repoName

TopullarepofromtheHelixServerusingSSH,runthefollowingcommand:

$ git pull git@ConnectorHost:graphDepotName/repoName

HTTPS syntaxTopusharepointotheHelixServerusingHTTPS,runthefollowingcommand:

$ git push https://ConnectorHost/graphDepotName/repoName

ToclonearepofromtheHelixServerusingHTTPS,runthefollowingcommand:

$ git clone https://ConnectorHost/graphDepotName/repoName

TopullarepofromtheHelixServerusingHTTPS,runthefollowingcommand:

$ git pull https://ConnectorHost/graphDepotName/repoName

31

Depots and reposAllversionedfilesthatusersworkwithresideinasharedrepositorycalledadepot.Bydefault,adepotnameddepotoftypelocaliscreatedintheHelixVersioningEngine(theHelixServer)whentheserverstartsup.Thiskindofdepotisalsoreferredtoasaclassicdepot.Inaddition,theHelixServerinstallationcreatesadefaultgraphdepotnamedrepo.AgraphdepotisadepotoftypegraphthatservesasacontainerforGitrepos.

Create graph depots 32Create and view repos 33Specifyadefaultbranch 34

Manage access to graph depots and repos 34Set up client workspaces 35Sync files from graph depots 36Syncusinganautomaticlabel 37

Create graph depotsAgraphdepotcanholdzeroormorerepositories.Thereisnoupperlimittothenumberofreposthatyoucanstoreinasinglegraphdepot.Youcanalsomanuallycreateadditionalgraphdepotsatanytimebyrunningthep4 depotcommand.Thiscommandisusedtocreateanytypeofdepot.Fordetails,seeP4 Command Referenceorrunthep4 helpcommand.

Makesuretograntadminpermissiontothegconn-useronanymanuallycreatedgraphdepots.Forinstructions,seeGrantingpermissions.

Youcanviewalistofthegraphdepotsonyourserverbyrunningthep4 depotscommand.withthe--depot-type=graphoption,asfollows:

$ p4 depots --depot-type=graph

or(shorter):

$ p4 depots -t graph

Whenyoucreateanewdepot(ofanytype),theresultingformthatopensiscalledthedepotspec.Thedepotspecforagraphdepot:

n givesthegraphdepotaname

n establishesanownerforthedepot

Theownerhascertainprivilegesforallreposinagraphdepotandautomaticallyacquiresdepot-wideadminprivileges.

n definesastoragelocationforthearchivesandGitLFSfilesforallreposinagraphdepot

Agraphdepotdoesnotusethep4 protectmechanismatthefilelevel.Instead,agraphdepotsupportstheGitmodelwithasetofpermissionsforanentirerepooffiles.Fordetails,seeManagingaccesscontroltographdepotsandrepos.

32

http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Create and view repos

1. Tocreateanewgraphdepot,runthefollowingcommand:

$ p4 depot -t graph graphDepotName

2. Edittheresultingspecasneeded.

Forinformationontheavailableformfields,seep4depotinP4 Command Reference.

Create and view reposSimilartothedepotspec,eachGitrepostoredintheHelixServerisrepresentedbyarepospec.Youcancreate,update,anddeleterepospecsbyrunningthep4 repocommand.

Note Helix4Gitsupportsamaximumof10reposperlicense.Toobtainmorelicenses,pleasecontactyourPerforceSalesrepresentative.

Eachrepohasanowner(auseroragroup).Bydefault,thisistheuserwhocreatestherepo.Theownerautomaticallyacquiresrepo-wideadminprivilegesandisresponsibleformanagingaccesscontrolsforthatrepo.

Inaddition,therepospecincludesthereponameandinformationonwhentherepowascreatedaswellasthetimeanddateofthelastpush.Thespecalsoletsyouspecify:

n adescriptionoftheremoteserver

n adefaultbranchtoclonefrom

Ifyoudonotspecifyadefaultbranchhere,thedefaultbranchisrefs/heads/master.Ifyourprojectusesanothername,see"Specifyadefaultbranch"onthefacingpage.

n theupstreamURLthattherepoismirroredfrom

TheMirroredFromfieldisupdatedautomaticallyduringmirroringconfiguration.Fordetails,seethechapter"One-waymirroringfromGitservers"onpage39.

Itispossibletoenableautomaticcreationofarepowhenyouusethegit pushcommandtopushanewrepointotheHelixServer.Youconfigurethisbehaviorwiththep4 grant-permissioncommand.Fordetails,see"Manageaccesstographdepotsandrepos"onthefacingpageandp4grant-permissioninP4 Command Reference.

YoucanviewalistoftheGitreposonyourserverbyrunnnigthep4 reposcommand.Similarly,Gituserscanrunthefollowingcommandtoviewalistofrepos:

$ git clone git@ConnectorHost:@list

1. TocreateanewGitrepoinanexistinggraphdepot,runthefollowingcommand:

$ p4 repo //graphDepotName/repoName

2. Edittheresultingspecasneeded.

33

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_depot.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Specify a default branch

Formoreinformation,seep4repoinP4 Command Reference.

Specify a default branch 34

Specify a default branchIfyourprojectusesanameotherthanmasterasthedefaultbranchname,makesuretospecifythisnameintheDefaultBranchfieldoftherepospecasafullGitref,suchasrefs/heads/main.Otherwise,ifthisfieldisleftblank,theGitConnectorassumesthatyourdefaultbranchtocloneismaster.Thiswouldmeanthatyouneedto:

n addthebranchnametotheGitcommandeverytimeyoupushto,clone,orcheckoutthebranch.

n manuallycheckoutthebranchafteryoucloneit.

Tomakeyourworkeasier,specifyadefaultbranch.Forexample,tomakemainthedefaultbranch,youneedtoaddthefollowinglinetotherepospec:

$ DefaultBranch: refs/heads/main

SettingtheDefaultBranchfieldintherepospecsimplifiespushingandcloningbranches.

Inaddition,youcanpush:

n asinglebranchbyspecifyingthebranchname,whichcreatesarepowithonlythatbranch:

$ git push git@ConnectorHost:graphDepotName/repoName

branchName

n allbranchesbypassinginthe--alloption,whichcreatesarepowithallbranches:

$ git push git@ConnectorHost:graphDepotName/repoName --all

n allbranchesandGittagsbypassinginthe"*:*"option,whichcreatesarepowithallbranchesandGittags.

$ git push git@ConnectorHost:graphDepotName/repoName "*:*"

Manage access to graph depots and reposWiththep4 grant-permissioncommand,youcancontrolaccessrightsofusersandgroupstographdepotsandtheirunderlyingrepos.Thisincludespermissionsto:

n create,delete,andviewrepos

n update,force-push,delete,andcreatebranchesandbranchreferences

n writetospecificfilesonly

Thisallowsforscenarioswhereausercanclonearepobutmayonlypushchangestoasubsetofthefilesinthatrepo.

34

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_repo.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Set up client workspaces

n delegatetheadministrationofauthorizationstotheownerofadepotorrepo

Inmostcases,delegatingauthorizationmanagementatthegraphdepotlevelshouldsufficebecauserelatedrepostypicallyresideinthesamegraphdepot.However,ifneeded,repoownerscangrantandrevokepermissionsfortheirrepos.

Forexample,tograntuserbrunopermissiontoreadandupdatefilesingraphdepotgraphDepot,youcanrunthefollowingcommand:

$ p4 grant-permission -d graphDepot -u bruno -p write-all

Tolimitthispermissiontoreporepo1,whichresidesindepotgraphDepot,youcanrunthefollowingcommand:

$ p4 grant-permission -n //graphDepot/repo1 -u bruno -p write-all

Bydefault,thefollowingusershavepermissiontorunthep4 grant-permissioncommand:

n Theownerofthegraphdepotorrepo

n Thesuperuseruserforallgraphdepots

n adminusersforaparticulargraphdepotorrepo

Youcanviewaccesscontrolsbyrunningthep4 show-permissioncommand.Torevokeaccesscontrols,youcanrunthep4 revoke-permissioncommand.

Forinitialsetupinstructions,seeGrantingpermissions.

Foradetailedlistofpermissionsandtheirdescription,seep4grant-permissioninP4 Command Reference.

Set up client workspacesAclientworkspaceisasetofdirectoriesonausersmachinethatmirrorsasubsetofthefilesinthedepot.Moreprecisely,itisanamedmappingofdepotfilestoworkspacefiles.Theworkspaceviewdefineswhichdepotsyoucansynctoyourclientworkspace.

Aviewconsistsofmappings,oneperline.Theleft-handsideofthemappingspecifiesthedepotfilesandtheright-handsidethelocationintheworkspacewherethedepotfilesresidewhentheyareretrievedfromthedepot.

Whenyoucreateaclientworkspace,aclassicdepotismappedtoyourworkspacebydefault.However,adepotoftypegraphrequiresthatyoumanuallyconfigurethemappingbyeditingtheviewfieldintheclientworkspacespecification.Youcanalsoeditthespectoviewonlyaportionofadepotortochangethecorrespondencebetweendepotandworkspacelocations.

Inthefollowingexample,agraphdepotcalledgraphDepotincludesarepositorycalledrepo1.Itismappedtoadedicatedfoldercalledworkspacesuchthatallfileslocatedinthe//graphDepot/repo1directoryontheHelixServerappearinthe//workspace/graphDepot/repo1directoryonthemachinewheretheclientworkspaceresides.

//graphDepot/repo1/... //workspace/graphDepot/repo1/...

35

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Sync files from graph depots

Foradvancedworkflows,youcouldalsohaveamixedworkspacetoaccommodatethemappingofbothaclassicdepotandagraphdepot.Inthiscase,yourmappingcouldlooklikethis:

//graphDepot/repo1/... //mixed-client/graphDepot/repo1...

//depot1/moduleA/... //mixed-client/depot1/moduleA/...

Formoreinformationonmixedclientworkspaces,seeIncludingGraphDepotsandreposinyourclientinP4 Command Reference.

Formoreinformationonconfiguringworkspaceviews,seeConfigureworkspaceviewsinHelix Versioning Engine User Guide.

1. Tocreateadepotclientspecificationanditsview,runthefollowingcommand:

$ p4 client clientName

2. Edittheworkspaceviewtomeetyourrequirements.

Sync files from graph depotsYoucansyncanentiregraphdepotoroneormorerepostoaclientworkspacewithappropriatemappingsusingthep4 synccommand.Whensyncinginformationfromagraphdepot,thiscommandcanonlytakeonalimitednumberofoptions.

Bydefault,ifyoudonotspecifyabranch,p4 syncsyncsthemasterbranchoftherepo,unlesstheDefaultBranchfieldintherepospecspecifiesadifferentbranch(formoreinformationonspecifyingadefaultbranch,see"Specifyadefaultbranch"onpage34).Youcanalsoappendthebranchnametothecommandtosyncadifferentbranch,asfollows:

$ p4 sync branchName

Inaddition,youcansync:

n aGitcommitassociatedwithaSHA-1hashkey

n aparticularreferenceorcommitofarepo

n reposassociatedwithaspecificlabel

n repos/filescontainingaHelixServerwildcard

Notethatitisnotpossibletosyncindividualfileswiththep4 synccommand.YoucanonlygaincontrolofindividualfilesifyouspecifythemintheViewfieldoftheclientworkspacespecification.Otherwise,thewholerepoissynced,evenifyouspecifyafileinthecommandline.

Fordetailsandalistofexamples,seeWorkingwithadepotoftypegraphinP4 Command Reference.

Sync using an automatic label 37

36

https://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html#CmdRef/p4_client.html#Including_Graph_Depots_repos_in_your_clienthttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4guide/index.html#P4Guide/configuration.workspace_view.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4guide/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4guide/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html#CmdRef/p4_sync.html#Working_with_a_depot_of_type_graphhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Sync using an automatic label

Sync using an automatic labelHelixServersautomaticlabelfeatureenablesyoutospecifywhichreposyouwanttosyncwithwhichbranches,tags,orcommits.Thisenablesyoutosynctomultiplerepos,notallofwhichareatthesamebranch,tag,orcommit.

ThismightbeusefulwhenyouarebuildingaGitprojectthatisdependentonotherprojectsthatareataparticularreleaseversion,tag,orcommit(SHA-1).Innon-HelixServerGitsolutions,themanifestfiletraditionallyperformsthisfunction.

Note Tosyncmorenarrowlythanattherepolevel,usetheViewfieldintheclient(workspace)specification.Seethetopicp4clientinP4 Command Reference.

TouseautomaticlabelswithGitrepos,youeditthelabelspecification(spec)byissuingthep4 labelcommand.Inparticular,youedittwofields:RevisionandView:

n TheRevisionfieldmustalwaysbesetto"#head"whenusingautomaticlabelswithGitrepodata.

n TheViewfieldcontentsvaryaccordingtowhatyouwanttosyncto.

Withthefollowinglabelspecsettings,HelixServersyncs:

n thecollectionofreposunderdepot//androidtotagandroid-7.1.1_r23

n thecollectionofreposunder//android/platform/buildtobranchmaster

n therepo//android/platform/build/katitocommitSHA-1341a2ceccb836ab23f92c0ba96d0a0e73142576

# A Perforce Label Specification.

#

# Label: release1_build

# Update: The date this specification was last modified.

# Access: The date of the last 'labelsync' on this label.

# Owner: bruno

# Options: Label update options: [un]locked, [no]autoreload.

# Revision: "#head"

# View: Lines to select depot files for the label.

#

# Use 'p4 help label' to see more about label views.

Label: release1_build

Owner: bruno

37

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_client.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Sync using an automatic label

Description:

Created by bruno.

Options: unlocked noautoreload

Revision: "#head"

# View: Lines to select depot files for the label.

View:

//android/@refs/tags/android-7.1.1_r23

//android/platform/build/@master

//android/platform/build/kati/@341a2ceccb836ab23f92c0ba96d0a0e73142576

Formoreinformationonautomaticlabels,seethechapterLabelsinHelix Versioning Engine User Guide.

38

https://www.perforce.com/perforce/doc.current/manuals/p4guide/chapter.labels.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4guide/index.html

One-way mirroring from Git serversHelix4Gitcanduplicate("mirror")commitsfromaGitrepomanagedbyoneofthefollowingGitservers:

n GitHub

n GitLab(CommunityEditionorEnterpriseEdition)

n GerritCodeReview

n HelixTeamHub

AtypicalusecaseformirroringoneormoreexternalGitreposintoHelixistoenableasingleinstanceofaCItool,suchasJenkins,tobuildacomplexjobthatsyncscontentsfrombothclassicHelixandGitrepos.

Themirroringisone-way:fromtheGitserverintoHelix.

Tip graph-push-committriggersaresupportedwithmirroring.SeetheHelix Versioning Engine Administrator Guide: Fundamentalschapteron"Usingtriggerstocustomizebehavior".

You,thesystemadministratorforHelixandtheGitserver,configureawebhookintheGitserverandtheGitConnectorserver,whichenablesthisflow:

1. AGituserpushesabranchtotheGitserver.

2. TheexternalrepointheGitserverreceivesacommitofaGitrepoortag,whichfiresthewebhook.

3. TheGitConnectorreceivesthewebhookmessageandfetchesthecommitfromtheGitserverrepothatisthesourceformirroring.

4. TheHelixServerreceivestheupdatefromtheGitConnector.

5. Optionally,aCItool,suchasJenkins,pollsonaHelixworkspacetodetectchangesacrossmultiplereposandperformsabuild.

Important IfyouwanttouseGitLargeFileStorage(LFS)inyourone-waymirroring,astherootuserontheGitConnectorserver,installthegit-lfspackageforyouroperatingsystemfromhttps://github.com/git-lfs/git-lfs/releases/tag/v2.3.4.ThisisanoptionforGitHub,GitLab,andGerrit.

GitHub or GitLab configuration 40GitHuborGitLabHTTP 40GitHuborGitLabSSH 42

Gerrit configuration 44SystemrequirementswithGerrit 44Nextstep 44Installationofthemirrorhooks 45

39

https://github.com/https://about.gitlab.com/https://www.gerritcodereview.com/https://helixteamhub.cloud/docs/user/https://www.perforce.com/perforce/doc.current/manuals/p4sag/https://www.perforce.com/perforce/doc.current/manuals/p4sag/https://git-lfs.github.com/https://github.com/git-lfs/git-lfs/releases/tag/v2.3.4

GitHub or GitLab configuration

ConfigureGerritforHTTP 45ConfigureGerritforSSH 47Testingthemirrorhook 49TroubleshootingGerritone-waymirroring 49

Helix TeamHub configuration 50Overview 50Systemrequirements 51InstallationofHelixTeamHubOn-Premise 51Nextstep 51HelixTeamHubHTTP 52HelixTeamHubSSH 55

Git Connector configuration for fail-over to another Git host 58Procedure 59Example 60Effect 62Command-lineHelp 62NextSteps 62

GitHub or GitLab configuration"GitHuborGitLabHTTP"below

"GitHuborGitLabSSH"onpage42

GitHub or GitLab HTTP

Important n ThetargetrepomustNOTalreadyexistinHelixServer.

n Thesourcerepomustnotbeempty.

Tip Iftherepoisprivateorinternal,considercreatinganpersonalaccesstoken:

n ForGitHub-Creatingapersonalaccesstokenforthecommandline-https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

n ForGitLab-Personalaccesstokens-https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html

40

https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/https://docs.gitlab.com/ce/user/profile/personal_access_tokens.htmlhttps://docs.gitlab.com/ce/user/profile/personal_access_tokens.html

GitHub or GitLab HTTP

On the Git Connector server1. LoginasthegitOSuserortheuseryouspecifiedwhenconfiguringtheGitConnector.

2. Configurethewebhookformirroring:

Tip CopytheURLfromyourproject'sHTTPdrop-downbox.

a. SettheenvironmentvariableGCONN_CONFIGtotheabsolutepathtothegconn.conffile:export GCONN_CONFIG=/opt/perforce/git-connector/gconn.conf

b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName https://access-token:[email protected]/project/repoName.git

whereaccess-token:secretrepresentsyourpersonalaccesstokenforGitHuborGitLab.

3. Savethesecrettokenthatthe--mirrorhookscommandgenerates,whichisnotrelatedtothepersonalaccesstokenforGitHuborGitLab.

Tip Thesecrettokenisalsostoredin/opt/perforce/git-connector/repos/graphDepotName/repoName.git/.mirror.config

Mirror a repo over HTTP1. GotothehooksURL,whichmightresemble

https://GitHost/project/repo/hooksandrepresentsthewebhookURLforyourGitclient:

n ForGitLabseehttps://docs.gitlab.com/ce/user/project/integrations/webhooks.html

n ForGitHub,seehttps://developer.github.com/webhooks/creating/

2. PastetheURLoftheGitConnectorintotheURLtextbox:https://GitConnector.com/mirrorhooks

3. PastethewebhooksecrettokenintheSecret Tokentextbox.

4. UncheckEnable SSL verification.

5. ClickAdd Webhook.

6. ClickthelowerrightcornerTestbuttontovalidatethewebhookiscorrectlysetup.

TroubleshootingIfthereareanyissues,reviewthefollowingfiles,orsendthemtoPerforceTechnicalSupport:

41

https://docs.gitlab.com/ce/user/project/integrations/webhooks.htmlhttps://developer.github.com/webhooks/creating/

GitHub or GitLab SSH

/opt/perforce/git-

connector/repos/graphDepot/repoName.git/.mirror.config

/opt/perforce/git-connector/repos/graphDepot/repoName.git/push_log

/opt/perforce/git-connector/repos/graphDepot/repoName.git/fetch_log

/opt/perforce/git-connector/repos/graphDepot/repoName.git/.mirror.log

/opt/perforce/git-connector/gconn.conf

/opt/perforce/git-connector/logs/gconn.log

/opt/perforce/git-connector/logs/p4gc.log


Important ThetargetrepomustNOTalreadyexistinHelixServer.

Thesourcerepomustnotbeempty.

1. OntheGitConnectorserver,loginastherootuser.

2. Createa.sshdirectory:mkdir /var/www/.ssh

3. Assigntheownerofthedirectorytobetheweb-service-user:chown web-service-user:gconn-auth /var/www/.ssh

4. Switchuserfromroottotheweb-service-user:

Ubuntu CentOSsu -s /bin/bash - www-data su -s /bin/bash - apache

andgeneratethepublicandprivateSSHkeysfortheGitConnectorinstance:

ssh-keygen -t rsa -b 4096 -C [email protected]

thenfollowtheprompts.

5. Locatethepublickey:/var/www/.ssh/id_rsa.pub

6. CopythispublickeytotheGitLaborGitHubserverandadd/var/www/.ssh/id_rsa.pubtotheuseraccount(helix-user)thatperformscloneandfetchformirroring.

42




b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName [email protected]/project/repoName.git


Tip CopytheURLfromyourproject'sSSHdrop-downbox.

8. Savethesecrettokenthatthe--mirrorhookscommandgenerates.


Mirror a repo over SSH 1. Gotohttps://GitHost.com/project/repoName/hooks

2. PastetheURLoftheGitConnectorintotheURLtextbox:https://GitConnector.com/mirrorhooks

3. PastethewebhooksecrettokenintheSecret Tokentextbox.

4. UncheckEnable SSL verification.

5. ClickAdd Webhook.

6. Clickthelower-rightcornerTestbuttontovalidatethewebhookiscorrectlysetup

TroubleshootingIfthereareanyissues,reviewthefollowingfiles,orsendthemtoPerforceTechnicalSupport:

/opt/perforce/git-






43

Gerrit configuration



Gerrit configurationPerforceprovidesacustomPythonplug-inscriptnamedgconn-change-merged.py.Whenproperlyrenamed,thescriptenablesGerrittogenerateawebhookforaspecifictypeofGitcommit,eitherchange-mergedorref-update.Youmightwanttohavetwocopiesofthescript,oneforeachtypeofaction.

System requirements with Gerrit 44Next step 44Installation of the mirror hooks 45Configure Gerrit for HTTP 45Configure Gerrit for SSH 47Testing the mirror hook 49Troubleshooting Gerrit one-way mirroring 49

System requirements with Gerritn HelixGitConnector2017.1Julypatchorlater

l IfyourinstallationoftheGitConnectorispriortotheJuly2017patch,see"UpgradingGitConnector"onpage20.

n Gerritversion2.13or2.14installedandworkingontheGitserverwithPythonversionof2.7.x.orlater

n ThePerforcewebhookforGerritgconn-change-merged.py,whichisinthe/opt/perforce/git-connector/bindirectoryoftheGitConnector

n AuserintheGerritapplicationthatislimitedtotheminimalprivilegesnecessaryformirroring

n AsourcerepoinGerritthatalreadyexistsandisnotempty


ThesourcerepomustNOTbeempty.

Next stepInstallationandscriptrenaming

44

Installation of the mirror hooks

Installation of the mirror hooks

On the Gerrit server1. Transferthe/opt/perforce/git-connector/bin/gconn-change-

merged.pyfilefromtheGitConnectorintothehookssubdirectoryofyourGerritinstallation.

2. Renamethefileinthehooksdirectorytochanged-merged:mv gconn-change-merged.py changed-merged

Thehookchanged-mergedenablesthedefaultGerritbehaviorofamandatorycodereviewofarepobeforemergingitintoaprotectedbranch.

Tip Ifyourorganizationallowsdirectrefcommitswithoutamandatorycodereview,makeasecondcopyinthehookssubdirectory,thistimewithref-updateasthename:

cp changed-merged ref-update

Thenameref-updateenablesdirectrefcommits.

3. Makechanged-merged(and,optionally,ref-update)executablebytheOSuserrunningGerrit.

Configure Gerrit for HTTP



45

Configure Gerrit for HTTP





b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName https://access-token:[email protected]/project/repoName.git

whereaccess-token:secretrepresentsyourpersonalaccesstokenforGerrit.

3. Savethesecrettokenthatthe--mirrorhookscommandgenerates,whichisnotrelatedtothepersonalaccesstokenforGerrit.


On the Gerrit server1. UpdatetheconfigurationfilefortheGerritrepositoryinthe$GERRIT_SITE/git/repoName/config

file,where$GERRIT_SITErepresentstherootdirectoryofyourGerritserver.

[gconn]

mirror-url = https://GitConnector.com/mirrorhooks

token =

git-http-url =

[gconn "http"]

46

Configure Gerrit for SSH

sslverify = false

Next step"Testingthemirrorhook"onpage49


Set up the SSH keys



1. OntheGitConnectorserver,loginastheroot user.









6. CopythispublickeytotheGerritserverandadd/var/www/.ssh/id_rsa.pubtotheuseraccount(helix-user)thatperformscloneandfetchformirroring.

47




b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName ssh://[email protected]/repoName.git



On the Gerrit serverUpdatetheconfigurationfilefortheGerritrepositoryintheGERRIT_SITE/git/repoName/configfile,whereGERRIT_SITErepresentstherootdirectoryofyourGerritserver.

[gconn]

mirror-url = https://GitConnector.com/mirrorhooks

token =

git-ssh-url =

[gconn "http"]

sslverify = false

Next step"Testingthemirrorhook"onthefacingpage

48

Testing the mirror hook

Testing the mirror hook

On the Gerrit server1. SettheenvironmentvariableGIT_DIRtotheabsolutepathtotheGerritrepository:

export GIT_DIR=GERRIT_SITE/git/repoName.git

whereGERRIT_SITErepresentstherootdirectoryofyourGerritserver.

2. FromtheGERRIT_SITEdirectory,issuethecommand:./hooks/change-merged

3. Checkwhetherthehookdisplaysthemessagethatindicatessuccessfulmirroring:GConn Hook HTTP response: mirror from http://GerritHost.com/repoName.git to //graphDepot/repoName.git

4. Ifthereareproblems,see"TroubleshootingGerritone-waymirroring"below.

Troubleshooting Gerrit one-way mirroring

Note Mirroringoccursuponcommitormerge(dependingontheGerritworkflow),sopushingaGerritcodereviewonapseudo-branch,suchas

git push origin HEAD:refs/for/master

isnotsufficienttofirethewebhook.

Important Toverifywhichrepoisbeingmirrored,attheGitConnectorcommandline,issuethefollowingcommand:

bin/gconn --mirrorhooks list

Theresponsemightbesimilarto:

//graphDepot/repoName

Helix TeamHub configuration

Ifthereareanyissues,reviewthefollowingfiles,orsendthemtoPerforceTechnicalSupport:

OntheGerritserver:

GERRIT_SITE/git/repoName.git/config

OntheGitConnectorserver:

/opt/perforce/git-








Helix TeamHub configuration

OverviewYou,theadministratorofHelixTeamHubandHelix4Git,cansetupmirroringaGitrepositoryintotheHelixVersioningEngine.Youcanchoosewhattriggersmirroringtooccur:

Sequence of events1. Anend-userdoesagitpushfromthelocalcomputertotheHelixTeamHubserver.

2. Theuser'sactionfiresaRepositoryWebhookinHelixTeamHubtonotifytheHelixGitConnector.

3. HelixGitConnectorfetchesthenewchanges.

4. TheHelixGitConnectormirrorstheGitrepointothespecifiedHelixgraphdepot.

5. Optionally,anautomatedbuildoccurs,usingatoolsuchasJenkins,whichissupportedbyp4Jenkins.

50

System requirements

LimitationsThisusecaseisforHelixTeamHubon-premise,notthecloudversionofHelixTeamHub.

Repoaccessisthroughusername/passwordorSSHkey.HelixTeamHubon-premisedoesnotsupportforSSOortwo-factorauthentication.

Formirroring,usearepositoryhook,notacompanyhookoraprojecthook.Fordetails,seehttps://helixteamhub.cloud/docs/user/webhooks/general/.

AuthenticationBothHTTPandSSHaresupported.TouseSSH,thepublickeyneedstobeaddedtoHelixTeamHub.

System requirementsn Ubuntu14.04LTS,Ubuntu16.04LTS,CentOSorRedHat6.x,CentOSorRedHat7.x

n MustbeanadministratorforaworkingHelixTeamHub,sothatyoucansetupaRepositoryWebhook

n MustbeanadministratorontheGitConnectorserver,soyoucanrunthecommandtoaddamirrorhook

n AworkingGitConnectorwithpatchreleasestring2017.1/1572461

n AworkingHelixVersioningEngineserver,either17.1patch2017.1/1574018or17.2

n AHelixTeamHubrepositorythatisnotempty.ThisrepositorywillbethesourceformirroringintotheHelixgraphdepot.

n AHelixTeamHubbotaccountyoucanuseinsteadofpersonalcredentials.Thetwooptionsare:

l Aregularbotwithaccesstorelevantprojectsandrepositoriesontheteamview

l Acompanyadminbotaccount,whichhasaccesstoeveryrepositoryinsidethecompany

Formoreinformation,seehttps://helixteamhub.cloud/docs/user/bots/

Installation of Helix TeamHub On-PremiseYou,theHelix4Gitadministrator:

1. Gotohttps://www.perforce.com/downloads/helix-teamhub-enterprise

2. LocatetheHelixTeamHubpackagetodownload.Seetheinstallationinstructionsathttps://helixteamhub.cloud/docs/admin/getting-started/orhttps://helixteamhub.cloud/docs/admin/installation/combo/

3. Runthepackageforanon-premiseinstallationofHelixTeamHub.

Next stepConfigureforHTTPorSSH:

51

https://helixteamhub.cloud/docs/user/webhooks/general/https://helixteamhub.cloud/docs/user/bots/https://www.perforce.com/downloads/helix-teamhub-enterprisehttps://www.perforce.com/downloads/helix-teamhub-enterprisehttps://helixteamhub.cloud/docs/admin/installation/combo/

Helix TeamHub HTTP

Helix TeamHub HTTP

Tip Useabotaccountinsteadofpersonalcredentials.Thetwooptionsare:

n Usearegularbot,andgiveitaccesstorelevantprojectsandrepositoriesontheteamview

n Useacompanyadminbotaccount,whichhasaccesstoeveryrepositoryinsidethecompany








52

https://helixteamhub.cloud/docs/user/bots/

Helix TeamHub HTTP

b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName git@HelixTeamHubServer/companyName/projects/projectName/repositories/gitrepoName




Mirror a repo over HTTP

53

Helix TeamHub HTTP

1. SelectHooks,Add Hook,andselectarepositoryfromthedrop-down.

2. SelecttheserviceWebHookfromthedrop-down.

3. Checkthetriggersthatyouwanttolaunchamirroringaction.

4. UnderHook attributes:

a. PastetheURLoftheGitConnectorintotheURLtextbox:https://GitConnector.com/mirrorhooks

b. Selectcontent-typeofjson (application/json)fromthedrop-down.

c. PastethemirrorhooksecrettokenintheSecrettextbox.

d. ChecktheInsecure sslcheckboxbecausenocertificateisassociatedwiththewebhook.

5. ClickSave hook.

6. ValidatethatmirroringisinplacebyrunningthefollowingcommandontheGitConnector:gconn --mirrorhooks list

ThisdisplaystherepositoriesthataremirroredandtheGitHost.Forexample:

gconn --mirrorhooks list

//hth/repoName

Helix TeamHub SSH



Helix TeamHub SSH

Tip UseabotaccountinsteadofpersonalcredentialstostoretheSSHpublickeyrequiredfortheGitConnector.(Theweb-service-usermentionedbelow).

Thetwooptionsare:

n Usearegularbot,andgiveitaccesstorelevantprojectsandrepositoriesontheteamview

n Useacompanyadminbotaccount,whichhasaccesstoeveryrepositoryinsidethecompany




1. OntheGitConnectorserver,loginastheroot user.



55

https://helixteamhub.cloud/docs/user/bots/

Helix TeamHub SSH







6. CopythispublickeytotheGitLaborGitHubserverandadd/var/www/.ssh/id_rsa.pubtotheuseraccount(helix-user)thatperformscloneandfetchformirroring.



b. Addthewebhook:gconn --mirrorhooks add graphDepotName/repoName git@HelixTeamHubServer/companyName/projects/projectName/repositories/gitrepoName


Tip CopytheURLfromyourproject'sSSHdrop-downbox.



56

Helix TeamHub SSH

Mirror a repo over SSH

1. SelectHooks,Add Hook,andselectarepositoryfromthedrop-down.

2. SelectserviceWebHookfromthedrop-down

3. Checkthetriggersthatyouwanttolaunchamirroringaction

4. UnderHookattributes:

a. PastetheURLoftheGitConnectorintotheURLtextbox:https://GitConnector.com/mirrorhooks

b. Selectcontent-typeofjson (application/json)fromthedrop-down.

c. PastethemirrorhooksecrettokenintheSecrettextbox.

d. ChecktheInsecure sslcheckboxbecausenocertificateisassociatedwiththewebhook.

5. ClickSave hook.

57

Git Connector configuration for fail-over to another Git host

6. ValidatethatmirroringisinplacebyrunningthefollowingcommandontheGitConnector:gconn --mirrorhooks list

ThisdisplaystherepositoriesthataremirroredandtheGitHost.Forexample:


//hth/repoName

Procedure

Helix4GitcanmirrorfromaGitserver,suchasGitLab,GitHub,Gerrit,orHelixTeamHub.IfthatGitserverbecomesunavailable,Helix4GitsupportsthemanualconfigurationofHelix4Gitmirroringfromthefail-overserver.

Note n ThetwoGitserversshouldbereplicasofeachother.

n TheGitConnectorcanrunonamachineseparatefromtheGitserverandtheHelixVersioningEngine(recommended),thesamemachineasaGitserver(alsorecommended),orthemachinewithHelixVersioningEngine(notrecommended).

n Perforcehastestedfail-overwithGitLabandGerrit.

ProcedureToperformafail-overofthethird-partyGitserverthattheGitConnectorfetchesfrom,usetheHelixGitConnectorsetremotecommand.

Werecommendyoufirstusethiscommandwiththe-noption:

gconn --mirrorhooks -n setremote oldUrl newUrl

where

n oldUrlisapatternthatmatchestheprimaryGitserverURLforasetofoneormorerepos

n newUrl isreplacementpatterncontainingthefail-overorsecondaryserverURL,suchthatallmirroredreposwithMirroredFromURLsmatchingtheoldUrl patternwillbemodifiedbysubstitution

59

Example

n -ndisplaysinpreviewmodethenamesofthereposthatwouldbeaffected,butdoesnotperformtheoperation

Toperformtheoperation,omitthe-noption:

gconn --mirrorhooks setremote oldUrl newUrl

Example1. SettheenvironmentvariableGCONN_CONFIGtotheabsolutepathtothegconn.conffile:

export GCONN_CONFIG=/opt/perforce/git-connector/gconn.conf

2. Runthelistcommandtoseethenamesofreposthatareassociatedwithwebhooks:gconn --mirrorhooks list

Theoutputmightbe:


//graphDepot/project1

Example

4. Torunthecommandthatswitchestothesecondaryserver,omitthe-noption:

gconn --mirrorhooks setremote https://primaryGitHost

https://secondaryGitHost

61

Effect

5. Runthelistcommandagaintolistthereposthatnowneedtobeassociatedwithwebhooks:gconn --mirrorhooks list

Theoutputis:


//graphDepot/project1

Next Steps

n "GitHuborGitLabHTTP"onpage40

n "GitHuborGitLabSSH"onpage42

n "ConfigureGerritforHTTP"onpage45

n "ConfigureGerritforSSH"onpage47

n "HelixTeamHubHTTP"onpage52

n "HelixTeamHubSSH"onpage55

Finally,pushtothecurrentlyactiveGitserverandverifythatthewebhookcausestheGitConnectortofetchthechangesothatHelix4Gitmirrorsthechangeintoarepo.

63

Configuring Git Connector to poll repos from Helix4Git

Configuring Git Connector to poll repos from Helix4GitYourorganizationmighthavecontributorsinmultiplelocationsthataregeographicallyremotefromoneanother,likeBrazilandJapan.TheadministratoroftheGitConnectorateachlocationmightwantthelocalGitConnectortoperiodicallygetthelatestversionofasetofrepos.Thiscanenabletheend-usersforagivenlocationtoexperiencefastclonesandfetches.

Procedure 64

Procedure1. TheadministratorinBrazilusesthep4 servercommandtoedittheserverspecificationthat

correspondstotheServerIdfortheinstanceoftheGitConnectorinBrazil.ThisadministratorpopulatestheExernalAddress:fieldintheserverspectocontainalistofreposforwhichBrazilwantsthelatestupdates.Thelistcanbecomma-separatedorspace-separated,andcanbeasubsetoftherepos:

ExternalAddress: //graphDepotName/repo1 //graphDepotName/repo3 //graphDepotName/repo4

64

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_server.html%23p4_server%3FTocPath%3DCommands%2520-%2520alphabetical%2520list|p4%2520server|_____0

Procedure

2. AttheGitConnectorcommand-line,theBraziladministrator:

a. SetstheenvironmentvariableGCONN_CONFIGtotheabsolutepathtothegconn.conffile:

export GCONN_CONFIG=/opt/perforce/git-connector/gconn.conf

b. Runsthecommandgconn poll-reposandverifiesthatthismanualtesthaspulledthelatestforthesetofrepos:

Command-Line Output Meaning

Polling repo: //graphDepot/repo1

From p4gc://brazilURL/graphDepoA/repo1

* [new branch] master ->

master

Brazilgetsanewbranchforthisrepo

Polling repo: //graphDepot/repo3

From p4gc://brazilURL/graphDepoA/repo3

784a8e8..e6a5604 master -> master

Brazilgetsanupdateforthisrepo

Polling repo: //graphDepot/repo4 Brazilisalreadyhasthelatestforthisrepo

3. TheBraziladministratorconfigurestheUNIXcronutilitytoscheduleanautomaticrunofthegconn poll-reposcommandataspecifiedinterval.Forexample,etc/cron.d/gconncanpollforupdatedreposevery10minutes:*/10 * * * * git /usr/bin/gconn poll-repos

Note TheadministratorforJapancanedittheserverspecassociatedwiththeJapanGitConnectorsuchthatthisserverspecforJapancontainsnone,some,orallofthereposastheserverspecforBrazil.Similarly,theadministratorforJapanmightsetupadifferentintervalforpolling.

65

TroubleshootingThefollowingsectionsindicateproblemsyoumightencounter,howtofixthem,andhowtofacilitatetroubleshootingwith"SpecialGitcommands"onpage75.

Connection problems 66SSH:userpromptedforgitspassword 67SSLcertificateproblem 68HTTPS:userdoesnotexist 68

Permission problems 68Thegconn-userneedsadminaccess 69Unabletoclone:missingreadpermission 69Unabletopush:missingcreate-repopermission 70Unabletopush:missingwrite-refpermission 70Unabletopush:notenabledbyp4protect 71Unabletopushanewbranch:missingcreate-refpermission 71Unabletodeleteabranch:missingdelete-refpermission 72Unabletoforceapush:missingforce-pushpermission 73

Branch problems 73PushresultsinmessageaboutHEADrefnotexisting 73Cloneresultsin"remoteHEADreferstononexistentref" 74

Special Git commands 75

Connection problemsThissectionlistsproblemsrelatedtoaccessinggraphdepotsorrepos.

SSH: user prompted for gits password 67SSL certificate problem 68HTTPS: user does not exist 68

66

SSH: user prompted for gits password

SSH: user prompted for gits password

Problem Solution

git clone

git@

ConnectorHost/gD1/repo8

causestheusertobepromptedforgitspassword:Cloninginto'repo8'

git@ConnectorHost's

password:

Tryoneormoreofthefollowing:

1:Runp4 protecttoopenthespecform,andaddthegconn-usertotheprotectionstablewiththewritepermission:

write user gconn-user * //...

Seep4protectinP4 Command Reference.

2:Runp4 show-permissiontofindoutwhetherthegconn-userhasadminpermission.

p4 show-permission -u gconn-user -d gD1

Ifnot,runp4 grant-permissiontograntadminaccesstothegconn-user.

p4 grant-permission -p admin -d gD1 -u

gconn-user * //...

Seep4grant-permissioninP4 Command Reference.

3:AddtheusersSSHpublickeytotheGitConnector:

p4 pubkey -i -u user < id_rsa.pub

andwaittenminutesfortheGitConnectortoupdatetheHelixServer.

Seep4pubkeyinP4 Command Reference.

67

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_pubkey.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

SSL certificate problem

SSL certificate problem

Problem Solution

git clone

https://ConnectorHost/gD1/repo8

resultsin

Cloning into 'gD1/repo8'... fatal: unable

to access

https://ConnectorHost/gD1/repo8/': SSL

certificate problem:

Invalid certificate chain

TurnoffSSLvalidation:

git config --global

http.sslVerify false

HTTPS: user does not exist

Problem Solution

git clone https://ConnectorHost/gD1/repo8

resultsin

Cloning into 'gD1/repo8'...

Username for https://ConnectorHost: bruno

Password for https://bruno@ConnectorHost:

remote: User is not authenticated: User bruno doesn't exist.

fatal: Authentication failed for

https://ConnectorHost/gD1/repo8/.

Createthemissinguserbyrunningp4 user.

Seep4userinP4 Command Reference.

Permission problemsThissectionslistspermission-relatedproblems.

The gconn-user needs admin access 69Unable to clone: missing read permission 69Unable to push: missing create-repo permission 70Unable to push: missing write-ref permission 70

68

https://bruno@connectorhost/https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_user.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_user.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

The gconn-user needs admin access

Unable to push: not enabled by p4 protect 71Unable to push a new branch: missing create-ref permission 71Unable to delete a branch: missing delete-ref permission 72Unable to force a push: missing force-push permission 73

The gconn-user needs admin access

Problem SolutionIf

git push origin master

resultsin

... GConn P4 user needs admin

access ...

Asasuperuser,runp4 protecttoopenthespecform,thenaddthegconn-usertotheprotectionstablewiththewritepermission:

write user gconn-user * //gD1/...


and,

Runp4 show-permissiontofindoutwhetherthegconn-userhasadminpermission.

p4 show-permission -u gconn-user

-d gD1

Ifnot,runp4 grant-permissiontograntadminaccesstothegconn-userforthespecifieddepot.


Unable to clone: missing read permission

Problem Solution

git clone

https://bruno@ConnectorHost/gD1/r

epo8

resultsin:

No read permission

Grantthereadpermission:

p4 grant-permission -u bruno -

p read -d gD1


69

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://bruno@connectorhost/gD1/repo8https://bruno@connectorhost/gD1/repo8https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Unable to push: missing create-repo permission

Unable to push: missing create-repo permission

Problem Solution

git push

git@ConnectorHost:gD1/repo8

master

resultsin

! [remote rejected] 8cf...b4d ->

master

(User bruno does not have

administrative privileges to

create

repo //gD1/repo8.)

Grantthepermissiontocreatearepo:

p4 grant-permission -u bruno -p

create-repo -d gD1


Unable to push: missing write-ref permission

Problem Solution


resultsin

... User bruno does not have

write-ref

privilege for reference

refs/heads/master.

Grantthewrite-refpermission:


write-ref -d gD1

Youcanspecifyanentiredepotorrepo,orlimittheusertooneormorebranchesortags.Seep4grant-permissioninP4 Command Reference.

Note Auserwiththewrite-refpermissionalsoneedsp4protectwriteaccess.

70

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.html

Unable to push: not enabled by p4 protect

Unable to push: not enabled by p4 protect

Problem SolutionIf


resultsin

... Access for user 'bruno' has not been enabled

by 'p4 protect'...

Note Auserwiththewrite-refpermissionalsoneedsp4protectwriteaccess.

Thewrite-refpermissionisthesolepermissionthatappliestheprotectionsettingintheprotectionstableforafileordirectory.Asasuperuser,runp4 protecttoopenthespecform,thenaddtheusertotheprotectionstablewiththewritepermission:

write user bruno *

//gD1/...


Unable to push a new branch: missing create-ref permission

Problem Solution

git push origin dev

resultsin

! [remote rejected] 8cf...b4d

-> master

(User bruno does not have

create-ref privilege for

reference

refs/heads/dev.)

Grantthepermissiontocreateareferenceinthegraphdepot.


create-ref -d gD1


71

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_protect.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Unable to delete a branch: missing delete-ref permission

Unable to delete a branch: missing delete-ref permission

Problem Solution

git push origin :dev

resultsin

remote: ! [remote rejected] dev

(User bruno does not have delete-

ref privilege

for reference refs/heads/dev.)

Grantthepermissiontodeletearepointhegraphdepot:


delete-ref -d gD1


72

https://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_grant-permission.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Unable to force a push: missing force-push permission

Unable to force a push: missing force-push permission

Problem SolutionSomeorganizationsallowoneormorespecialusersoradministratorstooverwriteotherpeoplesworkbygrantingthisusertheforce-pushpermission.Theforce-pushpermissionimpliesthepowersassocia

Helix4Git Administrator Guide - Perforce · Helix4Git Administrator Guide ... Git users use a Git...

Documents

Transcript of Helix4Git Administrator Guide - Perforce · Helix4Git Administrator Guide ... Git users use a Git...