Import a theme from GitHub

Where is the theme installed?

Not on GitPress.net’s servers, and not copied into your posts repo. The private data repo’s gitpress.json only stores a pointer, for example:

"theme": {
  "name": "classic",
  "source": "builtin",
  "ref": "v1",
  "config": { "showAvatar": true }
}

Built-in themes have source builtin. They actually come from the official public repo tap6/gitpress under themes/theme-name/, pinned to tag v1. An imported theme is written as github:owner/repo#branch-or-tag.

What happens after “Add to my themes”

1. The admin first fetches that repo’s theme.json and checks it is GitPress spec v1 with engine Astro.
2. The repo URL is added to this site’s “my imports” list (on the GitPress control plane, not in your posts repo). The theme is not switched yet, and nothing is rebuilt.
3. Only after you tap “Enable” on Appearance is the pointer written into the data repo gitpress.json.
4. That push on the data repo triggers GitHub Actions.
5. The Action git clones the theme repo on GitHub’s build machine, mounts your posts and images, and runs astro build.
6. Only compiled HTML/CSS is pushed to the public site repo for GitHub Pages. Theme source does not stay in the site repo.

The three form fields

GitHub repo

owner/repo works, or paste the browser URL, including pages with /tree/main/themes/xxx. The repo must be public — the build machine clones anonymously and cannot read private repos.

Subdirectory (optional)

Leave empty if the whole repo is one theme. If it lives in something like themes/aurora, fill that path. The root or that subdirectory must contain theme.json.

Branch / tag

Prefer a pinned tag (such as v1) over a branch that might be force-pushed. If you leave it empty and the URL has no branch, we try v1 by default.

What import does not do

• It does not upload a zip or theme files to GitPress.net.
• It does not change your posts, images, or categories; switching a theme only changes presentation.
• It does not leave an editable copy of the theme in the public site repo. The next build clones the pinned version again.
• If the author later updates the theme on GitHub, your site still uses the ref written at enable time. To upgrade, change the URL in the list or the ref in gitpress.json, then rebuild.

Common failures

• The repo is private, or owner/repo is wrong.
• The branch/tag does not exist, or the subdirectory has no theme.json.
• theme.json specVersion is not 1, or engine is not astro.
• The theme can be read, but Astro errors at build time (missing deps, paths that don’t match the mount contract). Then check the data repo’s Actions log.