build-and-deploy-site.yaml

# This workflow is designed to automate the process of building and deploying a Kotlin/JS web application to GitHub Pages.
# It ensures that whenever changes are merged into the dev branch or when manually triggered, the web application is built,
# packaged, and deployed to the GitHub Pages environment, making it accessible online.

# Key Features:
# - Automated web application build using Kotlin/JS
# - Deployment to GitHub Pages
# - Supports configurable web project module name
# - Manages deployment concurrency and environment settings
# - Provides secure deployment with proper permissions

# Prerequisites:
# - Kotlin Multiplatform/JS project configured with Gradle
# - Web module set up for browser distribution
# - Java 17 or compatible version
# - GitHub Pages enabled in repository settings

# Workflow Configuration:
# - Requires input of `web_package_name` to specify the web project module
# - Uses Windows runner for build process
# - Leverages GitHub Actions for build, pages configuration, and deployment

# Workflow Triggers:
# - Can be manually called from other workflows
# - Supports workflow_call for reusability across projects

# Deployment Process:
# 1. Checkout repository code
# 2. Set up Java development environment
# 3. Build Kotlin/JS web application
# 4. Configure GitHub Pages
# 5. Upload built artifacts
# 6. Deploy to GitHub Pages

### Example Workflow
# This workflow is designed as a reusable workflow. You'll need to call it from another workflow file.
# Create a workflow file (e.g., `.github/workflows/deploy.yml`) that looks like this:
#
#   ```yaml
# name: Build And Deploy Web App
#
## Trigger conditions for the workflow
# on:
#   pull_request:
#     branches: [ "dev" ]
#     types: [ closed ]
#   workflow_dispatch:
#
# # Concurrency settings to manage multiple workflow runs
# # This ensures orderly deployment to production environment
# concurrency:
#   group: "web-pages"
#   cancel-in-progress: false
#
# permissions:
#   contents: read  # Read repository contents
#   pages: write    # Write to GitHub Pages
#   id-token: write # Write authentication tokens
#   pull-requests: write # Write to pull requests
#
# jobs:
#   build_and_deploy_web:
#     name: Build And Deploy Web App
#     uses: openMF/mifos-mobile-github-actions/.github/workflows/build-and-deploy-site.yaml@main
#     secrets: inherit
#     with:
#       web_package_name: 'mifospay-web'
#   ```
#

# Workflow to build and deploy the web application to GitHub Pages
name: Publish Web App

# Trigger conditions for the workflow
on:
  workflow_call:
    inputs:
      web_package_name:
        description: 'Name of the Web project module'
        type: string
        required: true

# Concurrency settings to manage multiple workflow runs
# This ensures orderly deployment to production environment
concurrency:
  #Groups workflow runs related to GitHub Pages deployment.
  group: "pages"
  # Prevents cancellation of in-progress deployments to ensure stability, especially in production environments.
  cancel-in-progress: false

# Grants necessary permissions for reading repository contents, writing to GitHub Pages, and writing authentication tokens.
permissions:
  contents: read  # Read repository contents
  pages: write    # Write to GitHub Pages
  id-token: write # Write authentication tokens

jobs:
  # Main job to build and deploy the web application
  build_web_app:
    # Configure deployment environment and URL
    #Specifies the deployment environment as github-pages and sets the URL using the output from the deployment step.
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    # Use Windows runner for build environment
    runs-on: windows-latest

    steps:
      # Step 1: Check out the repository code to the runner
      - uses: actions/checkout@v4

      - name: Build & Publish Web App
        uses: openMF/kmp-web-publish-action@v1.0.0
        id: deployment
        with:
          web_package_name: ${{ inputs.web_package_name }}