GR:Gravity/Xref/Locations/Create Location

Creating a remote location

The easiest way to add a location is by creating it in the Xref configuration UI (reachable from the Configuration perspective). With the ‘Create Location’ button in the ´Locations´ section you can define a location by setting the Location URI, location name, location type and credentials. The fields, location name, uri and type are required, the user and password fields are optional and can be added from the locations table later on. The location name is the unique project name under which the sources of the remote location will be stored on the Gravity server. When creating a location it is also important to set a correct URI for the remote location as each location type (i.e. Git, Subversion …) has a unique URI format. The provided URI must also be unique so that sources are not indexed from more than 1 location. Below is a list of supported types with their accompanying format(s):

Type	Format	Example
git	[http | https]://host:port/repository.git[?branch=name]	https://github.com/user/project.git?branch=main
svn	[http | https]://host:port/repository	http://subversion.com/demo/trunk/project
Ifs	//host[@secure]/path	//ibmi/QOpensys/demo/dev/project/src
lib	//host[@secure]/library	//ibmi/source.lib
tdoms	//host[@secure]/APPCD/ENVCD~LIBLSEQNR[,ENVCD~LIBLSEQNR]/ROUTECD	//ibmi@secure/DEMO/*DEV~10/XMPSRC
files	[sftp | ftps | ftp | smb | file]://host[:port]/sources_path	sftp://linuxhost/sources/demo

Note. Currently, Xref only supports the protocol HTTP and HTTPS to access Git and Subversion repositories, also the file protocol of the location type 'files' will only access files in the file system local to the Xref server.

As of Gravity version 8.0.1 there are 2 extra location types provided, gitcmd and svncmd. The new types are for the time being beta and are to be used when the 'git' or 'svn' location type do not work as expected (internal java native implementations of git and svn). The gitcmd and svncmd rely on a system wide install (must be able to run from the command line) of either the git and or the svn program. These 2 location types are not available for the IBMi platform.

Github, Gitlab and Atlassion Bitbucket cloud no longer allow a user’s password for the repository login. Login requires an App password or personal access token as the password to be entered for a location. 
For Bitbucket the app password can be created by logging into bitbucket org and then in the browser pasting in the following url: https://bitbucket.org/account/settings/app-passwords/. Here you will be able to create an app password for reading your repositories. Once created copy and paste the created password as the password for the Gravity bitbucket location. Also note that the Bitbucket host name in the url should not contain a reference to your user name, this can happen if you copy paste from the bitbucket clone button, for example https://username@bitbucket.org/username/repomain.git should become https://bitbucket.org/?username?/?repomain.git? (without the starting username@). 
For Github and Gitlab you will need to create a personal access token through your account (of the user profile/account that has access to the repository). For Github the URL to access the repository is similar to what bitbucket uses: https://github.com/?username?/?repomain.git?, the profile user name is provided as the location's User name with the access token as the password. For Gitlab the URL to access the repository is for example https://gitlab.com/?repomain.git?, also providing a location User name and access token as the location's password. 

Git Branch name

By default the check-out of a Git repository will take place using the ubiquitous 'master' branch. If the branch to be checked-out is not the 'master' branch but for example 'main' then the property 'branch=main' must be added to the repository. Depending on the version of Gravity Admin being used you can either add this option to the location URL as '?branch=main' or add it the options field of the location as 'branch=main'.

Secure Access

When using the ifs, lib or tdoms location type then you can opt to connect in secure mode by adding '@secure' to the host part of the location, for example, //host@secure/path or //host@secure/library. When using the @secure option then the appropriate certificates must be accepted by the Gravity server java runtime, this can be an issue when using self-signed certificates. Self-signed certificates will have to be added to the server´s certificate directory ./data/certificates or to the java Keystore of the server's Java runtime, see Gravity/Client/Setup/HTTPS, in this respect the server behaves as a client initiating and consuming HTTPS requests.

IASP

When using the lib location type and the library is located on an IASP then you will need to set the IASP id/number as the first parameter after the host name for example:

'//host[/IASP1]/QSYS.LIB/LIBRARY.LIB' or at least '/host[/IASP1]/LIBRARY.LIB', here IASP1 is a configured ASP group name.

Note that to use an IASP in the location, the ASP must be set in the job description of the user configured for that location, for example, the following user profile has a custom job description of which the job description has the Initial ASP group configured as IASP1:

With regards to the credentials make sure that they do not expire or change. If credentials expire or change then Xref will not be able to access a remote repository and the repository related Xref data will become stale. To avoid unnecessary processing of inaccessible repositories (or locations), the Xref server will not try to process a location if it has the state 'suspended'. A location becomes suspended if it fails a check-out on 5 consecutive Xref Indexing runs, or is manually set from the Xref UI. Resetting a location to not suspended is only possible from the Gravity Admin Xref perspective.

Upon pressing OK with the example below, the Git repository https://github.com/RemainSoftware/GITST.git will be added as a location to Xref. To save the location then the Xref configuration must be saved. Note that any changes made to the configuration will set the configuration dirty and enable the save button allowing you to permanently store any changes made. At this point, you also have the option to remove any changes reverting the configuration to its previous (unchanged) state.

Suspend checkout

If a location is not to be checked out and indexed by the Xref server then the location can be set manually to 'suspended'. When a location is suspended then the Xref data for that location will not be removed but will also not be updated if the location repository data changes. To set a location to suspended select the value 'ýes' on the 'Suspend' field and save the configuration. When a suspended location once more becomes available then select the value 'no' on the 'Suspend' field and save the configuration. A location can also become suspended automatically. This will occur when the Xref server has failed to access the remote location in 5 consecutive indexing cycles.