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.
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.
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.
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 ^[For example, the University of
Chicago hosts a GitLab instance for its researchers at
https://git.rcc.uchicago.edu/, which would require setting domain =
"git.rcc.uchicago.edu"
].
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.
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)
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
.
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.
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
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.