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

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

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

  stage: deploy
    - flutter build web
    - cp -r build/web public
      - public
    - live

Your folder structure should look something like:

    .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.

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

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


<base href="/">


<base href="/projectname/">

Remember to replace projectname with the name of your repo!


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, 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 You can check the exact link in your repo at under Settings > Pages.

Use a Custom Domain

Open up your Flutter project’s repository on 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?