{"id":15363813,"url":"https://github.com/javieraviles/quarkus-github-flow","last_synced_at":"2025-07-18T01:40:27.067Z","repository":{"id":40688466,"uuid":"268100094","full_name":"javieraviles/quarkus-github-flow","owner":"javieraviles","description":"This is a Github Flow boilerplate project using Quarkus graal native image. The whole CICD process deploying to Heroku is already setup so the development can just get started.","archived":false,"fork":false,"pushed_at":"2024-09-03T20:57:22.000Z","size":159,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T18:21:23.592Z","etag":null,"topics":["boiler","devops","github-ac","github-flow","graalvm-native-image","integration-tests","load-tests","postgres","quarkus","sonar","sonarcloud"],"latest_commit_sha":null,"homepage":"https://quarkus-github-flow.herokuapp.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/javieraviles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-30T14:51:06.000Z","updated_at":"2025-03-21T14:45:07.000Z","dependencies_parsed_at":"2024-10-16T06:20:58.458Z","dependency_job_id":"94376f82-ef8a-422c-bc62-8f4ee1e4c70d","html_url":"https://github.com/javieraviles/quarkus-github-flow","commit_stats":{"total_commits":34,"total_committers":1,"mean_commits":34.0,"dds":0.0,"last_synced_commit":"38ecb9cc626b21e621e20cd77a9638780245047c"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javieraviles%2Fquarkus-github-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javieraviles%2Fquarkus-github-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javieraviles%2Fquarkus-github-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javieraviles%2Fquarkus-github-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javieraviles","download_url":"https://codeload.github.com/javieraviles/quarkus-github-flow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249026750,"owners_count":21200502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boiler","devops","github-ac","github-flow","graalvm-native-image","integration-tests","load-tests","postgres","quarkus","sonar","sonarcloud"],"created_at":"2024-10-01T13:08:37.309Z","updated_at":"2025-04-15T07:31:12.940Z","avatar_url":"https://github.com/javieraviles.png","language":"Java","readme":"# quarkus-github-flow project\n\nThis is a **Github Flow** boilerplate project using **Quarkus** GraalVM native image. The whole CICD process deploying to Heroku is already setup so the development can just get started.\n\n  - [CICD Workflows in place](#cicd-workflows-in-place)\n  - [How to Github Flow](#how-to-github-flow)\n  - [Release](#release)\n  - [Load Tests](#load-tests)\n  - [Integration Tests](#integration-tests)\n  - [Sonar](#sonar)\n  - [Wrapping up developer responsabilities](#wrapping-up-developer-responsabilities)\n  - [Heroku DEV environment](#heroku-dev-environment)\n  - [Database](#database)\n  - [Api docs](#api-docs)\n  - [Quarkus](#quarkus)\n    - [Running the application in dev mode](#running-the-application-in-dev-mode)\n    - [Packaging and running the application](#packaging-and-running-the-application)\n    - [Creating a native executable](#creating-a-native-executable)\n  - [Continuous Deployment](#continuous-deployment)\n    - [How to do this?](#how-to-do-this)\n\n## CICD Workflows in place\n[Github Actions](https://github.com/features/actions) is the CICD tool for this project. Under the directory `.github/worflows` 4 workflows are defined:\n\n- `cron.yml` -\u003e runs periodically (cron expression). For now, two stages running locust **load tests** against **TEST** environment and updating SonarCloud dashboard will take place.\n- `master.yml` -\u003e full CICD, executed each time code gets merged into **master**. Stages: native image build / deploy to Heroku / run integration tests.\n- `pullrequest.yml` -\u003e each time a **PR** is created, runs **unitary tests**\n- `tag.yml` -\u003e whenever a **git tag** (v*) is created, this workflow creates a **release** in Github (https://github.com/javieraviles/quarkus-github-flow/releases)\n\nProject workflows are displayed in the repo [Actions](https://github.com/javieraviles/quarkus-github-flow/actions) section.\n\n## How to Github Flow\n- Create a **feature** branch from **master**\n- Send a **pull request** with your proposed changes to kick off a discussion against **master**\n- Make changes on **your** branch as needed. Your pull request will **update automatically**\n- **Merge** the pull request once the branch is **ready** to be merged\n- Tidy up your branches using the delete button in the pull request or on the branches page.\n\nCheckout [Github Guides](https://guides.github.com/introduction/flow/) for a nice and more detailed explanation on this topic.\n\n## Release\nMaster branch will always be stable, as only ready branches will be merged into it. Still, not every commit from master will be a release. A **git tag** shall be created on **master specific commits** each time a new release is to be released, following a [semantic versioning](https://semver.org/) with `v` prefix (i.e. `v1.1.0`).\n\nOnce the tag has been created, the `tag.yml` workflow will get triggered, publishing a [github release](https://github.com/javieraviles/quarkus-github-flow/releases) in the repository.\n\n## Load Tests\nAs load testing tool, [Locust](https://locust.io/) is the one this project will be using. Opensource, mature and super powerful. The load tests can be found under the directory `/loadtests`, containing an environment specific configuration file within `config` dir.\n\nAs part of the **cron** workflow, load tests will get executed against **TEST** periodically.\n\nWhenever a new endpoint is created, or a new developed feature is to affect load tests, is the **responsability of the developer** to update load tests accordingly.\n\n## Integration Tests\nThe chosen tool here is [Postman](https://www.postman.com/) due to the simplicity and universality of it.\n\nUnder the directory `/integrationtests` the test collection can be found. Within `env` an environment specific file is created so the collection can be reused.\n\nThe idea is every developer should **update and execute the collection locally** when **new features** are developed and a PR is created.\n\nThanks to [Newman](https://github.com/postmanlabs/newman) the collection can also be directly executed from the CLI. In this project, every time new code is pushed to **master** the tests are executed against **TEST** environment, currently running on Heroku.\n\n## Sonar\n[SonarCloud](https://sonarcloud.io/) is free for opensource projects, so you can register there with your github account and link it to a project. Then you have mainly two options, either SonarCloud takes care of pulling from your project whenever there are changes or PRs, or you push it from your CI (previously setting your properties in the `pom.xml`) performing a `mvn verify sonar:sonar`.\n\nThe [Dashboard](https://sonarcloud.io/dashboard?id=javieraviles_quarkus-github-flow) in this project will then get updated with the latest quality status whenever `cron.yml` worflow is executed, using **master** branch.\n\nTherefore, notice the following piece of code in the `pom.xml`:\n\n    ```\n    \u003csonar.projectKey\u003ejavieraviles_quarkus-github-flow\u003c/sonar.projectKey\u003e\n    \u003csonar.organization\u003equarkus-github-flow\u003c/sonar.organization\u003e\n    \u003csonar.host.url\u003ehttps://sonarcloud.io\u003c/sonar.host.url\u003e\n    \u003csonar.login\u003e214f06333c5b7090128e9144a144da8bc2439ab6\u003c/sonar.login\u003e\n    ```\n\nEven though the dashboard will always represent the quality status of master, is the **responsability of every developer** in the project not to worsen the **technical debt** of the project when a new feature is introduced. Some IDEs also allow you to bind the sonar project in SonarCloud to your local project so you check whether you are introducing some new code smells based on project rules.\n\n## Wrapping up developer responsabilities\n- Code within a feature branch starting from latest master\n- Whenever is ready, create a Pull Request against develop and tell another developer to check it out and start a discussion\n- Make sure your branch passes all unit tests and every piece of code you introduced contains its own unit test\n- Make sure integration tests still work. Introduce some if needed.\n- Make sure the technial debt in Sonar is the same or better when your code is merged.\n\n## Heroku DEV environment\nAs mentioned before, `master.yml` pipeline will deploy to a DEV heroku environment every time new features are merged into master branch using a `push` mechanism.\n\nA so called `Add-on` is already active in Heroku, making a `PostgreSQL` database hosted in AWS available through a connection string provided as `DATABASE_URL` environment variable.\n\nAdditionally, a `Dyno` is also created in Heroku so the platform knows how to bootstrap our docker image every time it gets deplyed, configured with the command `web ./application -Dquarkus.http.host\\=0.0.0.0`.\n\nOther than that, when the pipeline pushes to Heroku, the application downtime (startup time) will be around **50ms** thanks to the GraalVM native image.\n\n## Database\nFor testing purposes an H2 database will be used (notice the %test prefix in `application properties` that only apply to mvn test). Once deployed, the application will use a *PostgreSQL* in Heroku. Connection details will get overriden as environment variables will replace some `application properties` (notice the ${PORT:8080} annotation, this will get a default value of `8080` unless a `PORT` environment variables is set, in which case its value will override the `8080`).\n\nAs version control for database, the selected tool is `flyway`. Schema migrations will take place automatically on application startup when new flyway scripts are created at `src/main/resources/db/migration` following the appropriate annotation.\n\n## Api docs\nBoth [OpenAPI](https://quarkus-github-flow.herokuapp.com/openapi) and [Swagger-UI](https://quarkus-github-flow.herokuapp.com/swagger-ui) are available.\n\n## Quarkus\nThis project uses Quarkus, the Supersonic Subatomic Java Framework.\n\nIf you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .\n\n### Running the application in dev mode\n\nYou can run your application in dev mode that enables live coding using:\n```\n./mvnw quarkus:dev\n```\n\n### Packaging and running the application\n\nThe application can be packaged using `./mvnw package`.\nIt produces the `quarkus-github-flow-1.0.0-SNAPSHOT-runner.jar` file in the `/target` directory.\nBe aware that it’s not an _über-jar_ as the dependencies are copied into the `target/lib` directory.\n\nThe application is now runnable using `java -jar target/quarkus-github-flow-1.0.0-SNAPSHOT-runner.jar`.\n\n### Creating a native executable\n\nYou can create a native executable using: `./mvnw package -Pnative`.\n\nOr, if you don't have GraalVM installed, you can run the native executable build in a container using: `./mvnw package -Pnative -Dquarkus.native.container-build=true`.\n\nYou can then execute your native executable with: `./target/quarkus-github-flow-1.0.0-SNAPSHOT-runner`\n\nIf you want to learn more about building native executables, please consult https://quarkus.io/guides/building-native-image.\n\n## Continuous Deployment\nSo the whole project is fine and the DEV environment looks very comfy and so, BUT, what if a real production deployment completely automated is needed, with zero downtime and a serious strategy?\n\nWell, that's the reason why I'm adding this section here.\n\nA very convenient strategy is the so called [BlueGreenDeployment](https://martinfowler.com/bliki/BlueGreenDeployment.html).\n\nFor our scenario we will have two exact replicas of the production environment, blue and green (active and inactive). New deployments will be performed over the green (inactive) environment (where the router is not pointing to at the moment), and ensure with our integration and load tests from pipeline that the new deployment is working correctly. Then, the swap can be performed (router points now to green, becoming the active one).\n\n![BlueGreenDeployment](https://raw.githubusercontent.com/javieraviles/quarkus-github-flow/master/assets/blue_green_deployments.png) \n\nBoth rollback and stability should be fine following this pattern.\n\n### How to do this?\nYour PROD environments can be created at Heroku in the same way you did for DEV. Deployment can be automated editing the `tag.yaml` workflow including the same heroku deployment stages `master.yaml` is using but for the prod release. Afterwards, you should include also the postman integration tests and locust load tests to ensure environment stability.\n\nNow the end clients will not call Heroku prod environments directly, but using the **router** url. This router can be implemented using NGINX web server. Both the configuration and the swap script NGINX would use can be found at `bluegreendeployment` directory.\n\nThis is a very brief description to just give an insight of how this could be done, but don't hesitate to read further or contact me for more details about this specific approach.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavieraviles%2Fquarkus-github-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjavieraviles%2Fquarkus-github-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavieraviles%2Fquarkus-github-flow/lists"}