GitLab Pages

GitHub Pages, for GitLab.

---

Author

Glavin Wiechert (Glavin001) - Twitter @GlavinW - LinkedIn

Installation

Requirements

It requires Jekyll to be installed. GitLab Pages will build Jekyll sites or simply copy content from non-jekyll sites to publicPagesDir.

Step 1) Create your deploy key pair

Create a SSH key pair for GitLab to use as deploy keys.

ssh-keygen -t rsa -C "example@email.com" -f "$(pwd)/keys/id_rsa"

They should be in path keys/id_rsa and keys/id_rsa.pub.

Step 2) Configure GitLab Pages server

Clone this repo and install it's necessary dependencies:

# Already cloned repo
npm install
bower install

Copy default config to custom config file.

cp default_config.js _config.js

Edit your new _config.js file for your setup.

Step 3) Start your GitLab Pages server

And start the server!

npm start

Profit!

Login using your GitLab User Token at http://localhost:1337.

How It Works

1. User logs into Web UI, which authenticates against GitLab with node-gitlab and retrieves a private key for subsequent requests.
2. Select the Project to enable GitLab Pages support for it. Available Projects list is pulled from GitLab with node-gitlab.
3. The selected project will setup a Deploy Key and Webhook for GitLab Pages.
4. When the user pushes to GitLab, a webhook event is sent to GitLab Pages server.
5. The Webhook is handled by gitlab-webhook and the project is pulled (or cloned) with nodegit to the GitLab Pages configured clones install directory.
6. The gl-pages branch is checked out with nodegit. (This can optionally be configured to be gh-pages branch to work on both GitHub and GitLab).
7. The public content, a GitLab Page, is served using Expressjs. Each project will be served from a different subdirectory in the form of server.publicUrl/pages/:username/:projectName/. It is recommended that the publicPagesDir be served using Nginx or Apache.

Libraries & Tools

• Node.js
• Express
• NodeGit
• Node-GitLab
• GitLab-Webhook

Docker

A docker wrapping https://github.com/csakoda/GitLab-Pages to work with gitlab.imshealth.com

Building

docker build -t gitlab-pages .

Running

docker run -d -e EXT_URL=<external pages url> -p 3000:3000 gitlab-pages

Running with crane

• Install crane
  • go get github.com/michaelsauter/crane && go install github.com/michaelsauter/crane

Initial Deploy

(Optional) Copy your id_rsa and id_rsa.pub keys into keys/

cp .env.template .env
# edit .env to contain your external pages url
crane lift

Deploy Updates

Only update the pages container, preserving the existing HTML data

crane lift -r pages