Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

docs: ephemeral per-PR preview deploys for the docs site

Open
  • Is something wrong?
#675 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
github, github-actions
Domain
ci-cd, documentation

Research direction

The payload names no existing workflow file, so start by locating the current docs build workflow under .github/workflows and the docs source it builds. The proposal splits work into three workflows (build on pull_request, deploy via workflow_run to a gh-pages path under preview/pr-<n>/, and teardown on PR close), so reading how the current docs publish step authenticates is the first thing to do. Done means a docs PR gets a preview URL comment that updates in place, the fork-PR secret split is preserved, and closing the PR removes the preview path. Settle the security design with a maintainer before writing any workflow.

Written by the indexing model from the issue text.

Description

documentation enhancement github_actions
Problem Statement

Docs changes are reviewed as raw markdown diffs; rendering problems (broken links, mangled tables, asset paths) surface only after merge, when the docs workflow publishes. Reviewers can't see what a docs PR actually produces.

Proposed Solution

Three small workflows around the existing docs build:

  • build — on PRs touching docs paths, build the site and upload the artifact;
  • deploy — publish the artifact to a per-PR path (e.g. gh-pages under preview/pr-<n>/) and comment the preview URL on the PR (edit the same comment on subsequent pushes, don't stack);
  • teardown — on PR close, delete the preview path.

Keep the fork-PR security split: the build job runs on pull_request with no secrets; only the deploy step runs with write permissions via workflow_run.

Alternatives Considered
  • Review rendered output locally — works for maintainers, invisible to drive-by contributors.
  • Deploy previews to an external host (Netlify/CF Pages) — less to build, but adds a third-party dependency for a self-hosted-ethos project.
Priority

Nice to have

Dominant language
Java
Stars
35
Forks
7
Avg merge
9h 23m
Merged PRs (30d)
154

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from devops-thiago/ThrillhouseBot

All issues in devops-thiago/ThrillhouseBot

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.