The Git File Bridge allows you to integrate Matrix with an external Git based file repository such as GitHub, GitLab and Bitbucket, creating a representation of the file repository as assets within the Asset Map.

The concept of the Git File Bridge is shown in the figure below.

The files and folders from your Git repository will be displayed within Squiz Matrix as Physical File and Physical Folder assets. These assets allow you to view and browse the files within the system, however, you will not be able to move or modify these files.

The Git File Bridge is similar in concept to that of the File Bridge asset. However, you are not able to import the files of a Git File Bridge into Matrix as physical assets using the File Bridge Import Tool.

Git File Bridges must be created somewhere in the system that has a URL applied in order for the files to be accessible from the front end when they are imported into Matrix.

All files imported to Matrix via the Git Bridge will always get public read access. Do not use this feature to import and store files that contain sensitive data.

Git Repository

The Git Repository section of the Details screen allows you to configure the connection to an external Git repository.

The fields available are as follows:

• Git URL: Enter the URL of the external Git repository that you want to connect to and fetch files from. This can either be the HTTPS or SSH URL. The Git repository will often provide you with these 2 links to copy and paste from.
  
  If connecting to a private Git repository and using an SSH URL, you do not need to enter a username or password. You must instead store the public SSH key of the Matrix instance (found under External Tools in the SSH RSA Key section) as a deploy key in the Git repository.
  Example: if using a GitHub repository the 2 versions of the Git URL will look something like this:
  • HTTPS: https://github.com/username/repo-name.git

  Consider using SSH instead of HTTPS.
  Using HTTPS requires you to store username and password values in clear text in the Matrix database. Avoid using your personal credentials when checking out a Git repo using this method.
  
  Invalid @ symbols in HTTPS username and password values
  In order to use HTTPS authentication, you must change your username or password to one that excludes the @ symbol otherwise authentication will fail.

  • SSH: git@github.com:username/repo-name.git
    
    

    Using SSH checkout requires you to add the Matrix system's public SSH RSA key to the Git repo you'll be connecting to. You can find this SSH key on the External Tools Configuration screen.

• Username: (HTTPS URL only) Enter the username of the user used to authenticate to the Git repository. The @ symbol is invalid anywhere within the Git username itself.
• Password: (HTTPS URL only) Enter the password for the user account being used to authenticate. The @ symbol is invalid anywhere within the Git password itself.
• Sub Directories: Enter a comma-separated list of subdirectories to checkout. If no subdirectories are specified, the whole repository will be checked out.
• Secret Key: If you are using a webhook to automatically make Matrix fetch updated files, enter the secret key of the webhook (if required) set at the Git hosting service for the given repository.

Once you have entered a URL and authentication details and hit commit, a "Clone Repo" button will become available next to the Git URL field. Clicking on this button will make Matrix attempt to clone the Git repository over to the file server. This might take some time depending on the size of the repository.

Once the clone and checkout are complete, the screen will refresh and a new section called Current Repository will be available on the Details screen.

It is recommended to always use the SSH version of the URL so that you are not storing any usernames or passwords on the Matrix server.

Current Repository

The Current Repository section of the Details screen displays information about the connected Git repository and allows you to configure the branch to use.

The fields available are as follows:

• Branch, Tag, or Commit: Select a Git branch, tag, or commit ID to use as the checkout point for the repo.
  

  Tag and commit ID support is only supported in version 5.4.4.0 and up.

• Remote Git URL: This will display the current remote Git URL of the repository being used for the Git File Bridge asset.
• Update Repository: This button will let you manually fetch fetch an update from the remote Git repository for the current Branch selected. Whenever you switch to a different branch using the "Branch" field above, you will need to click this button in order to see the changes reflected in Matrix.

The image below shows an example of the Current Repository section with a cloned Git repository:

Browsing and Viewing Files

Once a connection to a remote Git repository has been established and files fetched and cloned into the Matrix file server, the files  can be browsed and viewed in the same manner as other assets within the system.

To view the contents of a file, right click on the Physical File asset in the Asset Map and select View File. The View File screen will appear.

You will not be able to edit the contents of these files within Squiz Matrix.

Linking to Files

You can link to files in the Git File Bridge in a similar way that you would link to normal assets by using the Asset ID of the Git File Bridge asset followed by the path to the file.

For example, lets say I wanted to link to the global.css file in the following Git File Bridge asset structure:

To link to it, I would use the normal asset linking format in Matrix followed by the path of the file in relation to the repository. Like this:

./?a=7037:css/global.css

When previewed on the front end, this URL would be replaced with an absolute link to the file's location on the file server:

https://www.site.net/__data/assets/git_bridge/0001/7037/css/global.css

<link href="%globals_asset_url_with_hash:7037:css/styles.css%" rel="stylesheet"/>

<link href="https://matrix.squiz.net/__data/assets/git_bridge/0001/7037/css/styles.css?h=e6543c4" rel="stylesheet"/>

The relative folder paths of all files within the Git repository is maintained when cloned over to the Matrix server, so you would link to files relatively from the the root of the Git File Bridge asset. This means that any relative references to files within your text files such as JS and CSS would still work once served via Matrix. For example, if the global.css file had links to background images like this:

.header{
    background-img: url(background-images/header.jpg); 
}

You can also link files from the Git File Bridge in JS and CSS file folders to take advantage of minification and other features provided by the File Folder assets.

Web Hooks

When you commit or push new changes to your Git repository, by default, you need to go to the Details screen of the Git File Bridge asset and click on the "Update Now" button to see the new files and changes in Matrix.

Web Hooks allow you to set up automatic updates to your Git File Bridge whenever a certain event occurs on the remote Git repository. This means that Matrix can automatically fetch updates to the files when updates to the files in the Git repository are made.

The payload URL for the Web Hook configured in your Git repository must be the publicly accessible URL of the Git File Bridge asset plus the following URL parameter: ?SQ_GIT_BRIDGE_ACTION=pull

For example: https://www.site.net/git-file-bridge-asset?SQ_GIT_BRIDGE_ACTION=pull

Refer to the documentation of your chosen Git repository system for more information on how to set up Web Hooks. Here are links to documentation of some popular Git systems:

• GitHub: https://developer.github.com/webhooks/
• GitLab: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md
• Bit Bucket: https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html

Not all Git repositories support Web Hooks.

The Git repository must also be allowed HTTP POST access to your Squiz Matrix server for a Web Hook to successfully work.