Create a project website at eclipse with hugo framework

This guide is intended to help create a project website using GitHub Actions and the Hugo framework.

NOTE: The Eclipse Foundation offers a domain under eclipse.dev where project websites can be hosted. Alternatively, projects can also host their website directly on GitHub using GitHub Pages, which serves content under the organization's GitHub Pages domain, for example: https://<github-org>.github.io/<github-project-name>/

Learn more about project websites at the Eclipse Foundation by consulting the Eclipse Foundation Project Handbook.

Using Eclipse Hugo Boilerplate

If you want to use the Eclipse Hugo boilerplate, please follow instructions here: https://gitlab.eclipse.org/eclipsefdn/it/webdev/hugo-eclipsefdn-website-boilerplate

Activate GitHub Pages with otterdog (Optional)

GitHub Pages can be enabled and configured using otterdog. For more details, refer to the Otterdog documentation.

e.g:

    orgs.newRepo('Project-website') {
    ...
      gh_pages_build_type: "legacy",
      gh_pages_source_branch: "gh-pages",
      gh_pages_source_path: "/",
      ...
      environments: [
        orgs.newEnvironment('github-pages') {
          branch_policies+: [
            "gh-pages"
          ],
          deployment_branch_policy: "selected",
        },
      ],
    },

Deploy a Hugo website on a branch (GitHub Pages or not)

This example creates a new gh-pages branch in the same repository, containing the content generated by Hugo.

The gh-pages branch name is a common convention in GitHub configurations. However, the name can be changed if needed.

name: Build and Archive
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  build_website:
    name: Build and Archive
    runs-on: ubuntu-latest
    container: 
      image: eclipsefdn/hugo-node:h0.144.2-n22.14.0
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Extract Project Short Name
        id: project
        run: |
          org_name="${{ github.repository_owner }}"
          project="${org_name#eclipse-}"
          echo "project_name=$project" >> $GITHUB_OUTPUT
      - name: Build Website
        shell: bash
        run: |
          hugo --minify -b 'https://eclipse.dev/${{ steps.project.outputs.project_name }}/'
      - name: Archive
        uses: actions/upload-artifact@v4
        with:
          name: website
          path: ./public

  publish:
    if: github.ref == 'refs/heads/main'
    name: Archive and Published Builds on main
    runs-on: ubuntu-latest
    needs: [ build_website ]
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: gh-pages

      - name: Download Artifact
        uses: actions/download-artifact@v4
        with:
          name: website

      - name: Push changes
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: .

Deploy a Hugo website to a remote GitHub repository

Prerequisite: A fine-grained token named GH_PUBLISH_TOKEN must be created in order to push content to the new repository.

Please open a helpdesk issue in such case.

name: Build and Archive
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  build_website:
    name: Build and Archive
    runs-on: ubuntu-latest
    container: 
      image: eclipsefdn/hugo-node:h0.144.2-n22.14.0
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Extract Project Short Name
        id: project
        run: |
          org_name="${{ github.repository_owner }}"
          project="${org_name#eclipse-}"
          echo "project_name=$project" >> $GITHUB_OUTPUT
      - name: Build Website
        shell: bash
        run: |
          hugo --minify -b 'https://eclipse.dev/${{ steps.project.outputs.project_name }}/'
      - name: Archive
        uses: actions/upload-artifact@v4
        with:
          name: website
          path: ./public

  publish:
    if: github.ref == 'refs/heads/main'
    name: Archive and Published Builds on main
    runs-on: ubuntu-latest
    needs: [ build_website ]
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: main
          token: ${{ secrets.GH_PUBLISH_TOKEN }}

      - name: Download Artifact
        uses: actions/download-artifact@v4
        with:
          name: website

      - name: Push changes
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: .
          branch: main # default is gh-pages
          git-config-name: "<project_id> Bot [bot]"
          git-config-email: "<project_id>-actions[bot]@users.noreply.github.com"
          repository-name: "eclipse-<project_id>/eclipse-<project_id>-website-published" # remote repository
          commit-message: "Website build ${{ github.workflow }}-${{ github.run_number }}"
          token: ${{ secrets.GH_PUBLISH_TOKEN }}