Deploy a Flutter Web App on GitLab Pages for Free

Sep 25, 2020

How to publish your Flutter web app online — in a matter of minutes.

Before we begin, I’ll assume you’re already storing your Flutter project’s repository on GitLab. If you’re using GitHub, you’ll want a tutorial for GitHub Pages, and if you’re not versioning your code… 😧

If you just want to see code, check the demo repo.

Add One Little File

Copy & paste the code below into a file called .gitlab-ci.yml in the root of your Flutter project:

image: cirrusci/flutter:latest

before_script:
  - flutter channel beta
  - flutter upgrade
  - flutter config --enable-web
  - flutter pub get

pages:
  stage: deploy
  script:
    - flutter build web
    - cp -r build/web public
  artifacts:
    paths:
      - public
  only:
    - live

Your folder structure should look something like:

my-flutter-project/
    android
    ios
    lib
    ...
    .gitlab-ci.yml 👍

This file tells GitLab: each time there’s a commit on a branch called live, run flutter build web, copy the built files to a folder called public, and make this folder publicly available on the internet.

It’s based on a handy docker image from Cirrus CI which comes with Flutter pre-installed.

I like to keep my public deployments in a separate git branch. You can use any branch name, just update the setting under pages > only in .gitlab-ci.yml.

Check your Base

You can skip this step if you want to use a custom domain with your Flutter app at the root — e.g. https://mydomain.com/.

By default, GitLab pages publishes your app to gitlab.io under a subdirectory. Say your GitLab username is yourusername and your repo is called projectname, the URL will be:

https://yourusername.gitlab.io/projectname/

Flutter needs to know that it’s running at /projectname/ rather than /. So, let’s edit the base tag in web/index.html.

Replace:

<base href="/">

with:

<base href="/projectname/">

Remember to replace projectname with the name of your repo!

Deploy

At this stage, you can already release your Flutter app to the world. If your code is ready, create a new git branch named live and push a commit.

Checking your repo on gitlab.com, under CI / CD > Jobs, you should see your flutter web app building.

While it builds, you’ll want to go to Settings > General > Visibility… and ensure that Pages is switched on and set to ‘Everyone’.

By default, this is set to *‘Only Project Members’*, meaning you’ll see a not-so-helpful 401 permissions error when you load the site.

If the build was successful, your site will now be running at something like https://yourusername.gitlab.io/projectname/. You can check the exact link in your repo at gitlab.com under Settings > Pages.

Use a Custom Domain

Open up your Flutter project’s repository on gitlab.com and head to Settings > Pages, then press ‘New Domain’.

After typing in your domain, you should see instructions for updating its DNS records. You’ll need a CNAME record to actually direct traffic to the site, along with a TXT record to prove your ownership.

Using a CNAME is pretty neat: it means you never have to think about the underlying IP address where your site is hosted.

Enjoy your Web App

I put this tutorial together while working on my latest side project, a numberline app for learning to round — special request from my partner the primary school teacher!

I hope you found this guide useful and I’d love to hear what you’re building.

Xander Gottlieb