GitHub Pages Deployment

GitHub Pages Deployment

Maven Skin includes a ready-to-use GitHub Actions workflow for automatic deployment to GitHub Pages.

Setup

1. Add the Workflow File

Create .github/workflows/pages.yml:

name: Deploy Site

on:
  push:
    branches: ["main"]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: actions/setup-java@v5
        with:
          java-version: 25
          distribution: 'temurin'
          cache: 'maven'

      - run: mvn -B -ntp verify site site:stage -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false -Dmaven.wagon.httpconnectionManager.ttlSeconds=120

      - uses: actions/configure-pages@v6

      - uses: actions/upload-pages-artifact@v5
        with:
          path: 'target/staging'

      - uses: actions/deploy-pages@v5

2. Enable GitHub Pages

In your GitHub repository:

  1. Go to Settings → Pages
  2. Under "Build and deployment", select "GitHub Actions"
  3. The workflow will automatically deploy to the gh-pages branch

3. Test the Workflow

Push to main branch:

git add .github/workflows/pages.yml
git commit -m "Add GitHub Pages deployment workflow"
git push origin main

Visit GitHub repository Actions tab to see the workflow run.

After successful deployment, your site will be available at:

Custom Domain Setup

To use a custom domain like maven-skin.verron.pro:

1. DNS Configuration

Point your domain to GitHub Pages:

Option A: Using A Records (IPv4)

A       185.199.108.153
A       185.199.109.153
A       185.199.110.153
A       185.199.111.153

Option B: Using ALIAS/ANAME Record (recommended)

ALIAS/ANAME  yourusername.github.io

2. GitHub Pages Settings

In your GitHub repository:

  1. Go to Settings → Pages
  2. Under "Custom domain", enter your domain: maven-skin.verron.pro
  3. Check "Enforce HTTPS" (recommended)
  4. GitHub will automatically create a CNAME file in your repository

3. Verify DNS

After 10-15 minutes, verify DNS resolution:

dig maven-skin.verron.pro
nslookup maven-skin.verron.pro

Your site should now be accessible at your custom domain!

Troubleshooting

Build Errors

Error: "Cannot find descriptor for mojo 'org.apache.maven.plugins:maven-site-plugin:…​'

Solution: Update Maven Site Plugin:

mvn versions:display-dependency-updates
mvn clean install

Site Generation Issues

Error: "Executing copy-resources failed"

Solution: Check file permissions and paths:

# Ensure src/site directory exists
mkdir -p src/site/asciidoc

# Clean and rebuild
mvn clean site

GitHub Pages Not Updating

Issue: Changes don’t appear on GitHub Pages

Solutions: 1. Wait 2-3 minutes for deployment 2. Check Actions tab for workflow status 3. Verify custom domain CNAME file exists 4. Clear browser cache 5. Try incognito/private browser window

Deployment Workflow Fails

Check the workflow logs:

  1. Go to your GitHub repository
  2. Click Actions tab
  3. Click on the failed workflow run
  4. Review the logs for error messages

Common causes: * Maven build failure (check mvn site locally) * GitHub Pages disabled (check Settings → Pages) * Insufficient permissions (check workflow permissions)