GitHub Actions updates for SUSE Multi-Linux Manager releases

Author: Joseph Cayouette
Version: v1.0 (2025-10-23)

Frequency: Annual (with major releases)
Applies to: SUSE Multi-Linux Manager (MLM) documentation CI/CD workflows
Repository: uyuni-docs
Trigger: New major release branch creation

Overview

When a new SUSE Multi-Linux Manager major release branch is created (typically once per year), several GitHub Actions workflow files must be updated to include the new branch in automated builds, testing, and deployment processes.

This ensures that:

New major release branches are included in CI/CD pipelines
Documentation builds automatically for new versions
Translation workflows cover new release branches
Release and maintenance update patterns are properly configured

Critical timing: These updates must be completed immediately after creating new major release branches to ensure continuous integration functionality.

Affected Workflow Files

Primary Workflow Files Requiring Updates

build_and_archive_devel_docs.yml - Development branch builds
build_and_archive_release_docs.yml - Release branch builds and maintenance updates
test_pdf_translations.yml - Translation testing for supported languages
update_translation_files.yml - Translation file updates and maintenance

File Locations

All workflow files are located in:

.github/workflows/
├── build_and_archive_devel_docs.yml
├── build_and_archive_release_docs.yml
├── test_pdf_translations.yml
└── update_translation_files.yml

Update Procedures

1. Development Branch Builds (`build_and_archive_devel_docs.yml`)

Purpose: Builds documentation from development and major release branches

Current Configuration:

name: Build and archive documentation from development branches

on:
  push:
    branches:
      - 'master'      # Builds both Uyuni and SUSE Multi-Linux Manager documentation
      - 'manager-4.3' # Builds SUSE Multi-Linux Manager documentation only
      - 'manager-5.0' # Builds SUSE Multi-Linux Manager documentation only
      - 'manager-5.1' # Builds SUSE Multi-Linux Manager documentation only

Update Process:

When creating SUSE Multi-Linux Manager 5.2 (example):

name: Build and archive documentation from development branches

on:
  push:
    branches:
      - 'master'      # Builds both Uyuni and SUSE Multi-Linux Manager documentation
      - 'manager-4.3' # Builds SUSE Multi-Linux Manager documentation only
      - 'manager-5.0' # Builds SUSE Multi-Linux Manager documentation only
      - 'manager-5.1' # Builds SUSE Multi-Linux Manager documentation only
      - 'manager-5.2' # ADD: New major release branch

Steps:

Open .github/workflows/build_and_archive_devel_docs.yml
Locate the branches: section under on: push:
Add the new major release branch (e.g., manager-5.2)
Ensure proper YAML formatting and indentation
Add comment indicating SUSE Multi-Linux Manager documentation only

2. Release Branch Builds (`build_and_archive_release_docs.yml`)

Purpose: Builds documentation from release branches, including maintenance updates

Current Configuration:

name: Build and archive documentation from release branches

on:
  push:
    branches:
      - 'uyuni-20[0-9][0-9].[0-9][0-9]'           # Uyuni release pattern
      - 'manager-4.3-MU-4.3.[0-9][0-9]?'         # 4.3 maintenance updates
      - 'manager-5.0-alpha[0-9]'                  # 5.0 alpha releases
      - 'manager-5.0-beta[0-9]'                   # 5.0 beta releases  
      - 'manager-5.0-rc[0-9]'                     # 5.0 release candidates
      - 'manager-5.0-gmc[0-9]'                    # 5.0 GMC releases
      - 'manager-5.0-gm'                          # 5.0 gold master
      - 'manager-5.0'                             # 5.0 final release
      - 'manager-5.0-MU-5.0.[0-9][0-9]?'         # 5.0 maintenance updates

Update Process:

When creating SUSE Multi-Linux Manager 5.2 (example):

name: Build and archive documentation from release branches

on:
  push:
    branches:
      - 'uyuni-20[0-9][0-9].[0-9][0-9]'           # Uyuni release pattern
      - 'manager-4.3-MU-4.3.[0-9][0-9]?'         # 4.3 maintenance updates
      - 'manager-5.0-alpha[0-9]'                  # 5.0 alpha releases
      - 'manager-5.0-beta[0-9]'                   # 5.0 beta releases  
      - 'manager-5.0-rc[0-9]'                     # 5.0 release candidates
      - 'manager-5.0-gmc[0-9]'                    # 5.0 GMC releases
      - 'manager-5.0-gm'                          # 5.0 gold master
      - 'manager-5.0'                             # 5.0 final release
      - 'manager-5.0-MU-5.0.[0-9][0-9]?'         # 5.0 maintenance updates
      - 'manager-5.2-alpha[0-9]'                  # ADD: 5.2 alpha releases
      - 'manager-5.2-beta[0-9]'                   # ADD: 5.2 beta releases
      - 'manager-5.2-rc[0-9]'                     # ADD: 5.2 release candidates
      - 'manager-5.2-gmc[0-9]'                    # ADD: 5.2 GMC releases
      - 'manager-5.2-gm'                          # ADD: 5.2 gold master
      - 'manager-5.2'                             # ADD: 5.2 final release
      - 'manager-5.2-MU-5.2.[0-9][0-9]?'         # ADD: 5.2 maintenance updates

