build_and_publish_on_platforms.yaml

# This workflow file defines a comprehensive build and release pipeline for a
# multi-platform application. It automates the process of building, testing, and deploying the
# application to various platforms, including Android, iOS, Desktop (Windows, macOS, Linux), and Web.
name: Multi-Platform App Build and Publish

# Trigger configuration
# This keyword specifies the events that trigger the workflow.
on:
  # Manual trigger through GitHub Actions UI with configurable inputs
  workflow_dispatch:
#  This section defines the configurable inputs for the workflow.
    inputs:
      #  A choice input for selecting the release type (internal or beta), defaulting to internal.
      release_type:
        type: choice
        options:
          - internal  # For internal testing purposes
          - beta      # For beta testing with external testers
        default: internal
        description: Release Type
      
      # Toggle for Android Play Store publishing
      # : A boolean input to control Android app publishing to the Play Store, defaulting to false.
      publish_android:
        type: boolean
        default: false
        description: Publish Android App On Play Store
      
      # Toggle for iOS App Store publishing
      #  A boolean input to control iOS app publishing to the App Store, defaulting to false.
      publish_ios:
        type: boolean
        default: false
        description: Publish iOS App On App Store
      
      # Toggle for Desktop app publishing (Windows/macOS/Linux)
      # A boolean input to control desktop app publishing, defaulting to false.
      publish_desktop:
        type: boolean
        default: false
        description: Publish Desktop Apps On App Store
      
      # Toggle for Web app deployment
      # A boolean input to control web app publishing, defaulting to true.
      publish_web:
        type: boolean
        default: true
        description: Publish Web App
      
      #  A boolean input to control the iOS build process, defaulting to false.
      # Separated from publishing to allow building without deployment
      build_ios:
        type: boolean
        default: false
        description: Build iOS App

# Repository-level permissions configuration
#  This section defines the permissions required by the workflow.
permissions:
  # Grants the workflow write access to the repository contents, necessary for deployment tasks.
  contents: write

# Concurrency management configuration
# Controls how multiple workflow runs are handled
concurrency:
  # Uses "pages" group to coordinate with GitHub Pages deployments, preventing conflicts
  group: "pages"
  # When false, new runs (workflow) are queued instead of cancelling running ones
  # This ensures deployment stability and ordered releases
  cancel-in-progress: false

