vts_test_cicd_plugin #

This project is a guideline for publishing packages using Gitlab CI/CD

INTRODUCTION #

We assume that you already have a runner for your project so we'll only guide you through the .gitlab-ci.yml creating process

REPOSITORY VARIABLES #

First, you need to add variables to your repository. This can be done in Settings > CI/CD > Variables . [variables]

1. FLUTTER_IMAGE: docker image for Flutter, we'll using cirrusci/flutter:stable
2. GITLAB_API_TOKEN: This is your gitlab access token. This must be valid or you will not be able to create a tag whenever you change the package's version.
3. PUB_DEV variables: These variables are crucial for the final publish job. We'll explain why and how to get them in the publish stage section.

.GITLAB-CI.YML #

Important notes:

• If your package directory is not at the root of your repo (ex: images_utilities/cached_image), you'll need to add a little tweak to your yml file: -- In any job, you'll need to use before_script to move to your package directory (ex: cd cached_image) -- You'll need to provide relative path for your artifacts (ex: coverage/ -> cached_image/coverage/)

This project's .gitlab-ci.yml file is enough for most cases but it's quite simple so you can feel free to add or modify any stages and jobs for your own needs. We'll create 3 stages test, before-publish and publish. You can scroll pass the first 2 stages

TEST STAGE #

Create a simple job for running unit tests, checking and generating artifacts for code coverage. You can add a new job like integration-test, smoke-test, etc. To avoid the redundant execution of this job every time we push our code to gitlab, we'll use only and changes keywords so that only changes in the lib or test folder can trigger this job.

BEFORE-PUBLISH STAGE #

After unit testing, we have an extra stage before publish the package to pub dev. In this stage, we have 3 jobs: dry-run, dartdoc and tag-version.

dry-run is used to check if you can publish this package to pub dev. Example if you change your package version and you forgot to add new version to CHANGE.md file, this job will failed.

dart-doc will be used to dry-run dart doc so that our package points on pub dev can be maximized. Make sure to provide a dartdoc_options.yml file (or use the one from this project) so that the warnings can be turned to errors.

tag-version job can only be started manually in the main branch to create a new tag whenever your package's version changes. This job need 4 variables to work if your package is private:

• GITLAB_ACCESS_TOKEN: Your access token to the private gitlab.
• GITLAB_HOST, GITLAB_REPO_PATH, GITLAB_USERNAME: your repository's information.

If your package is public, you can remove all of those 4 variables and changegit push http://$GITBAB_USERNAME:$GITLAB_API_TOKEN@$GITLAB_HOST/$GITLAB_REPO_PATH.git to git push origin

PUBLISH STAGE #

Finally, our publish stage. In this stage, we'll publish this package to pub dev. And it can only be run on tags that we've pushed in previous tag-version job.

You'll need PUB_DEV variables that we mentioned above. This is because for auto publishing, file credentials.json must exist in the docker container of your current repository in current gitlab runner server. This is the tricky part, that file will be generated automatically on the first time you publish your package to pub dev and is stored in your machine pub cache folder. So you will need to publish you package first for these variables but don't worry, after that the CI/CD process will take care of publishing job for you. ** Note: There was a way to retrieve PUB_DEV variables without publishing it by using flutter pub uploader add [email protected] but it's not working anymore. Therefore, if you have any trick to retrieve these variables, please inform us.