DEV Community 👩‍💻👨‍💻

Rodrigo Castro
Rodrigo Castro

Posted on

Publishing your Flutter apps into GitHub pages

Versão em português:

Long, long time ago...

In a far far away land, when Flutter web used to be something experimental yet, and I was looking for somewhere to publish my Flutter app into Github pages.

But now with Flutter 3.3.3, Flutter web is already stable long time ago, decided to see what has changed. I took the opportunity to document here everything I learned.

What is this GitHub pages?

Essentially is one approach that GitHub offers you to promote your repository, as a webpage to your code, it can be a landing page, documentation or whatever you want. It's possible to do that in every repository, including a "secret" repository that consists on naming it as <your_github_username>, and if you create one GitHub page in this repository, it will be your home page and the other repositories always will be <your_github_username>

I remember that it was cool, long time ago, when the developers used to have their blogs made with static websites into GitHub using Jekyll framework, it was really popular at that moment, I remember that I used to find some cools plugins and themes to customise my blog.

Now (not really now) it's possible to publish your app into GitHub pages, and have your own web app.

Source code

The source code used in this article will be available in this link:

Option 1: Peanut
Enter fullscreen mode Exit fullscreen mode

it's a tool that makes the application build and updates/create a gh-pages branch.

In my case, I had to follow these steps:

  • Install peanut
flutter pub global activate peanut
Enter fullscreen mode Exit fullscreen mode
  • Run the peanut command line with one extra parameter, because my repository will be available at, that is different than the default that is /, that's why I needed to give this base-href extra parameter too.
flutter pub global run peanut --extra-args "--base-href=/flutter_web/"
Enter fullscreen mode Exit fullscreen mode
  • In the end it will show that the gh-pages branch construction was completely successful, but you need to sync it in git.
To push your gh-pages branch to github (without switching from your working branch), run:
  git push origin --set-upstream gh-pages
Enter fullscreen mode Exit fullscreen mode
  • It's just run this command, and your local branch will be synced with the remote and that's it, you just need to wait. You can see that there is one GitHub action running, called pages build and deployment. It's responsible to pick-up your selected branch, in this example gh-pages, and publish it as the page of your repository.

If for some reason you cannot find this GitHub action, maybe it's because the GitHub page was not configured in your repository. To fix that you need to go into your repository -> Settings -> Pages and select the branch you want to build your GitHub page.

GitHub pages settings page

Flutter web application running, with the initial counter app with the default color, which is blue

It's alive

Option 2: GitHub actions

In this alternative we are going to create one workflow that will have as trigger, any update into the main branch, so follow all of these steps to publish the GitHub page.

Let's go, open your repository into the GitHub website and follow these steps:

  • First, click into the tab Actions, just bellow the repository name and then click into New workflow.
    GitHub actions menu

  • Select the option to create the workflow by yourself set up a workflow yourself.
    Action creation menu

  • You will see this screen here. First, in the top rename the file, if you want. I'll change it to deploy_github_page.

GitHub action creation screen, in edit mode

  • Delete all the content of this file and replace with this code bellow:
name: Flutter Web Deploy
      - main
    runs-on: ubuntu-latest

      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
      - run: flutter build web --release --base-href /flutter_web/
      - run: git config github-actions
      - run: git config
      - run: git --work-tree build/web add --all
      - run: git commit -m "Automatic deployment by github-actions"
      - run: git push origin HEAD:gh-pages --force

Enter fullscreen mode Exit fullscreen mode
  • Code changed, we are ready to submit the changes, create a commit or PR directly the GitHub to save the changes, in my case I'm going to save it directly into the main branch.

Commit changes menu

  • Is it ready? Yes, now we just need to change any UI component into our application so we can proof that the workflow is working properly.

Commit showing the color change from blue to green

Screen showing all the GitHub actions steps, all successfully executed

  • All the workflow steps were satisfied and in the end it updates our application that has it's primary color as green instead of blue.

Again the flutter application running, but this time with the primary color as green

Pros and Cons of these approaches

Nazaré Tedesco thinking in some math formulas

Peanut is the simplest solution, because it takes just two command lines and you already have your gh-pages branch updated. But we have to consider that we are humans and probably we would forget to run these command lines and your application will not be updated.

In another way, with GitHub action everything runs automatically, but it takes really more time, and you have to consider once your application is growing, it will take more time to run the workflow too. But these steps will never be forgotten, because every time you update your main branch it will trigger these action once again.

Use this knowledge to go further

GitHub pages is not the only option to deploy your Flutter web app, you can give a try in other services like:

Firebase Hosting
Codemagic Static Pages


I hope I can help someone with this content, use both approaches wisely, or only one of them, depends on your use case.

See you soon!

Hagrid waving his hands, saying bye!

Top comments (0)

Hey 😍

Want to help the DEV Community feel more like a community?

Head over to the Welcome Thread and greet some new community members!

It only takes a minute of your time, and goes a long way!