Hosting workflowr websites using GitLab

What is in this vignette?

By default workflowr assumes that the project will be hosted on GitHub, but this is not always the case. Users may prefer to use another service or have a private Git repository hosting instance. This vignette details how to host a workflowr project on GitLab. Unlike GitHub Pages, GitLab Pages offers both public and private sites. For more details, see the documentation for GitLab Pages. Similar steps will be required for other platforms but some of the specifics will be different.

Step 0: Set up a project

The first thing we need to do is set up the project we want to host. We can do this by following the first few steps of the instructions in the “Getting started” vignette. When you get to the section Deploy the website, follow the rest of the steps in this vignette.

Step 1: Create a remote repository on GitLab

Note: You can skip this step if you’d like because GitLab will automatically create the new repository after you push it in Step 4 below. This feature was introduced in GitLab 10.5, released in February 2018.

Log in to the GitLab instance you want to use and create a repository to host your project. We recommend setting the project to be Public so that others can inspect the code behind your results and extend your work.

Step 2: Configure your local workflowr project to use GitLab

You will need to know your user name and the repository name for the following steps (here we are going to use “myname” and “myproject”) as well as a URL for the hosting instance. The example below assumes you are using GitLab.com. If instead you are using a custom instance of GitLab, you will need to change the value for the argument domain accordingly ¹.

wflow_use_gitlab(username = "myname", repository = "myproject")

The function wflow_use_gitlab() automates all the local configuration necessary to use GitLab. It changes the website directory from docs/ to public/, it creates the GitLab-specific configuration file .gitlab-ci.yml with the necessary settings, and it connects the local Git repository to communicate with the remote repository on GitLab.

Step 3: Republish the analyses

In order for the correct URLs to past versions to be inserted into the HTML pages, republish the analyses with wflow_publish().

wflow_publish(republish = TRUE)

Step 4: Push to GitLab

As a final step, push the workflowr project to GitLab (you will be prompted for your GitLab username and password):

wflow_git_push()

If this step has worked correctly you should be able to refresh your GitLab page and see all the files in your workflowr project. You can view your site at myname.gitlab.io/myproject/, replacing with your username and project (note it may take a minute for the site to be deployed).

If you skipped Step 1 above, the new repository created during the initial push will be private by default. Unless you are working with sensitive data, you should consider making the project public so that it is easier to share with other researchers (e.g. collaborators, reviewers). You can change the visibility by going to Settings -> General -> Visibility and changing Project visibility to Public.

Access control for private sites

If you need to keep your project private, you can grant access to your collaborators by going to Settings -> Members. You can invite them to the project via email, but they’ll need a GitLab login to access the source code and site. They can login to GitLab using common social sites like Google and Twitter.

Compatibility with custom GitLab instances

Currently workflowr works best with the public GitLab instance hosted at gitlab.com. If you are using a custom GitLab instance that is hosted by your institution, it may not work as smoothly.

If you cannot view your workflowr website, this may be because your administrators have not enabled GitLab Pages. You will need to email them to activate this feature. You can include this link to the GitLab Pages administration instructions.

If GitLab Pages is enabled, the links to past versions of the R Markdown files should work correctly (open an Issue if you are having problems). However, there is currently no way to conveniently view the past versions of the HTML files. This is because workflowr uses the free service raw.githack.com to host past HTML files, and it only supports the URLs raw.githubusercontent.com, gist.githubusercontent.com, bitbucket.org, and gitlab.com.