Git File Bridge

Last Updated: 28 Mar 2018

This entire manual refers to a feature that was added in version 5.3.0.0

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.

Git File Bridge concept diagram

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 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.

Bookmarks

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 will not need to enter a username or password in, but instead, the public SSH key of the Matrix instance (found under External Tools in the SSH RSA Key section) must be stored 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
    • Using HTTPS requires you to store username and password values in clear text in the Matrix database. Try and not to use your personal credentials when checking out a Git repo using this method, or alternatively, use a SSH checkout.

    • 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: Enter the username of the user used to authenticate to the Git repository (only applicable if using an HTTPS URL.
  • Password: Enter the password for the user account being used to authenticate (only applicable if using an HTTPS URL.
  • Sub Directories: Enter a comma separated list of sub directories to checkout. If no sub directories 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 web hook (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 is 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 and 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

You can also use a special Git URL keyword to reference the files if you also want to include the commit hash value of the latest commit from the Git repo. This is helpful for busting browser cache entries of outdated files as the hash value will change every time the file is updated from the Git repository.

To reference a specific file, you can use simply use the "globals" version of the keyword like this:

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

Which then will output something like this:

<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 will need to 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:

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.


Send Feedback

Noticed an error?
Want to suggest an improvement?

Let Us Know

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.