Investigate serving branch versions

ric commented

2025-12-04 21:47:08 +00:00

Owner

Investigate how we can serve sites from branches in git to allow for stage etc.

ric self-assigned this

2025-12-04 21:47:08 +00:00

ric added this to the Roadmap project

2025-12-04 21:47:08 +00:00

ric added the

enhancement

label

2025-12-04 21:49:27 +00:00

ric added this to the 0.2.0 - Branch sites milestone

2025-12-04 21:49:32 +00:00

ric commented

2025-12-04 21:59:29 +00:00

Author

Owner

Based on my exploration, here's the current state and possible approaches for serving different branches:

Current State

The plugin only serves from the repository's default branch (main/master). While it fetches the default branch name from the
Forgejo API, it doesn't actually use it - all file requests go to the default branch implicitly.

Design Options for Multi-Branch Support

Option 1: URL-Based Branch Selection

Add branch to the URL path, similar to how Netlify/Vercel handle branch deploys:

URL patterns:

https://username.pages.domain/repo/branch/path/to/file.html
https://branch--username.pages.domain/repo/path/to/file.html (subdomain-based)
https://username.pages.domain/repo@branch/path/to/file.html (@ separator)

Pros:

Access any branch without configuration
Great for preview/staging branches
No .pages file changes needed

Cons:

More complex URL parsing
Potential conflicts with file paths named after branches

Option 2: Configuration-Based (.pages file)

Add a branch: field to the .pages configuration:

enabled: true
branch: develop
custom_domain: example.com

Pros:

Simple, clean URLs remain unchanged
Explicit per-repository control
No URL parsing complexity

Cons:

Can only serve one branch per repository
Need to modify .pages file to switch branches

Option 3: Hybrid Approach

Default branch specified in .pages file
URL-based override for accessing other branches

Pros:

Best of both worlds
Production on configured branch, previews via URL

Cons:

Most complex to implement

Implementation Changes Needed

All options require modifying:

forgejo_client.go:165 - Add ?ref={branch} query parameter
forgejo_client.go:65-71 - Add branch to PagesConfig struct (Option 2/3)
pages.go - Pass branch through the request chain
cache.go - Include branch in cache keys

Based on my exploration, here's the current state and possible approaches for serving different branches: Current State The plugin only serves from the repository's default branch (main/master). While it fetches the default branch name from the Forgejo API, it doesn't actually use it - all file requests go to the default branch implicitly. Design Options for Multi-Branch Support Option 1: URL-Based Branch Selection Add branch to the URL path, similar to how Netlify/Vercel handle branch deploys: URL patterns: - https://username.pages.domain/repo/branch/path/to/file.html - https://branch--username.pages.domain/repo/path/to/file.html (subdomain-based) - https://username.pages.domain/repo@branch/path/to/file.html (@ separator) Pros: - Access any branch without configuration - Great for preview/staging branches - No .pages file changes needed Cons: - More complex URL parsing - Potential conflicts with file paths named after branches Option 2: Configuration-Based (.pages file) Add a branch: field to the .pages configuration: enabled: true branch: develop custom_domain: example.com Pros: - Simple, clean URLs remain unchanged - Explicit per-repository control - No URL parsing complexity Cons: - Can only serve one branch per repository - Need to modify .pages file to switch branches Option 3: Hybrid Approach - Default branch specified in .pages file - URL-based override for accessing other branches Pros: - Best of both worlds - Production on configured branch, previews via URL Cons: - Most complex to implement Implementation Changes Needed All options require modifying: - forgejo_client.go:165 - Add ?ref={branch} query parameter - forgejo_client.go:65-71 - Add branch to PagesConfig struct (Option 2/3) - pages.go - Pass branch through the request chain - cache.go - Include branch in cache keys

ric commented

2025-12-04 22:06:46 +00:00

Author

Owner

Query based approach:

The Problem

If you visit:
https://username.pages.domain/repo/?branch=develop

And the page contains internal links like:
About
Contact
Blog

Clicking any of those links would drop the ?branch=develop parameter and fall back to the default branch. Users would
constantly jump between branches - terrible UX!

Solutions

Option 1: Cookie-Based Persistence ⭐ (Best for browsers)

When the plugin sees ?branch=develop:

Set a cookie: pages-branch=develop
Use cookie value for all subsequent requests
Query parameter can override cookie
Cookie expires after session/time period

User flow:

Visit: https://username.pages.domain/repo/?branch=develop
→ Cookie set: pages-branch=develop
Click link:
→ Navigates to: /about.html
→ Cookie still says: develop
→ Serves from develop branch ✓

Want to switch back? Visit: ?branch=main
→ Cookie updated to main

Pros:

Persistent across navigation
Only need ?branch= once
Natural browser behavior
Can still share ?branch= links

Cons:

Requires cookie support
Need to consider cookie scope/expiry

Option 2: Path-Based Routing

https://username.pages.domain/repo/~develop/index.html
https://username.pages.domain/repo/~develop/about.html

Pros:

No cookies needed
Works with relative links (./about.html)

Cons:

Breaks absolute links unless carefully constructed
Requires path rewriting awareness from site authors

Option 3: Hybrid (Cookie + Query + Header)

Cookie: Persistence for browsers
Query param: Initial selection & override
Header: For API/testing

Priority: ?branch= > X-Pages-Branch > Cookie > .pages config > default

This gives the best of all worlds!

Query based approach: The Problem If you visit: https://username.pages.domain/repo/?branch=develop And the page contains internal links like: <a href="/about.html">About</a> <a href="contact.html">Contact</a> <a href="/repo/blog/post.html">Blog</a> Clicking any of those links would drop the ?branch=develop parameter and fall back to the default branch. Users would constantly jump between branches - terrible UX! Solutions Option 1: Cookie-Based Persistence ⭐ (Best for browsers) When the plugin sees ?branch=develop: 1. Set a cookie: pages-branch=develop 2. Use cookie value for all subsequent requests 3. Query parameter can override cookie 4. Cookie expires after session/time period User flow: 1. Visit: https://username.pages.domain/repo/?branch=develop → Cookie set: pages-branch=develop 2. Click link: <a href="/about.html"> → Navigates to: /about.html → Cookie still says: develop → Serves from develop branch ✓ 3. Want to switch back? Visit: ?branch=main → Cookie updated to main Pros: - Persistent across navigation - Only need ?branch= once - Natural browser behavior - Can still share ?branch= links Cons: - Requires cookie support - Need to consider cookie scope/expiry Option 2: Path-Based Routing https://username.pages.domain/repo/~develop/index.html https://username.pages.domain/repo/~develop/about.html Pros: - No cookies needed - Works with relative links (./about.html) Cons: - Breaks absolute links unless carefully constructed - Requires path rewriting awareness from site authors Option 3: Hybrid (Cookie + Query + Header) - Cookie: Persistence for browsers - Query param: Initial selection & override - Header: For API/testing Priority: ?branch= > X-Pages-Branch > Cookie > .pages config > default This gives the best of all worlds!

Rows
Columns

Investigate serving branch versions #13