Implement publication release workflow for automated smart-XXX to smart-html integration with enhanced PR management and manual dispatch

[Copilot]

This PR implements a comprehensive publication release workflow that automates the integration of published content from smart-XXX repositories into the smart-html repository for deployment to smart.who.int.

Overview

The new workflow enables automatic creation of pull requests in smart-html when smart-XXX repositories publish release branches, streamlining the publication process while maintaining security and consistency.

Key Components

1. Publication Release Workflow (.github/workflows/publication-release.yml)

A new GitHub Actions workflow that:

• Accepts triggers from smart-XXX repositories via repository_dispatch, workflow_call, or workflow_dispatch (manual UI)
• Validates organization membership (WorldHealthOrganization only)
• Enforces repository naming patterns (smart-XXX, excluding smart-html)
• Validates release branch patterns (release-*)
• Downloads published content from smart-XXX/gh-pages/branches/release-*
• Creates pull requests with content placed in appropriate directories using {repo-code}-release-{version} branch naming
• Handles existing PRs by automatically closing and recreating them for repeated releases
• Uses squash commits for compact artifact management
• Includes approval-to-publish workflow for merging to main

2. Enhanced PR Management

The workflow now includes sophisticated PR handling:

• Branch Naming: Uses {repo-code}-release-{version} format (e.g., trust-release-v1.0.0)
• Existing PR Handling: For repeated requests against the same release version:
  • Automatically closes existing PR with explanatory comment
  • Deletes the existing branch
  • Creates new branch with fresh content
  • Creates new PR with updated content
• Approval Workflow: PRs include approval-to-publish sections for controlled release to production

3. Manual Dispatch Capability

The workflow can now be triggered manually from the GitHub Actions UI:

• Manual Execution: Users can trigger the workflow directly from the GitHub interface
• Use Cases: Testing, emergency releases, re-running failed publications, or processing existing release branches
• Same Validation: Manual triggers use the same security and validation requirements as automated triggers
• Accessible Interface: Available from the Actions tab with form inputs for repository, branch, and owner parameters

4. Security Features

• Organization Verification: Only accepts requests from WorldHealthOrganization
• Repository Pattern Validation: Only processes smart-XXX repositories (excluding smart-html)
• Branch Pattern Validation: Only processes release-* branches
• Input Sanitization: Comprehensive validation of all inputs across all trigger methods
• GitHub Variable Injection Safety: Follows GitHub security protocols

5. Documentation

Complete documentation including:

• Integration guide for smart-base workflow changes
• Usage and troubleshooting documentation
• Manual dispatch instructions with step-by-step UI guide
• Example implementation code
• Security considerations and monitoring guidance

Integration Flow

1. Smart-XXX repository creates a release-* branch
2. Smart-base ghbuild workflow deploys content to gh-pages/branches/release-*
3. Upon successful deployment, triggers smart-html publication-release workflow (automated) OR users can manually trigger from GitHub UI
4. Smart-html workflow handles any existing PRs by closing and deleting them
5. Downloads fresh content and creates new PR with {repo-code}-release-{version} branch
6. Content becomes available at smart.who.int/{repo-code} after PR approval and merge

Example Usage

Automated Trigger

The workflow can be triggered from smart-base ghbuild workflow:

- name: Trigger publication release for release branches
  if: env.IS_DEFAULT_BRANCH == 'false' && startsWith(github.ref_name, 'release-')
  run: |
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
      -H "Accept: application/vnd.github.v3+json" \
      "https://api.github.com/repos/WorldHealthOrganization/smart-html/dispatches" \
      -d "{
        \"event_type\": \"release-publication-request\",
        \"client_payload\": {
          \"source_repository\": \"smart-trust\",
          \"release_branch\": \"release-v1.0.0\",
          \"source_owner\": \"WorldHealthOrganization\"
        }
      }"

Manual Trigger

Users can manually trigger the workflow from the GitHub Actions UI by:

1. Navigating to the Actions tab in the smart-html repository
2. Selecting "Publication Release Workflow"
3. Clicking "Run workflow" and filling in the required parameters

Benefits

• Automation: Eliminates manual PR creation for release publications
• Flexibility: Supports automated, direct, and manual trigger methods
• Consistency: Ensures uniform directory structure and branch naming
• Security: Comprehensive validation and safe content handling across all trigger methods
• Efficiency: Uses squash commits for compact artifacts and handles PR updates automatically
• Monitoring: Detailed logging and error reporting
• Reliability: Handles repeated releases by replacing existing PRs cleanly
• Accessibility: Manual dispatch enables testing and emergency releases

Next Steps

To complete the integration, the smart-base repository's ghbuild workflow needs to be updated with the trigger code provided in .github/docs/integration-example.yml.

Fixes #33.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

@litlfred 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[litlfred]

When generating the PR it should create a feature branched named YYY-release-XXX with the content copied from the smart -YYY repo.bramch preview.

Theel PR should have an approve to publish workflow that will merge the changes into makn

If it already exists and this is a new PR then add a -build-n for the nth build on end. @copilot

[litlfred]

I want to change the behavior on a repeated request against the same release version for the same repo.....

In this case I want that if there's existing PR associated to that branch that it is closed. I want the existing Branch to be deleted. Then I want to copy in the new Branch to a new reated PR

[litlfred]

Work fluids should also be dispatchable from the GitHub user interface on a release – xxx branch in a repo for a smart guideline @copilot

[Copilot]

I want to change the behavior on a repeated request against the same release version for the same repo.....

...

Implemented the requested behavior for repeated requests. When a new request comes in for the same release version and repo, the workflow now:

1. Closes any existing PR with an explanatory comment
2. Deletes the existing branch
3. Creates a fresh new branch with the updated content
4. Creates a new PR

This ensures that repeated builds replace the previous PR completely rather than creating duplicate PRs.

Changes implemented in commit f868eab.

When generating the PR it should create a feature branched named YYY-release-XXX with the content copied from the smart -YYY repo.bramch preview.

Theel PR should have an approve to publish workfl...

Updated the workflow to use the YYY-release-XXX branch naming format as requested. The PR now creates feature branches named {repo-code}-release-{version} (e.g., trust-release-v1.0.0). The PR includes an "Approval to Publish" workflow section that allows merging changes into main after review and approval.

Changes implemented in commit f868eab.

[Copilot]

Work fluids should also be dispatchable from the GitHub user interface on a release – xxx branch in a repo for a smart guideline @copilot

Added manual dispatch capability to the publication release workflow. The workflow can now be triggered from the GitHub UI in addition to automated triggers.

How to use manual dispatch:

1. Go to Actions tab in smart-html repository
2. Select "Publication Release Workflow"
3. Click "Run workflow"
4. Fill in parameters (source repository, release branch, source owner)
5. Click "Run workflow" to start

This enables manual triggering from release-xxx branches in smart guideline repositories for testing, emergency releases, or when automated triggers fail.

Changes implemented in commit 0430ce8.