GitHub Integration

GitHub Integration for Documentation Editing

This guide covers the GitHub integration features that make content editing seamless for team members.

Features Enabled

1. Edit This Page Links

Every documentation page includes an “Edit this page” link that:

• Opens the source file directly in GitHub editor
• Pre-populates commit message for quick edits
• Creates pull requests for review workflow

Configuration (already set in hugo.yaml):

params:
  github_repo: https://github.com/latts-ie/wiki-internal
  github_branch: main
  edit_page: true
  create_issue: true

2. GitHub Actions Workflow

The comprehensive deployment workflow provides:

Automatic Deployment:

• Production deployment on main branch pushes
• Preview deployments for pull requests
• Comment updates with preview URLs

Quality Assurance:

• Hugo build validation
• Content testing and verification
• Performance monitoring

Workflow Location: .github/workflows/deploy.yml

3. Repository Settings

Branch Protection (recommended configuration):

Main branch protection:
☑ Require pull request reviews before merging
☑ Require status checks to pass before merging  
☑ Require branches to be up to date before merging
☑ Include administrators
☑ Allow force pushes (disabled)
☑ Allow deletions (disabled)

Content Editing Workflows

Quick Edits (Using GitHub Web Editor)

1. Navigate to any documentation page
2. Click “Edit this page” link in top right
3. Make changes in GitHub web editor
4. Add commit message: Brief description of changes
5. Choose commit option:
   • Direct to main (for minor fixes)
   • Create new branch and pull request (recommended)

Advanced Edits (Local Development)

1. Clone repository:

   git clone https://github.com/latts-ie/wiki-internal.git
   cd wiki-internal
   

2. Create feature branch:

   git checkout -b docs/update-section-name
   

3. Make changes locally:

   make serve  # Test changes locally
   make test   # Validate changes
   

4. Commit and push:

   git add .
   git commit -m "Update section with new information"
   git push origin docs/update-section-name
   

5. Create pull request through GitHub interface

Pull Request Workflow

Automated PR Actions

When a PR is created:

1. Build Validation: Ensures Hugo can build the site
2. Preview Deployment: Creates preview version on Cloudflare Pages
3. Comment Update: Bot adds preview URL to PR comments
4. Status Checks: All tests must pass before merge

PR Review Process

For Contributors:

• Clear, descriptive PR title and description
• Link to related issues (if applicable)
• Test locally before submitting
• Respond to review feedback promptly

For Reviewers:

• Check content accuracy and clarity
• Verify formatting and structure
• Test links and functionality
• Review mobile responsiveness

Merge Requirements

Before merging, ensure:

• All status checks pass (build, tests)
• At least one approving review
• No unresolved conversations
• Preview deployment looks correct
• Content follows style guidelines

GitHub Repository Configuration

Required Settings

Secrets (for deployment):

CLOUDFLARE_API_TOKEN: [Your Cloudflare API token]
CLOUDFLARE_ACCOUNT_ID: [Your Cloudflare account ID]

Repository Settings:

Settings → General:
☑ Issues enabled
☑ Projects enabled  
☑ Wiki disabled (using docs instead)
☑ Preserve this repository (important!)

Settings → Code security and analysis:
☑ Dependency graph
☑ Dependabot alerts
☑ Dependabot security updates

Branch Protection Rules

Main Branch Protection:

Settings → Branches → Add rule

Branch name pattern: main

Protect matching branches:
☑ Require pull request reviews before merging
  ☑ Require review from code owners
  ☑ Dismiss stale PR approvals when new commits are pushed
☑ Require status checks to pass before merging
  ☑ Require branches to be up to date before merging
  Status checks: build, test (from GitHub Actions)
☑ Require conversation resolution before merging
☑ Include administrators
☐ Allow force pushes
☐ Allow deletions

Integration Benefits

For Content Authors

• No Technical Setup: Edit directly in browser
• Instant Previews: See changes before they go live
• Version Control: Full history of all changes
• Collaboration: Team review and approval process

For Developers

• Automated Deployment: No manual deployment steps
• Quality Gates: Automated testing prevents broken builds
• Preview Environments: Test changes in production-like environment
• Audit Trail: Complete history of all site changes

For Administrators

• Access Control: GitHub team-based permissions
• Security: All changes tracked and attributed
• Compliance: Full audit trail for content changes
• Scalability: Self-service content updates for team

Troubleshooting

Edit Links Not Working

Symptoms: “Edit this page” links go to wrong repository or 404

Solution: Verify hugo.yaml configuration:

params:
  github_repo: https://github.com/latts-ie/wiki-internal
  github_branch: main

PR Deployments Failing

Symptoms: Preview deployments not created for pull requests

Checklist:

• GitHub secrets configured correctly
• Workflow file present at .github/workflows/deploy.yml
• Branch protection not blocking workflow runs
• Cloudflare Pages project connected to repository

Permission Issues

Symptoms: Team members can’t create PRs or edit content

Solution: Check GitHub repository permissions:

Settings → Manage access
- Add team members with "Write" access minimum
- Configure team-based permissions for organization

Best Practices

Content Management

• Small, Focused Changes: One topic per PR
• Clear Commit Messages: Describe what and why
• Test Locally: Use make serve for complex changes
• Mobile Testing: Verify responsive design

Collaboration

• Review Promptly: Don’t let PRs sit idle
• Constructive Feedback: Focus on content improvement
• Document Decisions: Use PR comments for context
• Share Knowledge: Cross-train team members

Security

• Review External Links: Verify all URLs are appropriate
• Sanitize Content: No sensitive information in commits
• Regular Audits: Review contributor access quarterly
• Emergency Procedures: Document rollback process

This GitHub integration creates a professional, scalable documentation workflow that empowers your entire team to contribute while maintaining quality and security standards.