formigas GitLab CI

A brick that provides a GitLab CI Continuous Integration pipeline for Flutter projects as we use it at formigas.

See Details for more info about the pipeline and Troubleshooting.

Usage 🛠️

See BrickHub for usage instructions.

Output 📦

The pipeline configuration files

gitlab-ci.yml 
templates
└── build.yml

Setup and Configuration

The GitLab CI pipeline runs validation, build and tests.
The pipeline is run on every push to develop, staging and master/main branches, as well as on every merge request.
The build stage will create a release build and runs a different flavor depending on the branch:

• develop runs the development flavor
• staging runs the staging flavor
• master/main runs the production flavor

If the pipeline is run on a merge request, the test stage will add the test coverage to it. Additionally, the pipeline will output code coverage reports.

Setup GitLab CI for Android builds

For Android builds, an upload key is required. Please refer to Create an upload keystore to create a keystore. Remember that the keystore's password needs to be at least 8 characters long for GitLab to be able to store it as a masked variable. After having created the keystore, follow these steps to make it available to the pipeline:

1. Upload the keystore file to GitLab Secure Files in your project settings
2. Add the keystore password to the GitLab CI/CD settings as a masked variable with the key ANDROID_KEYSTORE_PASSWORD
3. Add the key password (usually the same as the keystore password) to the GitLab CI/CD settings as a masked variable with the key ANDROID_KEYSTORE_PRIVATE_KEY_PASSWORD
4. The pipeline assumes a keystore name of upload-keystore.jks. If you changed the name of the keystore file, update the ANDROID_KEYSTORE_PATH in templates/build.yml in the build_android_$[[ inputs.flavor ]] section to use the name of your keystore file.
5. Add the alias of the keystore to the GitLab CI/CD settings as a variable with the key ANDROID_KEYSTORE_ALIAS. The alias can be found in the command you used to create the keystore.

Setup for iOS builds

For iOS builds, having a GitLab Runner running macOS is required. Please refer to the GitLab documentation for setup instructions if you don't have one yet. Then follow Manage Runners to set up the runner for your project. During the mason make dialog you will be prompted to enter the tag configured for the runner after you chose GitLab CI as your automation service provider.

Configuration

The pipeline is defined in .gitlab-ci.yml, while the build stage is defined in templates/build.yml.

• Flutter version: Make sure to update the FLUTTER_VERSION variable to the version of Flutter you want to use.
• Image: By default, cirruslabs Flutter Docker images are used. If you want to use a different image, update the FLUTTER_DOCKER_IMAGE variable.

Troubleshooting

Error when building Android app

Execution failed for task ':app:signDevelopmentReleaseBundle'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.FinalizeBundleTask$BundleToolRunnable
   > java.lang.NullPointerException (no error message)

This error occurs when signing failed. Make sure you closely followed the steps in the Setup GitLab CI for Android builds section. If any of the steps are not followed, the pipeline will fail with the above error.

Setup 🧑‍💻

Ensure you have the mason_cli installed.

# 🎯 Activate from https://pub.dev
dart pub global activate mason_cli

# 🍺 Or install from https://brew.sh
brew tap felangel/mason
brew install mason

Installation ☁️

# Install locally
mason add formigas_gitlab_ci

# Install globally
mason add -g formigas_gitlab_ci

Usage 🚀

mason make formigas_gitlab_ci

Variables ✨

Hooks 🪝

• ✅   Pre-Gen
• ❌   Post-Gen

Environment 🌎

mason: ">=0.1.0-dev.53 <0.1.0"

0.1.0

Docs

• Improve documentation to reduce redundancy on BrickHub page

Initial Release

• Add GitLab CI pipeline configuration for Flutter projects
• Include setup instructions for Android and iOS builds
• Add troubleshooting section

MIT License

Copyright (c) 2024 formigas GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.