Git file bridge
The files and folders from your Git repository will be displayed within 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 for the files to be accessible from the frontend when they are imported into Matrix. |
| All files imported to Matrix through 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 external Git repository URL to which you want to connect. This can either be the HTTPS or SSH URL. The Git repository will often provide you with these two links to copy and paste.
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 two 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. To use HTTPS authentication, check that your username and password does not contain the
@symbol. Authentication will fail if this symbol is included in your username or password. - 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 to which you will be connecting. You can find this SSH key on the external tools configuration screen.
- Username
-
(HTTPS URL only) enter the user’s username 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 to authenticate. The
@symbol is invalid anywhere within the Git password itself. - Subdirectories
-
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 Save, 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 always to 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 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 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 tree and select view file. The view file screen will appear.
You will not be able to edit the contents of these files within Matrix.
Linking to files
You can link to files in the Git file bridge similarly to how you link to normal assets by using the asset ID of the Git file bridge asset followed by the path to the file.
For example, if you wanted to link to the global.css file in the following Git file bridge asset structure:
To link to it, you 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 frontend, this URL would be replaced with an absolute link to the file’s location on the file server:
https://www.example.com/__data/assets/git_bridge/0001/7037/css/global.css
You can also use a unique 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 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 are maintained when cloned over to the Matrix server so that you would link to files relatively from 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 through 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.
Webhooks
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.
Webhooks allow you to set up automatic updates to your Git file bridge whenever a specific 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 webhook 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 webhooks. Here are links to documentation of some popular Git systems:
| Not all Git repositories support webhooks. The Git repository must also be allowed HTTP post access to your Matrix server for a webhook to work successfully. |