Importing Projects

Illustrated drawing of Amadeus Maxmimilian StadlerIllustrated drawing of Amadeus Maxmimilian Stadler

Amadeus Stadler

Last updated August 20, 2021

Now that you have an overview of what projects are, you might be wondering how to get them into Mattrbld. There are three ways to do so, one of which you’ll already be familiar with if you followed the quickstart guide. All of them perform the same action (a git clone), but they have different side effects.

This article looks at each of the three ways individually and should give you a good idea of what makes each importing process unique and when you might want to choose one over the other.

Import During Onboarding

The first form of project import happens right the first time you open Mattrbld: during the onboarding process. This is probably how most developers will interact with Mattrbld for the first time, for example to set up a project for Mattrbld for a client or themselves.

After entering the repository and choosing the appropriate branch, the project will be cloned in the background, while the first local user profile is created and the general virtual file system for Mattrbld is set up. If you’re curious how that looks, check out the article on how it works.

Since this way of importing a project is inherently linked to the first-time setup of Mattrbld on any given device, it can naturally only be performed once, making it not a viable solution to import more than one project.

Import from Home Screen

That’s why the main way of importing projects is found directly on the home screen. Simply click on the “Import project” button at the end of the list of imported projects and you will be able to supply a link to a Git repository and subsequently select a branch to import.

Confirming these options will start the import process much like it did during the onboarding, although you obviously won’t have to create another local user for that. If you’re importing a project that was already set up to work with Mattrbld, you will be taken to the dashboard once the import completes successfully, otherwise you’ll end up in the project settings so you can set everything up.

When importing a project that has not been set up to work with Mattrbld, the user importing it for the first time will automatically be set to the role of “Project Owner”, while all other users importing the project after it was set up will join with a role of “Content Editor” by default, unless they were manually added to the project before and assigned a different role. These roles only have significance within Mattrbld, see the articles on users and roles for more information.

Should the project you’re trying to import have already been imported by another local user, it will not be duplicated. Instead, you will simply be registered as a member and it will show up under your current user profile as well to not unnecessarily waste any space. This means that it’s possible to work on the same project using two different local profiles—however, those two profiles will also show up as two independent members of a given project, which might have different roles. So make sure you know what you’re doing before attempting something like that.

Import via Invite Link

The third and final way to import a project is via an invite link. This is the most convenient option for non-technical users such as content editors, since they won’t have to deal with repository URLs or branches at all.

Invite links also give you the option to pre-select the email address, name, and proxy server, making the import as easy as the click of a button.

To generate an invite link for a person, simply add them as a member of your project under the “Users” tab of the project settings. You will be able to copy the link by clicking the button in the list entry for that user.

A screenshot of the invitation page that opens after clicking on an invite link. It allows editing the name of the person being invited and accepting the invitation via a purple buttonA screenshot of the invitation page that opens after clicking on an invite link. It allows editing the name of the person being invited and accepting the invitation via a purple button
The screen users see after opening an invite link

Opening that link will take a user to a special route, where they’ll be able to add or correct the given information and then import the project. If the user has used Mattrbld before and has a local user with the specified email address, the project would simply be imported as if it was imported through the home screen.

Otherwise, Mattrbld uses the additional information to create a local user and then import the project, similar to the process during onboarding. Opening an invite link after the project was already imported obviously won’t work and will open the project instead, displaying an appropriate message.

Invite links aren’t required to contain a name and email address for the user to be invited, which makes it possible to create a “general” invitation link to enable a group of users to join the project. To do so simply omit the respective query parameters in the URL.

Inviting a user to edit a project on Mattrbld is not the same as adding them to a Git repository! Users will only be able to import and modify projects they are members of on the Git provider’s site as well. Make sure to add them to the respective projects using your provider’s interface.

This also means that an account at the respective Git provider is required to be able to use Mattrbld.

Advanced Options

All import methods have a set of advanced options (although for Invite links they will only show up if not pre-filled) that allow you to specify a CORS proxy server to use for the Git requests. See the article on limitations to learn more about what that is and why it’s necessary. In most cases, you should be fine with the default options, however.

When setting a custom CORS proxy for an import, you will have the option to save that proxy as the default for any future imports. Please keep in mind that the proxy configured within an individual project will always take precedence over this option. It’s only used for initial imports.


When trying to import a private repository, users will be asked to confirm that they have permission to do so by signing into their user account at the respective Git provider hosting the repository. Public repositories can be imported by anyone (just like they’re visible to anyone on the internet). However, to sync local changes made to a project, the user will have to authenticate to prove that they are allowed to do so.

Since this topic can be a bit confusing and a privacy conscious user might have security concerns, it will be discussed in more detail in the next article.