Steps:

Open .github/workflows/build_and_archive_release_docs.yml
Add complete release cycle patterns for new major version
Include alpha, beta, RC, GMC, GM, final, and MU patterns
Use regex patterns to match maintenance update numbers
Maintain chronological order in the branch list

3. PDF Translation Testing (`test_pdf_translations.yml`)

Purpose: Tests PDF generation for Japanese, Korean, and Chinese translations

Current Configuration:

name: Test PDF translations (ja, ko, zh_CN)

on:
  push:
    branches:
      - master       # Builds both Uyuni and SUSE Multi-Linux Manager documentation
      - manager-4.3  # Builds SUSE Multi-Linux Manager documentation
      - manager-5.0  # Builds SUSE Multi-Linux Manager documentation
      - manager-5.1  # Builds SUSE Multi-Linux Manager documentation

Update Process:

When creating SUSE Multi-Linux Manager 5.2 (example):

name: Test PDF translations (ja, ko, zh_CN)

on:
  push:
    branches:
      - master       # Builds both Uyuni and SUSE Multi-Linux Manager documentation
      - manager-4.3  # Builds SUSE Multi-Linux Manager documentation
      - manager-5.0  # Builds SUSE Multi-Linux Manager documentation
      - manager-5.1  # Builds SUSE Multi-Linux Manager documentation
      - manager-5.2  # ADD: Builds SUSE Multi-Linux Manager documentation

Steps:

Open .github/workflows/test_pdf_translations.yml
Add new major release branch with appropriate comment
Ensure consistent formatting with existing entries

4. Translation File Updates (`update_translation_files.yml`)

Purpose: Updates translation files for documentation changes

Current Configuration:

name: Update translation files
on:
  push:
    branches:
      - 'master'
      - 'manager-4.3'
      - 'manager-4.3-MU-4.3.[0-9][0-9]?'         # 4.3 MU branches
      - 'manager-5.0'
      - 'manager-5.0-MU-5.0.[0-9][0-9]?'         # 5.0 MU branches
      - 'manager-5.1'
      - 'manager-5.1-MU-5.1.[0-9][0-9]?'         # 5.1 MU branches

Update Process:

When creating SUSE Multi-Linux Manager 5.2 (example):

name: Update translation files
on:
  push:
    branches:
      - 'master'
      - 'manager-4.3'
      - 'manager-4.3-MU-4.3.[0-9][0-9]?'         # 4.3 MU branches
      - 'manager-5.0'
      - 'manager-5.0-MU-5.0.[0-9][0-9]?'         # 5.0 MU branches
      - 'manager-5.1'
      - 'manager-5.1-MU-5.1.[0-9][0-9]?'         # 5.1 MU branches
      - 'manager-5.2'                             # ADD: New major release
      - 'manager-5.2-MU-5.2.[0-9][0-9]?'         # ADD: 5.2 MU branches

Steps:

Open .github/workflows/update_translation_files.yml
Add new major release branch
Add maintenance update pattern for new version
Include comments for clarity

Complete Update Workflow

Pre-Update Checklist

Before making changes:

New major release branch has been created and pushed
Branch naming follows established conventions
Team has been notified of the update schedule
Backup of current workflow files completed

Update Sequence

Recommended order for updates:

Development builds (build_and_archive_devel_docs.yml)
- Add new major branch immediately after creation
- Test with sample commit to new branch
Translation updates (update_translation_files.yml)
- Add major branch and MU pattern
- Ensure translation workflows function
PDF translation testing (test_pdf_translations.yml)
- Add new branch for translation testing
- Verify PDF generation works
Release builds (build_and_archive_release_docs.yml)
- Add complete release cycle patterns
- Most complex update - requires all patterns

Testing and Validation

After each file update:

Syntax validation:

# Validate YAML syntax
yamllint .github/workflows/filename.yml

Commit and monitor:

git add .github/workflows/
git commit -m "Add SUSE Multi-Linux Manager 5.2 to GitHub Actions workflows"
git push

Workflow verification:
- Check GitHub Actions tab for syntax errors
- Monitor first builds on new branches
- Verify workflows trigger correctly

