action.yml

# SPDX-FileCopyrightText: 2025 DB Systel GmbH
#
# SPDX-License-Identifier: Apache-2.0

name: "Website Preview and Deployment via SSH"
description: "Deploys a built website artifact to a production and preview environment via SSH, with optional link checking."
author: "OpenRail Association"
branding:
  icon: upload-cloud
  color: purple

inputs:
  artifact_name:
    description: "The name of the uploaded artifact to deploy."
    required: true

  condition_production:
    description: "Condition to deploy to production. E.g., compare `github.ref` to `'refs/heads/main'`. See `.github/workflows/selftest.yml` for an example."
    required: true

  domain_production:
    description: "Domain name for the production deployment, e.g. https://example.com"
    required: true

  domain_preview:
    description: "Domain name for the preview deployment, e.g. https://preview.example.com"
    required: true

  dir_base:
    description: "Remote base directory (e.g. /var/www/virtual)"
    required: true

  dir_production:
    description: "Full path for production deployment"
    required: true

  dir_preview_base:
    description: "Preview base domain (e.g. preview)"
    required: true

  dir_preview_subdir:
    description: "Preview subdir (e.g. pr-123)"
    required: true

  ssh_host:
    description: "SSH hostname (e.g. webspace.example.org)"
    required: true

  ssh_user:
    description: "SSH username"
    required: true

  ssh_key:
    description: "SSH private key for authenticating with the deployment server"
    required: true

  ssh_port:
    description: "SSH port"
    required: false
    default: "22"

  ssh_timeout:
    description: "SSH connection timeout (e.g. 1m)"
    required: false
    default: "1m"

  ssh_command_timeout:
    description: "SSH command timeout (e.g. 2m)"
    required: false
    default: "2m"

  ssh_rm:
    description: "Remove remote directory before deploying (true/false)"
    required: false
    default: "true"

  ssh_strip_components:
    description: "How many path components to strip (for tar/scp unpacking)"
    required: false
    default: "1"

  linkchecker_enabled:
    description: "Enable link checker (true/false)"
    required: false
    default: "true"

  linkchecker_exclude:
    description: "Comma-separated list of domains to exclude from link checker"
    required: false
    default: ""

  linkchecker_include_fragments:
    description: "Include anchor fragments in link checking"
    required: false
    default: "true"

  linkchecker_offline:
    description: "Only check local/relative links, do not fetch remote links (true/false)"
    required: false
    default: "false"

  linkchecker_max_concurrency:
    description: "Max concurrent requests for link checker"
    required: false
    default: "1"

  linkchecker_user_agent:
    description: "User-Agent for link checking"
    required: false
    default: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Apple WebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"

  linkchecker_retry_times:
    description: "Retry delay in seconds for link checking"
    required: false
    default: "5"

  linkchecker_fail_on_errors:
    description: "Fail workflow on link check errors (true/false)"
    required: false
    default: "false"

  linkchecker_verbose:
    description: "Turn on verbose linkchecker logging in action logs (true/false)"
    required: false
    default: "false"

  linkchecker_cache_age:
    description: "Cache age for link checking (e.g. 1d), `0` disables caching"
    required: false
    default: "0"

  linkchecker_extra_args:
    description: "Extra arguments to pass to the link checker (e.g. --some-flag value)"
    required: false
    default: ""

  sticky_comment_enabled:
    description: "Whether to enable sticky comments for the pull request. Defaults to true."
    required: false
    default: "true"

  step_summary_enabled:
    description: "Whether to enable step summaries in the GitHub Actions UI. Defaults to true."
    required: false
    default: "true"

  gh_deployment:
    description: "Name of the optional GitHub deployment to create. Requires the deployments permission. Defaults to empty, in which case no deployment is created."
    required: false
    default: ""

outputs:
  url:
    description: "The URL of the deployed production or preview website"

