Deploy a Flutter Web App on GitLab Pages for Free

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

Flutter & GitLab logos

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… 😧

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 so that little fixes pushed to master don’t automatically go public! You can use any branch name, just update the setting under pages > only in .gitlab-ci.yml.

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.

An Experiment

I've started a newsletter. A few links to good ideas and interesting stories, in your inbox, every so often. Sound good?