Publishing a Roq Site

Roq GitHub Action

Roq provides a GitHub action to publish to GitHub pages or other services.

To GitHub Pages

Check if you already have the .github/workflows/deploy.yml file, if you don’t create it:

.github/workflows/deploy.yml

## Deploy to GH-Pages for your Quarkus Roq site.
name: Roq Site Deploy

on:
  push:
    branches: [ main ]   # Switch to the branch which should be deployed to GitHub Pages
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Roq Site
        uses: quarkiverse/quarkus-roq@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}   # Used to automatically get the GitHub Pages url
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Then to enable GitHub Pages:

Open your GitHub repository page
Go to Settings→Page
Pick: Source: GitHub Actions, that’s enough (no save button)

It’s all good, restart your deploy workflow and enjoy!

To other services

.github/workflows/deploy-other.yml

## Deploy to another service for your Quarkus Roq site.
name: Roq Site Deploy other

on:
  push:
    branches: [ main ]   # Switch to the branch which should be deployed to GitHub Pages
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Roq Site
        uses: quarkiverse/quarkus-roq@v1
        with:
          github-pages: false
      - name: Publishing blog
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: target/roq
          retention-days: 3

This will create a GitHub artifact named site that you can download from another job (or another workflow). For example, the PR Preview workflow of Roq publishes to Surge.

Building Roq

Roq is based on Quarkus, you just need to set up a JDK to build your Roq site using this command:

export QUARKUS_ROQ_GENERATOR_BATCH=true
./mvnw -B package quarkus:run

Other CIs

Using the command above should be easy to configure on any CI.

if you created a configuration for a given CI which could help others, please share it here 🙏

Gitlab CI

Add this file at the root of your Gitlab repository

.gitlab-ci.yml

stages:
  - build
  - deploy

build_roq:
  # Look for appropriate maven docker images in https://hub.docker.com/_/maven/tags
  image: "maven:3.9.9-eclipse-temurin-23-alpine"
  stage: build
  # Generate the static site on merge request events and on the main branch
  script:
    - QUARKUS_ROQ_GENERATOR_BATCH=true mvn -B -q package quarkus:run
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  artifacts:
    reports:
      junit: target/surefire-reports/*.xml
    paths:
      - target/roq
      - target/surefire-reports

deploy_roq:
  image: alpine
  pages: true
  stage: deploy
  # For main branch take the artifacts from `build_roq` and deploy them.
  needs:
    - build_roq
  script:
    - cp -R target/roq public
    - echo "Quarkus Roq static site deployed to Gitlab Pages at $CI_PAGES_URL"
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  artifacts:
    paths:
      - public

If everything goes well the pipeline will deploy, the url of the deployment is found via these options:

Console output of deploy_roq job.
Clicking Deploy ⇒ Pages on the project sidebar
Navigating to the url https://gitlab.example.com/user-or-organization/projectpath/project/pages