Testing checklist:

YAML syntax is valid
Workflows trigger on new branch commits
Build processes complete successfully
No workflow failures or errors
Translation processes function correctly

Maintenance Update Considerations

Adding Maintenance Branches

When maintenance update branches are created:

Most maintenance updates are already covered by regex patterns:

manager-5.0-MU-5.0.[0-9][0-9]? covers MU branches like manager-5.0-MU-5.0.16
Patterns support single and double-digit MU numbers

Manual updates only needed for:

Non-standard maintenance branch naming
Special release branches (alpha, beta, RC)
Emergency or hotfix branches

Pattern Explanations

Regex Pattern Breakdown:

'manager-5.0-MU-5.0.[0-9][0-9]?'

manager-5.0-MU-5.0. - Literal prefix
[0-9] - Single digit (required)
[0-9]? - Second digit (optional)
Matches: 5.0.1, 5.0.16, 5.0.99

Version-specific patterns:

Each major version needs its own MU pattern
Patterns must be updated for each new major release
Use consistent formatting across all workflow files

Troubleshooting

Common Issues

YAML Syntax Errors:

# Incorrect indentation
branches:
- 'master'
  - 'manager-5.0'  # Wrong indentation

# Correct indentation
branches:
  - 'master'
  - 'manager-5.0'

Pattern Matching Problems:

# Too restrictive - won't match double digits
'manager-5.0-MU-5.0.[0-9]'

# Correct - matches single and double digits  
'manager-5.0-MU-5.0.[0-9][0-9]?'

Branch Not Triggering:

Verify branch name matches pattern exactly
Check for typos in workflow file
Confirm branch exists and has commits
Review GitHub Actions logs for errors

Recovery Procedures

If workflows break after updates:

Immediate rollback:
```
git revert <commit-hash>
git push
```
Fix and reapply:
- Identify specific syntax or pattern error
- Fix in local copy
- Test YAML syntax locally
- Commit and push corrected version
Manual workflow dispatch:
- Use GitHub UI to manually trigger workflows
- Test with known good branch first
- Verify fixes before automatic triggers

Annual Update Checklist

Complete Workflow Update Process

When creating new major release (e.g., SUSE Multi-Linux Manager 5.2):

Phase 1: Preparation

Create and verify new major release branch exists
Backup current workflow files
Plan update sequence and timing
Notify team of scheduled updates (freeze)

Phase 2: File Updates

Update build_and_archive_devel_docs.yml
Update update_translation_files.yml
Update test_pdf_translations.yml
Update build_and_archive_release_docs.yml

Phase 3: Testing

Validate YAML syntax for all files
Test development build workflows
Verify translation workflows function
Test release build patterns
Monitor first automated builds

Phase 4: Documentation

Update this document with new version examples
Document any special cases or exceptions
Update team documentation and runbooks
Archive old version information if needed

Post-Update Monitoring

First day after updates:

Monitor all workflow executions
Check for any failures or errors
Verify builds complete successfully
Confirm translation updates work correctly

First week after updates:

Review workflow performance and timing
Identify any optimization opportunities
Document lessons learned
Plan improvements for next annual update

This annual update process ensures that GitHub Actions workflows remain current and functional for all SUSE Multi-Linux Manager documentation releases and maintenance updates.

Overview​

Affected Workflow Files​

Primary Workflow Files Requiring Updates​

File Locations​

Update Procedures​

1. Development Branch Builds (build_and_archive_devel_docs.yml)​

2. Release Branch Builds (build_and_archive_release_docs.yml)​

3. PDF Translation Testing (test_pdf_translations.yml)​

4. Translation File Updates (update_translation_files.yml)​

Complete Update Workflow​

Pre-Update Checklist​

Update Sequence​

Testing and Validation​

Maintenance Update Considerations​

Adding Maintenance Branches​

Pattern Explanations​

Troubleshooting​

Common Issues​

Recovery Procedures​

Annual Update Checklist​

Complete Workflow Update Process​

Post-Update Monitoring​

Overview

Affected Workflow Files

Primary Workflow Files Requiring Updates

File Locations

Update Procedures

1. Development Branch Builds (`build_and_archive_devel_docs.yml`)

2. Release Branch Builds (`build_and_archive_release_docs.yml`)

3. PDF Translation Testing (`test_pdf_translations.yml`)

4. Translation File Updates (`update_translation_files.yml`)

Complete Update Workflow

Pre-Update Checklist

Update Sequence

Testing and Validation

Maintenance Update Considerations

Adding Maintenance Branches

Pattern Explanations

Troubleshooting

Common Issues

Recovery Procedures

Annual Update Checklist

Complete Workflow Update Process

Post-Update Monitoring