Skip to content

Prepare the move of the site to owaspacs.org - #416

Merged
rocklambros merged 1 commit into
integrationfrom
feat/216-owaspacs-domain
Nov 1, 2026
Merged

rocklambros merged 1 commit into
integrationfrom
feat/216-owaspacs-domain

Conversation

@rocklambros

Copy link
Copy Markdown
Collaborator

What changed

Prepares the move of the ACS site from the github.io project subpath to the apex domain owaspacs.org. This merges only after DNS resolves and the domain is bound in the Pages setting. Do not merge it before then.

  • deploy-pages.yml writes CNAME containing owaspacs.org into _site, and its fallback URLs name the domain.
  • The navigation and roadmap monitors point at the domain. README.md, SECURITY.md, project.owasp.yaml, and CLAUDE.md follow.
  • Schema $id, $ref, and the docs links to the schemas are untouched. They stay on github.io and follow the 301.

Three things differ from what you might assume:

  1. The deploy's schema verify moved off page_url. verify_published.py requires a schema to serve the URL it was asked for. After cutover page_url is the domain, which no $id declares, so the first deploy would have failed all 44 schemas. It now checks the $id URIs, like the monitor does.
  2. CNAME does not bind the domain. GitHub's docs say a CNAME file is ignored on a site published by a custom Actions workflow. The file is here as decided, but the Pages setting is what activates the domain, and CLAUDE.md now says that.
  3. mkdocs.yml is unchanged. site_url is !ENV GITHUB_PAGES_URL, tests pin that form, and the value comes from configure-pages, which returns the domain once it is bound. Only the workflow fallback needed changing. The landing links and the CSP are relative or hash-only, so neither depends on the path.

Which issue does this implement

Part of #216

  • This is an editorial correction (typo, grammar, link, formatting) with no change in
    meaning, so it needs no issue

Base branch

  • integration, because this touches the specification, schemas, a reference
    implementation, an adapter, tests, or CI
  • main, because every changed path is on the documentation lane allowlist in
    CONTRIBUTING.md

Type of change

  • Specification change (schema, hooks, events, AgBOM)
  • Reference implementation or adapter
  • Documentation
  • Tooling or CI
  • Governance (licensing, security policy, contributor docs)

Cutover sequence

Order matters. Binding the domain first means the promotion's deploy builds with the domain as its base.

  1. Point the owaspacs.org apex records at GitHub Pages and confirm they resolve.
  2. Set the custom domain in the Pages setting, wait for the certificate (GitHub says up to an hour), and turn on Enforce HTTPS.
  3. Confirm https://owaspacs.org/ loads. From here github.io 301s, so the 404 page's links and the navigation monitor are wrong until step 5, which should land the same day.
  4. Mark this ready, get approval, and merge into integration.
  5. Promote to main, which redeploys.
  6. Check that Deploy Pages is green, dispatch Monitor Pages and Monitor Roadmap, then close issue Move the project domain to owaspacs.org #216 by hand.

A red navigation verify on a green deploy can be a false red, per item 4 of the PR #366 review: a status under 500 is not retried, and the per-run nonce defeats the 404 retry. Fixing that changes behavior a test pins (test_main_fails_a_wrong_status_without_retrying), so it is out of scope here. Re-running the workflow clears it.

I tested this

  • I synced my branch with the base branch before opening this
  • uv run pytest -v passes on my machine
  • uv run mkdocs build --strict passes on my machine

uv run pytest -q: 1151 passed, 1 skipped.

I built the site in deploy order with GITHUB_PAGES_URL=https://owaspacs.org/docs/ and ran the workflow's own CNAME command. _site/CNAME holds owaspacs.org, and the sitemap and canonical URLs name the domain. The only github.io path left in the built pages is /schema/.

Then I served that build from the root on a local stand-in, with a second stand-in issuing the github.io 301:

  • verify_published.py through the 301: 44 of 44.
  • verify_published.py at the domain: fails, as the commit explains.
  • verify_site_nav.py at the domain: ok.
  • 120 internal links on the landing, 404, and docs front pages: none broken.

None of this ran on real Pages. The stand-ins used rebased $id values over HTTP, so the real redirect and certificate are unproven until cutover.

Checklist

  • Commits are signed off with git commit -s (required by the DCO)
  • Prose follows STYLE.md
  • No secrets, tokens, or internal URLs in the diff

Security

  • This change has no security impact

The site moves from the github.io project subpath to the apex domain.
The deploy now writes CNAME into _site, and the site links, monitors, and
project metadata name owaspacs.org.

Schema $id values stay on github.io. The deploy's schema verify moves off
page_url to the $id URIs, because verify_published.py requires a schema to
serve the URL it was asked for, and on the custom domain page_url names a
host no $id declares. It would have failed all 44 schemas on the first
deploy after cutover. The schema monitor stays on github.io for the same
reason and proves the 301 as it goes. The navigation monitor moves to the
domain, because the verifier resolves links against the requested address
and a redirect makes the rows differ.

GitHub ignores CNAME on a site published by Actions, so the repository's
Pages setting is what binds the domain. CLAUDE.md now says so.

Part of #216

Signed-off-by: rocklambros <rock@rockcyber.com>
@github-project-automation github-project-automation Bot moved this to Needs triage in ACS Project Tracker Nov 1, 2026
@rocklambros
rocklambros marked this pull request as ready for review November 1, 2026 03:06
@rocklambros
rocklambros merged commit 0e17d35 into integration Nov 1, 2026
13 checks passed
@github-project-automation github-project-automation Bot moved this from Needs triage to Done in ACS Project Tracker Nov 1, 2026
@github-actions github-actions Bot mentioned this pull request Nov 1, 2026
@rocklambros
rocklambros deleted the feat/216-owaspacs-domain branch November 1, 2026 12:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant