I recently built a web project from scratch for a client who had no existing infrastructure for web development. As a believer in continuous integration I decided to go with automated deployment from the very beginning.
After a quick research on off the shelf solutions and came up with the following combination:
- Host the source code on GitLab
- Build and deploy using GitLab’s continuous integration pipelines
- Host the web application on Surge
The advantage of this setup is the lack of the need for setting up your own server software while both cloud solutions have free plans to start your project with. Moreover GitLab’s free plan includes private repositories.
This blog post will guide you through the first steps of setting up GitLab and Surge for your own web project.
Setting up the project
If you don’t have one yet, use your favorite text editor or IDE to create a web
project in an empty folder with an
index.html at the top level. You can also
copy the html, js and css files from the example project I
created for this post.
Publishing the project to GitLab
First you will need a local Git repository. Set one up using the commands below:
git add index.html main.css main.html
git commit -m 'First commit'
Next create a new project on GitLab and publish the local repository with these commands (copy the origin URL from GitLab):
git remote add origin firstname.lastname@example.org:some-username/my-project.git
git push -u origin --all
Adding static web hosting
We will use Surge for quick and free static web hosting. It comes with a command line tool that can be installed using npm. Run these commands in the root of the project:
npm init -y # If you don't have a package.json yet
npm install --save-dev surge
The first time it’s used Surge prompts for an email and password. Choose a subdomain you like or let Surge generate a random one. The output should look like this:
$ node_modules/.bin/surge .
Surge - surge.sh
project path: .
size: 1 files, 57 bytes
upload: [====================] 100%, eta: 0.0s
propagate on CDN: [====================] 100%
IP Address: 188.8.131.52
Success! Project is published and running at my-awesome-project.surge.sh
Open http://my-awesome-project.surge.sh in your browser to see the published web project.
Important: Surge prompts for a subdomain every time you run it, if you want to stick with one, save it with the project:
echo my-awesome-project.surge.sh > CNAME
This is the right moment to make a Git commit:
echo node_modules >> .gitignore # Avoid commiting Node.js dependencies
git add CNAME package.json package-lock.json .gitignore
git commit -m 'Added Surge static hosting'
Setting up continuous deployment
GitLab’s continuous integration pipeline can be configured with
.gitlab-ci.yml placed in the root folder of the project. Create one with the
- npm install
- node_modules/.bin/surge .
.gitlab-ci.yml to GitLab the pipeline has to be configured
with Surge access credentials so that it can publish to the domain you
configured in the previous step. First obtain a token from Surge:
$ node_modules/.bin/surge token
Surge - surge.sh
token: <COPY THE TOKEN FROM HERE>
Next go to GitLab -> Your project -> Settings -> CI / CD -> Secret variables
- Add a key named
SURGE_LOGINand set the value to the email you use with Surge
- Add a key named
SURGE_TOKENand paste the token into the value from the output of
And now commit and push
.gitlab-ci.yml to GitLab. In a short while you should
see the pipeline running under GitLab -> Your project -> CI / CD -> Pipelines.
If it fails click on the red failed pipeline and the failed job to see the full
terminal output of the deploy job for troubleshooting.
From now on every change you push to GitLab will automatically be deployed to Surge.
Bundling the project
Setting up AssetGraph-builder is not more complicated than running these two commands:
npm install --save-dev assetgraph-builder
node_modules/.bin/buildProduction --outroot=dist index.html
Check the contents of
dist folder to see the bundled project.
To do the bundling automatically on GitLab, tweak the contents of
- npm install
- node_modules/.bin/buildProduction --outroot=dist index.html
- cp CNAME dist/
- node_modules/.bin/surge dist
Commit and push all changes to GitLab to run the pipeline. Don’t forget to add
dist folder to
.gitignore. After a short while the bundled project should
be republished to Surge.
A decent software project has automated tests. Fortunately we already have a pipeline set up with the potential of running our tests. Read the GitLab CI documentation on how to set up advanced pipelines with multiple jobs and stages.
There are also alternatives for continuous integration, Travis CI for example is free for public projects.