# Job definitions for different platforms
# This section defines the different jobs that make up the workflow.
jobs:
  # Android Build Job
  # Handles compilation and APK generation for Android platform
  build_android:
    # Sets the job name to "Build Android Application."
    name: Build Android Application
    # Specifies that the job will run on an ubuntu-latest runner.
    runs-on: ubuntu-latest
    # This section defines the individual steps within the job.
    steps:
      # Check out repository code
      # This step checks out the repository code using the actions/checkout@v4 action.
      - name: Checkout
        uses: actions/checkout@v4

      # Setup Java development environment
      # This step sets up the Java development environment using the actions/setup-java@v4.2.2 action
      # with Temurin distribution and Java version 17.
      - name: Set up JDK 17
        uses: actions/setup-java@v4.2.2
        with:
          distribution: 'temurin'
          java-version: '17'

      # Configure Gradle build tool
      # This step configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action.
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      # Cache Gradle dependencies to speed up builds
      # This step caches Gradle dependencies using the actions/cache@v3 action,
      # specifying the paths to cache and the cache key.
      - uses: actions/cache@v3
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
            ~/.konan
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}

      # Decrypt and prepare required secrets for signing
      # This step uses a custom action to decrypt and prepare secrets for signing the Android app.
      - uses: ./.github/actions/inflate-secrets
        name: Inflate Secrets
        with:
          keystore: ${{ secrets.ORIGINAL_KEYSTORE_FILE }}
          google-services: ${{ secrets.GOOGLESERVICES }}
          playstore-creds: ${{ secrets.PLAYSTORECREDS }}
          firebase-creds: ${{ secrets.FIREBASECREDS }}

      # Build signed release APK
      # This step builds the signed release APK using Gradle, setting environment variables for
      # keystore details and version code.
      - name: Build Release
        env:
          KEYSTORE_PASSWORD: ${{ secrets.ORIGINAL_KEYSTORE_FILE_PASSWORD }}
          KEYSTORE_ALIAS: ${{ secrets.ORIGINAL_KEYSTORE_ALIAS }}
          KEYSTORE_ALIAS_PASSWORD: ${{ secrets.ORIGINAL_KEYSTORE_ALIAS_PASSWORD }}
          VERSION_CODE: ${{ steps.rel_number.outputs.version-code }}
        run: |
          ./gradlew :mifospay-android:assembleRelease

      # Save built APKs as artifacts
      #  This step uploads the built Android APKs as artifacts using the actions/upload-artifact@v4
      # action, specifying the artifact name, retention days, compression level,
      # and paths to the APKs.
      - name: Upload Android Artifact
        uses: actions/upload-artifact@v4
        with:
          name: android-app
          retention-days: 1
          compression-level: 9
          path: |
            ./mifospay-android/build/outputs/apk/demo/release/mifospay-android-demo-release.apk
            ./mifospay-android/build/outputs/apk/prod/release/mifospay-android-prod-release.apk

  # Firebase Distribution Job for Android
  # Handles deployment to Firebase App Distribution for testing
  publish_android_on_firebase:
    # Sets the name of the job.
    name: Deploy Android App On Firebase
    # Specifies that this job depends on the successful completion of the
    # build_android and generate_release_info jobs.
    needs: [ build_android, generate_release_info ]
    # Indicates that this job will run on a macOS runner and its latest version.
    runs-on: macos-latest
    #  Defines the sequence of steps to be executed within the job.
    steps:
      # Basic setup steps
      # Checks out the repository code using the actions/checkout@v4 action.
      - name: Checkout
        uses: actions/checkout@v4

      # Setup Java environment
      #  Sets up the Java development environment using the actions/setup-java@v4.2.2 action with
      # Temurin distribution and Java version 17.
      - name: Set up JDK 17
        uses: actions/setup-java@v4.2.2
        with:
          distribution: 'temurin'
          java-version: '17'

      # Configure Gradle
      # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action.
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      # Setup Ruby for Fastlane automation
      # Sets up the Ruby environment using the ruby/setup-ruby@a2bbe... action and
      # enables bundler caching.
      - name: Configure Ruby
        uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0
        with:
          bundler-cache: true

      # Installs Fastlane and the required plugins (firebase_app_distribution and
      # increment_build_number) using RubyGems and Bundler. It specifies a specific version of
      # Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better
      # performance and resilience.
      - name: Install Fastlane
        run: |
          gem install bundler:2.2.27
          bundle install --jobs 4 --retry 3
          bundle exec fastlane add_plugin firebase_app_distribution
          bundle exec fastlane add_plugin increment_build_number

      # This step utilizes a custom action located at .github/actions/inflate-secrets within the
      # repository. This action is likely responsible for decrypting or preparing secrets needed
      # for the deployment process.
      - uses: ./.github/actions/inflate-secrets
        # Sets the name of the step for clarity in the workflow logs.
        name: Inflate Secrets
        # Provides input values to the custom action.
        with:
          #Passes the ORIGINAL_KEYSTORE_FILE secret to the action, likely containing
          # the Android keystore file.
          keystore: ${{ secrets.ORIGINAL_KEYSTORE_FILE }}
          # Passes the GOOGLESERVICES secret, probably containing the Google Services
          # JSON file for Firebase configuration.
          google-services: ${{ secrets.GOOGLESERVICES }}
          # Passes the PLAYSTORECREDS secret, potentially containing credentials for
          # Play Store interaction.
          playstore-creds: ${{ secrets.PLAYSTORECREDS }}
          # Passes the FIREBASECREDS secret, likely containing Firebase service account credentials
          firebase-creds: ${{ secrets.FIREBASECREDS }}

      # Retrieve built Android artifacts
      # Sets the name of the step.
      - name: Download Android Artifact
        #Utilizes the actions/download-artifact@v4 action to download previously uploaded artifacts
        uses: actions/download-artifact@v4
        # Configures the download.
        with:
          # Specifies the name of the artifact to download
          #(which was likely uploaded in the build_android job).
          name: android-app
          # Defines the local directory where the downloaded artifact will be stored.
          path: ./android-artifacts

      # Debug: List downloaded artifacts
      - name: List downloaded artifacts
        # Executes a shell command.
        # This command lists the contents of the android-artifacts directory recursively,
        # which helps in debugging and verifying the downloaded artifact.
        run: |
          ls -R ./android-artifacts

      # Get changelog for Firebase distribution
      - name: Download Beta Changelog
        # Uses the actions/download-artifact@v4 action to download the changelog artifact.
        uses: actions/download-artifact@v4
        #Configures the download.
        with:
          # Specifies the name of the changelog artifact to download.
          name: beta-changelog

      # Organize files for Firebase deployment
      - name: Move APK to build directory
        run: | #Executes shell commands.
   # Creates the necessary directory structure for the APK if it doesn't exist.
          mkdir -p ./mifospay-android/build/outputs/apk/prod/release/
   # Moves the downloaded release APK to the designated build output directory. 
          mv ./android-artifacts/prod/release/mifospay-android-prod-release.apk ./mifospay-android/build/outputs/apk/prod/release/
   #Moves the downloaded changelog file to the build output directory.
          mv ./changelogBeta ./mifospay-android/build/outputs/

      # Deploy to Firebase App Distribution
      - name: ☁️ Deploy to Firebase
        # Sets environment variables for the step.
        env:
      #Sets the VERSION_CODE environment variable to the value generated in the generate_release_info job.
          VERSION_CODE: ${{ needs.generate_release_info.outputs.version_code }}
      #Executes the Fastlane lane android deploy_on_firebase to deploy the Android app to Firebase App Distribution.
        run: bundle exec fastlane android deploy_on_firebase

 #This defines the job for publishing the Android app to the Google Play Store.
  publish_android_on_playstore:
    name: Publish Android App On Play Store
#Specifies that this job depends on the successful completion of the build_android and generate_release_info jobs.
    needs: [ build_android, generate_release_info ]
    # This job will only run if the publish_android input is set to true when the workflow is triggered.
    if: inputs.publish_android
    # Indicates that this job will run on a macOS runner.
    runs-on: macos-latest
    #Defines the sequence of steps to be executed within the job.
    steps:
      #Checks out the repository code using the actions/checkout@v4 action.
      - uses: actions/checkout@v4
        # Configures the checkout process.
        with:
          #Fetches the complete commit history, which might be necessary for versioning or release notes generation.
          fetch-depth: 0

      # Sets up the Java development environment using the actions/setup-java@v4.2.2 action with Temurin distribution and Java version 17.
      - name: Set up JDK 17
        uses: actions/setup-java@v4.2.2
        with:
          distribution: 'temurin'
          java-version: '17'

      # Setup Ruby for Fastlane
      #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action and enables bundler caching.
      - name: Configure Ruby
        uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0
        with:
          bundler-cache: true

      # Install Fastlane and plugins for Play Store deployment
      #Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using
      #RubyGems and Bundler. It specifies a specific version of Bundler (2.2.27) and configures bundle installation with
      # 4 jobs and 3 retries for better performance and resilience.
      - name: Install Fastlane
        run: |
          gem install bundler:2.2.27
          bundle install --jobs 4 --retry 3
          bundle exec fastlane add_plugin firebase_app_distribution
          bundle exec fastlane add_plugin increment_build_number

      # Setup Gradle build tool
      # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action.
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      # Prepare necessary secrets
      #This step utilizes a custom action located at .github/actions/inflate-secrets within the repository.
      #This action is likely responsible for decrypting or preparing secrets needed for the deployment process.
      - uses: ./.github/actions/inflate-secrets
        #Sets the name of the step for clarity in the workflow logs.
        name: Inflate Secrets
        # Provides input values to the custom action.
        with:
          # Passes the UPLOAD_KEYSTORE_FILE secret to the action, likely containing the Android keystore file for uploading to the Play Store.
          keystore: ${{ secrets.UPLOAD_KEYSTORE_FILE }}
          #Passes the GOOGLESERVICES secret, probably containing the Google Services JSON file for Firebase configuration.
          google-services: ${{ secrets.GOOGLESERVICES }}
          #Passes the PLAYSTORECREDS secret, potentially containing credentials for Play Store interaction.
          playstore-creds: ${{ secrets.PLAYSTORECREDS }}
          # Passes the FIREBASECREDS secret, likely containing Firebase service account credentials.
          firebase-creds: ${{ secrets.FIREBASECREDS }}

      # Build Android App Bundle for Play Store
      - name: Build Release
        env:
          #Sets the KEYSTORE_PASSWORD environment variable to the value stored in the UPLOAD_KEYSTORE_FILE_PASSWORD secret.
          KEYSTORE_PASSWORD: ${{ secrets.UPLOAD_KEYSTORE_FILE_PASSWORD }}
          #Sets the KEYSTORE_ALIAS environment variable to the value stored in the UPLOAD_KEYSTORE_ALIAS secret.
          KEYSTORE_ALIAS: ${{ secrets.UPLOAD_KEYSTORE_ALIAS }}
          #Sets the KEYSTORE_ALIAS_PASSWORD environment variable to the value stored in the UPLOAD_KEYSTORE_ALIAS_PASSWORD secret.
          KEYSTORE_ALIAS_PASSWORD: ${{ secrets.UPLOAD_KEYSTORE_ALIAS_PASSWORD }}
          #Sets the VERSION_CODE environment variable to the value generated in the generate_release_info job.
          VERSION_CODE: ${{ needs.generate_release_info.outputs.version_code }}
        run: |  # Executes a shell command.
      #This command uses Gradle to build the Android App Bundle (AAB) for release, targeting the mifospay-android module.
          ./gradlew :mifospay-android:bundleRelease

      # Save AAB files as artifacts
      - name: Archive Build
        #Utilizes the actions/upload-artifact@v4 action to upload the built AAB as an artifact.
        uses: actions/upload-artifact@v4
        with: #Configures the upload.
          name: release-aabs
          #Defines the path to the AAB file, using a wildcard to match any AAB files in any subdirectory.
          path: ./**/*.aab

      # Deploy to Play Store Internal testing track
      - name: Deploy to Playstore Internal
        # Executes the Fastlane lane deploy_internal to deploy the AAB to the Play Store's internal testing track.
        run: bundle exec fastlane deploy_internal

      # Promote to beta if specified
      - name: Promote Internal to Beta
        #This step will only run if the release_type input provided when triggering the workflow is set to beta.
        if: github.event.inputs.release_type == 'beta'
    # Executes the Fastlane lane promote_to_beta to promote the release from the internal testing track to the beta testing track on the Play Store.
        run: bundle exec fastlane promote_to_beta

  # iOS Build Job
  # Handles compilation and IPA generation for iOS platform
  build_ios:
    name: Build iOS App
    #Indicates that this job will run on a macOS runner, which is required for building iOS apps.
    runs-on: macos-latest
    steps:
     # Checks out the repository code using the actions/checkout@v4 action.
      - uses: actions/checkout@v4
        #Sets up the Java development environment using the actions/setup-java@v4 action. This might be needed for some dependencies or build tools used in the iOS project.
      - uses: actions/setup-java@v4
        with: #Configures the Java setup.
          java-version: 17
          distribution: 'temurin'  # Uses the Temurin distribution of Java.

      # Setup Ruby for Fastlane
      #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action and enables bundler caching.
      - name: Configure Ruby
        uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0
        with:
          bundler-cache: true

      # Install Fastlane and plugins for iOS automation
      # Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using RubyGems and Bundler.
      # It specifies a specific version of Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better performance and resilience.
      - name: Install Fastlane
        run: |
          gem install bundler:2.2.27
          bundle install --jobs 4 --retry 3
          bundle exec fastlane add_plugin firebase_app_distribution
          bundle exec fastlane add_plugin increment_build_number


      # Build iOS app if enabled
      # This step builds the iOS app using Fastlane.
      - name: Build iOS App
        #This step will only run if the build_ios input is set to true when the workflow is triggered.
        if: inputs.build_ios
        # Executes the Fastlane lane ios build_ios to build the iOS app.
        run: bundle exec fastlane ios build_ios

      # Save IPA as artifact
      #This step uploads the built iOS app (IPA file) as an artifact.
      - name: Upload iOS Artifact
        #This step will only run if the build_ios input is set to true when the workflow is triggered.
        if: inputs.build_ios
        # Utilizes the actions/upload-artifact@v4 action to upload the artifact.
        uses: actions/upload-artifact@v4
        with: # Configures the upload.
          name: ios-app
          retention-days: 1 # Sets the retention period for the artifact to 1 day.
          compression-level: 9 #  Uses the highest compression level for the artifact.
    #Defines the path to the IPA file to be uploaded. I hope this detailed explanation helps you with your documentation.
    #Let me know if you have any other questions or need further assistance with other parts of the workflow file.
          path: mifospay-ios/mifospay-ios-app.ipa

  # Firebase Distribution Job for iOS
  # Handles deployment to Firebase App Distribution for iOS testing
  publish_ios_app_to_firebase:
    name: Publish iOS App On Firebase
    #This job will only run if the publish_ios input is set to true when the workflow is triggered.
    if: inputs.publish_ios
    #Specifies that this job depends on the successful completion of the build_ios and generate_release_info jobs.
    needs: [ build_ios, generate_release_info ]
    # Indicates that this job will run on a macOS runner, which is required for interacting with iOS build artifacts and tools.
    runs-on: macos-latest
    permissions: # Defines the permissions required by this job.
      #Grants the job write access to the repository contents, which might be necessary for uploading artifacts or modifying files.
      contents: write
    steps:  # Defines the sequence of steps to be executed within the job.
    #Checks out the repository code using the actions/checkout@v4 action. This is a common first step in most workflows
    #to ensure the job has access to the project's files.
      - uses: actions/checkout@v4

      # Setup Ruby for Fastlane
      #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action
      #and enables bundler caching. This is likely needed because Fastlane, a popular mobile deployment tool, is written in Ruby.
      - name: Configure Ruby
        uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0
        with:
          bundler-cache: true

      # Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using RubyGems and Bundler.
      # It specifies a specific version of Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better performance and resilience.
      - name: Install Fastlane
        run: |
          gem install bundler:2.2.27
          bundle install --jobs 4 --retry 3
          bundle exec fastlane add_plugin firebase_app_distribution
          bundle exec fastlane add_plugin increment_build_number


      # Get iOS app artifact
      # Downloads the previously built iOS app artifact (IPA file) using the actions/download-artifact@v4 action.
      - name: Download iOS App
        uses: actions/download-artifact@v4
        #Specifies the name of the artifact to download, which was likely uploaded in the build_ios job.
        with:
          name: ios-app

      # Get changelog for Firebase distribution
      # Downloads the changelog artifact, presumably for including it with the Firebase App Distribution release.
      - name: Download Beta Changelog
        uses: actions/download-artifact@v4
        # pecifies the name of the changelog artifact to download.
        with:
          name: beta-changelog

      # Organize files for Firebase deployment
    #Sets the name of the step. Although the name mentions "APK," it's actually moving the iOS IPA file and the changelog.
      - name: Move APK to build directory
        #Moves any IPA file in the current directory to the mifospay-ios directory.
        #This is likely done to place the IPA file in the expected location for the Fastlane deployment lane.
        run: |
          mv *.ipa ./mifospay-ios/
     #Moves the changelogBeta file (presumably the downloaded changelog) to the mifospay-android/build/outputs/ directory.
     #This might be a mistake, as it's placing the iOS changelog in the Android build output directory.
     #It's possible this line should be adjusted to place the changelog in a more appropriate location for the iOS deployment.
          mv changelogBeta ./mifospay-android/build/outputs/


      # Deploy to Firebase App Distribution
      - name: Upload iOS App to Firebase Distribution
        #Executes the Fastlane lane ios deploy_on_firebase to deploy the iOS app to Firebase App Distribution.
        #This lane likely handles the authentication, upload, and distribution settings for Firebase.
        run: bundle exec fastlane ios deploy_on_firebase

      # Debug: Show git status
      - name: Print `git status`
     # Executes the git status command. This is a debugging step to show the current state of the Git repository within the workflow environment.
     #It can help identify any unexpected changes or issues with file operations.
        run: git status

  # App Center Publishing Job for iOS
  # Handles deployment to App Center for iOS distribution
  publish_ios_app_to_app_center:
    #Specifies that this job depends on the successful completion of the build_ios and generate_release_info jobs.
    #This ensures that the iOS app is built and the release information is generated before attempting to publish to App Center.
    needs: [ build_ios, generate_release_info ]
    #Sets the name of the job, which will be displayed in the workflow logs.
    name: Publish iOS App On App Center
    #This job will only run if the publish_ios input is set to true when the workflow is triggered.
    #This allows you to control whether or not the app is published to App Center based on the workflow input.
    if: inputs.publish_ios
    #Indicates that this job will run on a macOS runner, which is required for interacting with iOS build artifacts and tools.
    runs-on: macos-latest
    # Checks out the repository code using the actions/checkout@v4 action.
    #This is a common first step in most workflows to ensure the job has access to the project's files.
    steps:
   #Checks out the repository code using the actions/checkout@v4 action.
  #This is a common first step in most workflows to ensure the job has access to the project's files.
      - uses: actions/checkout@v4

      # Get iOS app artifact
      # Downloads the previously built iOS app artifact (IPA file) using the actions/download-artifact@v4 action.
      - name: Download iOS Artifact
        uses: actions/download-artifact@v4
        with:
          name: ios-app

      # Get changelog for App Center
      #Downloads the changelog artifact, presumably for including it with the App Center release.
      - name: Download Changelog
        uses: actions/download-artifact@v4
        #Specifies the name of the changelog artifact to download. This suggests that the changelog is generated
        #using a tool or action that produces an artifact named "git-changelog."
        with:
          name: git-changelog

      # TODO: Implement App Store publishing

  # Desktop Build Job
  # Handles compilation for Windows, macOS, and Linux platforms
  # This defines the job for building the desktop application.
  build_desktop:
    name: Build Desktop App
    # Defines the build strategy for this job.
    strategy:
      # Specifies a matrix build, which allows the job to run multiple times with different configurations.
      matrix:
       # Defines the operating systems to build the desktop app for (Ubuntu, macOS, and Windows).
        os: [ ubuntu-latest, macos-latest, windows-latest ]
   #Specifies that the job will run on the operating system defined in the matrix.
    runs-on: ${{ matrix.os }}
    steps:  # Defines the sequence of steps to be executed within the job.
      #Checks out the repository code using the actions/checkout@v4 action.
      - uses: actions/checkout@v4
        #Sets up the Java development environment using the actions/setup-java@v4 action.
      - uses: actions/setup-java@v4
        with:
          java-version: 17
          distribution: 'temurin'

      # Setup Gradle build tool
      #Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action.
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      # Build desktop app for current OS
      #This step builds the desktop app using Gradle.
      - name: Build Desktop App
        #Sets environment variables for the step. These variables are likely used for code signing or notarization on macOS.
        env:
          NOTARIZATION_APPLE_ID: ${{ secrets.NOTARIZATION_APPLE_ID }} #Sets the Apple ID for notarization.
          NOTARIZATION_PASSWORD: ${{ secrets.NOTARIZATION_PASSWORD }} #Sets the password for notarization.
          NOTARIZATION_TEAM_ID: ${{ secrets.NOTARIZATION_TEAM_ID }} #Sets the team ID for notarization.
      #Executes the Gradle task packageReleaseDistributionForCurrentOS to build the desktop app for the current operating system.
        run: ./gradlew packageReleaseDistributionForCurrentOS

      # Save Windows artifacts (EXE and MSI)
      - name: Upload Windows Apps
        # This step will only run if the current operating system in the matrix is Windows.
        if: matrix.os == 'windows-latest'
        # Utilizes the actions/upload-artifact@v4 action to upload the artifacts.
        uses: actions/upload-artifact@v4
        with:
          name: desktop-app-${{ matrix.os }} #Specifies the name of the artifact, including the operating system.
          retention-days: 1 #Sets the retention period for the artifact to 1 day.
          compression-level: 9 # Uses the highest compression level for the artifact.
          #Defines the paths to the EXE and MSI files to be uploaded.
          path: |
            ./mifospay-desktop/build/compose/binaries/main-release/exe/*.exe
            ./mifospay-desktop/build/compose/binaries/main-release/msi/*.msi

      # Save Linux artifact (DEB)
      # This step uploads the built Linux app artifact (DEB file).
      - name: Upload Linux App
        # This step will only run if the current operating system in the matrix is Ubuntu.
        if: matrix.os == 'ubuntu-latest'
        #Utilizes the actions/upload-artifact@v4 action to upload the artifact.
        uses: actions/upload-artifact@v4
        with: # Configures the upload, similar to the Windows upload step.
          name: desktop-app-${{ matrix.os }}
          retention-days: 1
          compression-level: 9
          path: './mifospay-desktop/build/compose/binaries/main-release/deb/*.deb'

      # Save macOS artifact (DMG)
      #This step uploads the built macOS app artifact (DMG file).
      - name: Upload MacOS App
        #This step will only run if the current operating system in the matrix is macOS.
        if: matrix.os == 'macos-latest'
        # Utilizes the actions/upload-artifact@v4 action to upload the artifact.
        uses: actions/upload-artifact@v4
        #Configures the upload, similar to the Windows and Linux upload steps. I hope this detailed explanation helps you with your documentation.
        #Let me know if you have any other questions or need further assistance with other parts of the workflow file.
        with:
          name: desktop-app-${{ matrix.os }}
          retention-days: 1
          compression-level: 9
          path: './mifospay-desktop/build/compose/binaries/main-release/dmg/*.dmg'

  # Desktop Publishing Job
  #This defines the job for publishing the desktop application to various stores.
  publish_desktop:
    name: Publish Desktop App
    #Specifies that this job depends on the successful completion of the build_desktop job.
    #This ensures that the desktop app is built before attempting to publish it.
    needs: [ build_desktop ]
    # This job will only run if the publish_desktop input is set to true when the workflow is triggered.
    #This allows you to control whether or not the app is published based on the workflow input.
    if: inputs.publish_desktop
    #Indicates that this job will run on an Ubuntu runner.
    runs-on: ubuntu-latest
    #Checks out the repository code using the actions/checkout@v4 action.
    #This is a common first step in most workflows to ensure the job has access to the project's files.
    steps:
      - uses: actions/checkout@v4

      # Get all desktop artifacts
      #Downloads all the desktop app artifacts that were uploaded in the build_desktop job.
      - name: Download Desktop Artifacts
        # Utilizes the actions/download-artifact@v4 action to download the artifacts.
        uses: actions/download-artifact@v4
        with: #Configures the download.
          # Specifies a pattern to match the artifact names. This will download all artifacts whose names start with "desktop-app-".
          pattern: desktop-app-*
          #Defines the local directory where the downloaded artifacts will be stored.
          path: desktop-apps

      # TODO: Implement desktop store publishing
      # Debug: Show git status
   #Executes the git status` command. This is likely a debugging step to show the current state of the Git repository within the workflow environment.
   #It can help identify any unexpected changes or issues with file operations.
      - name: Print `git status`
        run: git status

  # Web Build Job
  # Handles compilation of web application using Kotlin/JS
  build_web:
    name: Build Web Application
    runs-on: windows-latest #Indicates that this job will run on a Windows runner.
    steps: #Defines the sequence of steps to be executed within the job.
     #Checks out the repository code using the actions/checkout@v4 action.
      - uses: actions/checkout@v4

      # Setup Java environment
      #Sets up the Java development environment using the actions/setup-java@v4 action.
      - uses: actions/setup-java@v4
        with:
          distribution: 'zulu' # Uses the Zulu distribution of Java.
          java-version: 17

      # Cache Gradle dependencies
      #Caches Gradle dependencies to speed up subsequent builds.
      - uses: actions/cache@v3
        with:
          path: | #Specifies the paths to cache (Gradle caches and Konan cache).
            ~/.gradle/caches
            ~/.gradle/wrapper
            ~/.konan
    #Defines the cache key based on the runner OS and the hash of Gradle files.
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}

      # Build web app using Kotlin/JS
      - name: Build Web(JS) App
        #Executes the Gradle task jsBrowserDistribution to build the web app.
        #This task likely produces the production-ready JavaScript files for the web application.
        run: ./gradlew jsBrowserDistribution

      # Save web app as artifact
      #This step uploads the built web application as an artifact.
      - name: Upload Web Artifact
        #Utilizes the actions/upload-artifact@v4 action to upload the artifact.
        uses: actions/upload-artifact@v4
        with: #Configures the upload.
          name: web-app
          #Defines the path to the built web app files to be uploaded. This path suggests that the web app is built using
          #Kotlin/JS and the output is placed in the productionExecutable directory. I hope this detailed explanation helps you with your documentation.
          #Let me know if you have any other questions or need further assistance with other parts of the workflow file.
          path: './mifospay-web/build/dist/js/productionExecutable'

  # Web Publishing Job
  # Handles deployment to GitHub Pages
  publish_web:
    name: Publish Web App
    #Specifies that this job depends on the successful completion of the build_web job. This ensures that the web app is built before attempting to publish it.
    needs: [ build_web ]
    # This job will only run if the publish_web input is set to true when the workflow is triggered.
  #This allows you to control whether or not the web app is published based on the workflow input.
    if: inputs.publish_web
    runs-on: ubuntu-latest # Indicates that this job will run on an Ubuntu runner.
    environment:
    #Sets the environment name to "github-pages," indicating that this job deploys to GitHub Pages.
      name: github-pages
   # Sets the environment URL to the page URL generated by the deployment step (which is defined later in the job).
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      #Grants the job write access to the GitHub OIDC (OpenID Connect) token.
      #This is needed for authenticating with GitHub Pages.
      id-token: write
      pages: write #Grants the job write access to the GitHub Pages deployment.
    steps:
      #Checks out the repository code using the actions/checkout@v4 action.
      - uses: actions/checkout@v4
    # Sets up the Java development environment using the actions/setup-java@v4 action.
    #This might be needed for some dependencies or build tools used in the web app project.
      - uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 17

      # Get web app artifact
      # Downloads the previously built web app artifact using the actions/download-artifact@v4 action.
      - name: Download Web Artifact
        uses: actions/download-artifact@v4
        with:
      # Specifies the name of the artifact to download, which was likely uploaded in the build_web job.
          name: web-app
      # Defines the local directory where the downloaded artifact will be stored.
          path: ./web-app-content


      # Configure GitHub Pages
      #Configures GitHub Pages for the deployment using the actions/configure-pages@v5 action.
      #This action sets up the necessary environment and settings for deploying to GitHub Pages.
      - name: Setup Pages
        uses: actions/configure-pages@v5

      # Upload web app to GitHub Pages
      #Uploads the web app content as an artifact to GitHub Pages using the actions/upload-pages-artifact@v3 action.
      - name: Upload static files as artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './web-app-content' # Specifies the path to the web app content to be uploaded.

      # Deploy to GitHub Pages
      # Deploys the web app to GitHub Pages using the actions/deploy-pages@v4 action.
      - name: Deploy to GitHub Pages
      #Assigns an ID to this step so that its outputs can be accessed by other steps (like setting the environment URL).
      #I hope this detailed explanation helps you with your documentation. Let me know if you have any other questions or need
      #further assistance with other parts of the workflow file.
        id: deployment
        uses: actions/deploy-pages@v4

  # Release Info Generation Job
  # Creates version numbers and release notes
  #This defines the job for generating release information, such as version numbers and changelogs.
  generate_release_info:
    name: Generate Release Info
    runs-on: ubuntu-latest
    # Defines the outputs that this job will produce, which can be used by other jobs in the workflow.
    outputs:
      version: ${{ steps.rel_number.outputs.version }} #Outputs the version number generated by the rel_number step.
      version_code: ${{ steps.rel_number.outputs.version-code }} # Outputs the version code generated by the rel_number step.
    steps: #Defines the sequence of steps to be executed within the job.
      - uses: actions/checkout@v4
        #Fetches the complete commit history, which is necessary for generating release notes based on Git commits.
        with:
          fetch-depth: 0

      # Setup Java environment
      #Sets up the Java development environment using the actions/setup-java@v4 action. This might be needed for some dependencies
      #or build tools used in the release information generation process.
      - uses: actions/setup-java@v4
        with:
          java-version: 17
          distribution: 'temurin'

      # Configure Gradle
      # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action.
      #This might be needed if the release information generation process involves Gradle tasks.
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v4

      # Generate version number
      #This step uses a custom action located at .github/actions/create-release-number within the
      #repository to generate the release number and version code.
      - uses: ./.github/actions/create-release-number
        name: Create Release Number
        #Assigns an ID to this step so that its outputs can be accessed by other steps.
        id: rel_number

      # Create release notes
      # This step uses another custom action located at .github/actions/create-release-notes to generate release notes.
      - uses: ./.github/actions/create-release-notes
        name: Create Release Notes
        with: #Provides input values to the custom action.
      #Passes the version number generated by the rel_number step as the tag name for the release notes.
          tag-name: ${{ steps.rel_number.outputs.version }}
      # Passes the GITHUB_TOKEN secret, which is automatically provided by GitHub Actions, to authenticate with the GitHub API for accessing release information.
          gh-token: ${{ secrets.GITHUB_TOKEN }}

      # Save GitHub changelog
      #Uploads the generated GitHub changelog as an artifact using the actions/upload-artifact@v4 action.
      - name: Upload GitHub Changelog
        uses: actions/upload-artifact@v4
        with:
          name: git-changelog
          #Defines the path to the changelog file to be uploaded.
          path: './mifospay-android/build/outputs/changelogGithub'

      # Save beta changelog
      #Uploads the generated beta changelog as an artifact using the actions/upload-artifact@v4 action.
      - name: Upload Beta Changelog
        uses: actions/upload-artifact@v4
        with:
          name: beta-changelog
          #: Defines the path to the changelog file to be uploaded. I hope this detailed explanation helps you with your documentation.
          #Let me know if you have any other questions or need further assistance with other parts of the workflow file
          path: './mifospay-android/build/outputs/changelogBeta'

  # GitHub Release Job
  # Creates GitHub release with all built artifacts
  github_release:
    name: Create Github Release
    #Specifies that this job depends on the successful completion of the build and release information generation jobs for all platforms (Android, desktop, web, iOS).
    needs: [ build_android, build_desktop, build_web, build_ios, generate_release_info ]
    #This job will only run if the release_type input is set to beta when the workflow is triggered.
    #This indicates that this job is specifically for creating beta releases.
    if: inputs.release_type == 'beta'
    runs-on: ubuntu-latest
    # Checks out the repository code using the actions/checkout@v4 action.
    steps:
      - uses: actions/checkout@v4
        #Fetches the complete commit history, which might be necessary for including commit information in the release.
        with:
          fetch-depth: 0

      # Get all build artifacts
      #Downloads all the build artifacts from previous jobs using the actions/download-artifact@v4 action.
      - name: Download All Artifacts
        uses: actions/download-artifact@v4
        #Defines the local directory where the downloaded artifacts will be stored.
        with:
          path: ./all-artifacts

      # Debug: Show downloaded files
      # Executes the ls -R ./all-artifacts command to list the downloaded artifacts and their directory structure.
      #This is a debugging step to verify the downloaded files.
      - name: Display structure of downloaded files
        run: ls -R ./all-artifacts

      #Creates a ZIP archive of the web app build using PowerShell.
      - name: Archive Web Build
        shell: pwsh #Specifies that the step should use PowerShell as the shell.
        # Executes the Compress-Archive command to create the ZIP archive.
        run: |
          Compress-Archive -Path './all-artifacts/web-app/*' -DestinationPath './all-artifacts/mifospay-web-app.zip'

      # Rename Ubuntu desktop artifact for consistency
      #Renames the Ubuntu desktop app artifact (DEB file) to a more user-friendly name.
      - name: Rename Ubuntu Desktop Artifact
        #Executes the mv command to rename the file.
        run: |
          mv ./all-artifacts/desktop-app-ubuntu-latest/mifoswallet_1.0.0-1_amd64.deb ./all-artifacts/desktop-app-ubuntu-latest/MifosWallet-1.0.0.deb


      # Get changelog for release
      #Downloads the Git changelog artifact generated in the generate_release_info job.
      - name: Download Git Changelog
        uses: actions/download-artifact@v4
        with:
          name: git-changelog

      # Create GitHub pre-release with all artifacts
      - name: Create Github Pre-Release
        uses: softprops/action-gh-release@v2.0.8
        with:
          #Sets the tag name for the release to the version generated in the generate_release_info job.
          tag_name: ${{ needs.generate_release_info.outputs.version }}
          #Sets the release description to the contents of the downloaded Git changelog file.
          body_path: ./all-artifacts/git-changelog/changelogGithub
          #Indicates that the release should not be a draft (i.e., it should be published immediately).
          draft: false
          prerelease: true
          #Specifies the files to be included in the release, which are the built artifacts for all platforms.
          #I hope this detailed explanation helps you with your documentation. Let me know if you have any other questions
          #or need further assistance with other parts of the workflow file.
          files: |
            ./all-artifacts/android-app/prod/release/mifospay-android-prod-release.apk
            ./all-artifacts/android-app/demo/release/mifospay-android-demo-release.apk
            ./all-artifacts/desktop-app-windows-latest/exe/MifosWallet-1.0.0.exe
            ./all-artifacts/desktop-app-windows-latest/msi/MifosWallet-1.0.0.msi
            ./all-artifacts/desktop-app-macos-latest/MifosWallet-1.0.0.dmg
            ./all-artifacts/desktop-app-ubuntu-latest/MifosWallet-1.0.0.deb
            ./all-artifacts/mifospay-web-app.zip