runs:
  using: "composite"
  steps:
    # ----------------------------------------------------------------------------------------------
    # VARIABLES AND ENVIRONMENT SETUP
    # ----------------------------------------------------------------------------------------------
    - name: "Vars: PR Closed/Merged"
      shell: bash
      env:
        PR_CLOSED_OR_MERGED: ${{ github.event.pull_request && (github.event.pull_request.closed_at || github.event.pull_request.merged) }}
      run: |
        if [ -n "${PR_CLOSED_OR_MERGED}" ] && [ "${PR_CLOSED_OR_MERGED}" != "false" ]; then
          echo "IS_PR_CLOSED_OR_MERGED=true" >> $GITHUB_ENV
        else
          echo "IS_PR_CLOSED_OR_MERGED=false" >> $GITHUB_ENV
        fi

    - name: "Vars: Prod or Preview"
      shell: bash
      run: |
        echo "IS_PRODUCTION=${{ inputs.condition_production == 'true' && env.IS_PR_CLOSED_OR_MERGED != 'true' }}" >> $GITHUB_ENV
        echo "IS_PREVIEW=${{ github.event.pull_request && env.IS_PR_CLOSED_OR_MERGED != 'true' }}" >> $GITHUB_ENV

    - name: "Vars: Source and Target Directory"
      shell: bash
      env:
        INPUT_ARTIFACT_NAME: ${{ inputs.artifact_name }}
        INPUT_DIR_BASE: ${{ inputs.dir_base }}
        INPUT_DIR_PRODUCTION: ${{ inputs.dir_production }}
        INPUT_DIR_PREVIEW_BASE: ${{ inputs.dir_preview_base }}
        INPUT_DIR_PREVIEW_SUBDIR: ${{ inputs.dir_preview_subdir }}
      run: | # zizmor: ignore[github-env]
        if ${IS_PRODUCTION}; then
          echo "SOURCE_DIR=${INPUT_ARTIFACT_NAME}" >> $GITHUB_ENV
          echo "TARGET_DIR=${INPUT_DIR_BASE}/${INPUT_DIR_PRODUCTION}" >> $GITHUB_ENV
        else
          echo "SOURCE_DIR=${INPUT_ARTIFACT_NAME}/${INPUT_DIR_PREVIEW_SUBDIR}" >> $GITHUB_ENV
          echo "TARGET_DIR=${INPUT_DIR_BASE}/${INPUT_DIR_PREVIEW_BASE}/${INPUT_DIR_PREVIEW_SUBDIR}" >> $GITHUB_ENV
        fi

    - name: "Vars: Set URLs"
      shell: bash
      env:
        INPUT_DOMAIN_PRODUCTION: ${{ inputs.domain_production }}
        INPUT_DOMAIN_PREVIEW: ${{ inputs.domain_preview }}
        INPUT_DIR_PREVIEW_SUBDIR: ${{ inputs.dir_preview_subdir }}
      run: | # zizmor: ignore[github-env]
        if ${IS_PRODUCTION}; then
          echo "URL=${INPUT_DOMAIN_PRODUCTION}" >> $GITHUB_ENV
        else
          echo "URL=${INPUT_DOMAIN_PREVIEW}/${INPUT_DIR_PREVIEW_SUBDIR}" >> $GITHUB_ENV
        fi

    - name: "Vars: Helper and linkcheck Variables"
      shell: bash
      env:
        INPUT_LINKCHECKER_INCLUDE_FRAGMENTS: ${{ inputs.linkchecker_include_fragments }}
        INPUT_LINKCHECKER_OFFLINE: ${{ inputs.linkchecker_offline }}
        INPUT_LINKCHECKER_VERBOSE: ${{ inputs.linkchecker_verbose }}
        INPUT_LINKCHECKER_EXCLUDE: ${{ inputs.linkchecker_exclude }}
        INPUT_LINKCHECKER_CACHE_AGE: ${{ inputs.linkchecker_cache_age }}
        INPUT_LINKCHECKER_EXTRA_ARGS: ${{ inputs.linkchecker_extra_args }}
      run: | # zizmor: ignore[github-env]
        echo "DATETIME=$(date '+%Y-%m-%d %H:%M:%S %Z')" >> $GITHUB_ENV
        echo "SCP_UPLOAD_DIR=scp_upload_$GITHUB_SHA" >> $GITHUB_ENV
        if ${INPUT_LINKCHECKER_INCLUDE_FRAGMENTS}; then
          echo "LINKCHECKER_FRAGMENTS=--include-fragments" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_FRAGMENTS=" >> $GITHUB_ENV
        fi
        if ${INPUT_LINKCHECKER_OFFLINE}; then
          echo "LINKCHECKER_OFFLINE=--offline" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_OFFLINE=" >> $GITHUB_ENV
        fi
        if ${INPUT_LINKCHECKER_VERBOSE}; then
          echo "LINKCHECKER_VERBOSE=--verbose" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_VERBOSE=" >> $GITHUB_ENV
        fi
        if [ -n "${INPUT_LINKCHECKER_EXCLUDE}" ]; then
          echo "LINKCHECKER_EXCLUDE=$(echo "${INPUT_LINKCHECKER_EXCLUDE}" | sed 's/,/ --exclude /g; s/^/--exclude /')" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_EXCLUDE=" >> $GITHUB_ENV
        fi
        if [ -n "${INPUT_LINKCHECKER_CACHE_AGE}" ]; then
          echo "LINKCHECKER_CACHE_AGE=--cache --max-cache-age ${INPUT_LINKCHECKER_CACHE_AGE}" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_CACHE_AGE=" >> $GITHUB_ENV
        fi
        if [ -n "${INPUT_LINKCHECKER_EXTRA_ARGS}" ]; then
          echo "LINKCHECKER_EXTRA_ARGS=${INPUT_LINKCHECKER_EXTRA_ARGS}" >> $GITHUB_ENV
        else
          echo "LINKCHECKER_EXTRA_ARGS=" >> $GITHUB_ENV
        fi

    - name: "Vars: Fork Detection"
      shell: bash
      env:
        HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
        BASE_REPO: ${{ github.repository }}
        IS_PR: ${{ github.event.pull_request != '' }}
      run: | # zizmor: ignore[github-env]
        if [ "${IS_PR}" = 'true' ] && [ "${HEAD_REPO}" != "${BASE_REPO}" ]; then
          echo "IS_FORK_PR=true" >> $GITHUB_ENV
        else
          echo "IS_FORK_PR=false" >> $GITHUB_ENV
        fi

    # ----------------------------------------------------------------------------------------------
    # FORK PR: SKIP NOTICE
    # ----------------------------------------------------------------------------------------------
    - name: "Fork PR: Skip Notice"
      if: env.IS_FORK_PR == 'true'
      shell: bash
      run: |
        echo "::notice::Fork PR detected — deployment steps will be skipped. Link checking still runs. This is expected for pull requests from forks."
        cat >> $GITHUB_STEP_SUMMARY << 'EOF'
        # Deployment Skipped (Fork PR)

        This workflow was triggered by a pull request from a fork. GitHub does not expose
        repository secrets to fork-based pull requests, so the SSH key required for deployment
        is unavailable.

        **No deployment was performed.** Upload, comment, and GitHub deployment steps were skipped.
        The link checker still ran on the built artifact.
        EOF

    # ----------------------------------------------------------------------------------------------
    # ARTIFACT DOWNLOAD
    # ----------------------------------------------------------------------------------------------
    - name: Download Artifact
      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
      if: env.IS_PRODUCTION == 'true' || env.IS_PREVIEW == 'true' || env.IS_FORK_PR == 'true'
      with:
        name: ${{ inputs.artifact_name }}
        path: ./${{ env.SOURCE_DIR }}

    # ----------------------------------------------------------------------------------------------
    # CASE: CONTENT FOR CLOSED OR MERGED PR
    # ----------------------------------------------------------------------------------------------
    - name: Prepare placeholder index.html
      if: env.IS_FORK_PR != 'true' && env.IS_PR_CLOSED_OR_MERGED == 'true'
      shell: bash
      run: |
        rm -rfv "${SOURCE_DIR}"
        mkdir -p "${SOURCE_DIR}"
        echo "This PR has been closed or merged. The preview has been removed." > "${SOURCE_DIR}/index.html"

    # ----------------------------------------------------------------------------------------------
    # UPLOAD WEBSITE TO SERVER
    # ----------------------------------------------------------------------------------------------
    - name: Copy website files to a local subdirectory to preserve the file depth
      if: env.IS_FORK_PR != 'true' && (env.IS_PRODUCTION == 'true' || env.IS_PREVIEW == 'true' || env.IS_PR_CLOSED_OR_MERGED == 'true')
      shell: bash
      run: cp -r "${SOURCE_DIR}" "${SCP_UPLOAD_DIR}"

    - name: Upload Website to Server
      uses: appleboy/scp-action@ff85246acaad7bdce478db94a363cd2bf7c90345 # v1.0.0
      if: env.IS_FORK_PR != 'true' && (env.IS_PRODUCTION == 'true' || env.IS_PREVIEW == 'true' || env.IS_PR_CLOSED_OR_MERGED == 'true')
      with:
        host: ${{ inputs.ssh_host }}
        username: ${{ inputs.ssh_user }}
        key: ${{ inputs.ssh_key }}
        port: ${{ inputs.ssh_port }}
        timeout: ${{ inputs.ssh_timeout }}
        command_timeout: ${{ inputs.ssh_command_timeout }}
        target: ${{ env.TARGET_DIR }}
        source: "${{ env.SCP_UPLOAD_DIR }}/*"
        rm: ${{ inputs.ssh_rm }}
        strip_components: ${{ inputs.ssh_strip_components }}

    # ----------------------------------------------------------------------------------------------
    # REPORTING AND COMMENTS
    # ----------------------------------------------------------------------------------------------
    - name: Write Step Summary
      if: env.IS_FORK_PR != 'true' && inputs.step_summary_enabled == 'true'
      shell: bash
      run: |
        SUMMARY="# Website Deployment Summary"$'\n'"Deployed production/preview website to ${URL}"
        echo "$SUMMARY" >> $GITHUB_STEP_SUMMARY

    - name: "Sticky Comment: Add or Update"
      if: env.IS_FORK_PR != 'true' && inputs.sticky_comment_enabled == 'true' && env.IS_PREVIEW == 'true'
      uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
      with:
        header: pr-preview
        message: |
          Pull Request Live Preview
          :---:
          | <p><br />:rocket: View preview at <br />${{ env.URL }}/<br /><br /></p>
          | <p>Last updated: ${{ env.DATETIME }}</p>

    - name: "Sticky Comment: Remove"
      if: env.IS_FORK_PR != 'true' && inputs.sticky_comment_enabled == 'true' && env.IS_PR_CLOSED_OR_MERGED == 'true'
      uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
      with:
        header: pr-preview
        message: |
          Pull Request Live Preview
          :---:
          | <p><br />:x: Preview has been removed.<br /><br /></p>

    - name: "Create GitHub deployment"
      if: env.IS_FORK_PR != 'true' && inputs.gh_deployment != '' && env.IS_PREVIEW == 'true'
      uses: chrnorm/deployment-action@500aa6a23c81ffa1acf71072aee3cfa2cc2e556a # v2.0.8
      with:
        token: "${{ github.token }}"
        environment: "${{ inputs.gh_deployment }}"
        environment-url: "${{ env.URL }}"
        transient-environment: true
        initial-status: "success"

    # ----------------------------------------------------------------------------------------------
    # LINK CHECKER
    # ----------------------------------------------------------------------------------------------
    - name: Restore lychee cache
      if: ${{ inputs.linkchecker_enabled == 'true' && (env.IS_PRODUCTION == 'true' || env.IS_PREVIEW == 'true' || env.IS_FORK_PR == 'true') }}
      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
      with:
        path: .lycheecache
        key: cache-lychee-${{ github.sha }}
        restore-keys: cache-lychee-

    - name: Run Link Checker
      if: ${{ inputs.linkchecker_enabled == 'true' && (env.IS_PRODUCTION == 'true' || env.IS_PREVIEW == 'true' || env.IS_FORK_PR == 'true') }}
      uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
      with:
        args: >-
          -r ${{ inputs.linkchecker_retry_times }}
          -u "${{ inputs.linkchecker_user_agent }}"
          ${{ env.LINKCHECKER_FRAGMENTS }}
          ${{ env.LINKCHECKER_OFFLINE }}
          ${{ env.LINKCHECKER_EXCLUDE }}
          ${{ env.LINKCHECKER_VERBOSE }}
          ${{ env.LINKCHECKER_CACHE_AGE }}
          ${{ env.LINKCHECKER_EXTRA_ARGS }}
          --max-concurrency ${{ inputs.linkchecker_max_concurrency }}
          --root-dir ${{ github.workspace }}/${{ inputs.artifact_name }}
          ${{ inputs.artifact_name }}
        fail: ${{ inputs.linkchecker_fail_on_errors }}