4
5
Fork
You've already forked action
0
Forgejo Action for uploading a directory to a git-pages site
2025年12月20日 11:59:34 +00:00
action.yml Always use create-parents: true semantics. 2025年12月04日 19:08:24 +00:00
LICENSE-0BSD.txt Add documentation. 2025年11月16日 03:07:33 +00:00
README.md Fix lingering @v1 in README. 2025年12月20日 11:59:34 +00:00

action/git-pages

action/git-pages is a Forgejo Action for uploading sites to git-pages. It is a wrapper around git-pages-cli to simplify its use in CI workflows.

Usage

This Forgejo Action supports publishing to custom domains as well as wildcard domains (e.g. <username>.grebedoc.dev or <username>.codeberg.page). It must be invoked differently depending on the kind of domain you are publishing to, and whether the site URL matches the repository you are publishing from:

With a custom domain

The following example workflow, which you can put into .forgejo/workflows/publish.yaml, checks out the repository, performs a placeholder build step, and publishes the built site contents to https://example.org/:

name:Publishon:push:jobs:publish:runs-on:codeberg-tinysteps:- uses:actions/checkout@v5- run:| # Use your favorite static site generator here!
 mkdir _site
 cp *.html _site/- uses:actions/git-pages@v2with:site:https://example.org/server:grebedoc.devpassword:${{ secrets.SITE_PASSWORD }}source:_site/

With a wildcard domain (matching)

To publish to a matching site URL on a wildcard domain (e.g. repository https://codeberg.org/username/reponame.git to https://username.codeberg.page/reponame/), a Forgejo Actions automatic token is sufficient and it is not necessary to generate an access token.

The following example workflow, which you can put into .forgejo/workflows/publish.yaml, checks out the repository, performs a placeholder build step, and publishes the built site contents to https://username.grebedoc.dev/:

name:Publishon:push:jobs:publish:runs-on:codeberg-tinysteps:- uses:actions/checkout@v5- run:| # Use your favorite static site generator here!
 mkdir _site
 cp *.html _site/- uses:actions/git-pages@v2with:# This workflow will only work correctly in https://codeberg.org/username/reponame.git !# Adjust the site name to match your username and repository name.# To publish to the index site, https://username.codeberg.page/, name your repository# either `username.codeberg.page` or `pages`.site:https://username.codeberg.page/reponame/token:${{ forge.token }}source:_site/

With a wildcard domain (non-matching)

To publish to a non-matching site URL on a wildcard domain (i.e. any site corresponding to an existing repository you have push permissions for) you will need to generate and store a Forgejo access token. To generate a token, follow the instructions from git-pages-cli documentation. To securely store a token:

  1. Open Settings > Actions > Secrets.
  2. Click Add secret.
  3. Set Name to GIT_PAGES_TOKEN. (You can pick a different name, but change it in the workflow below if you do.)
  4. Set Value to the access token you've generated earlier.
  5. Click Confirm.
  6. Erase any other record of the access token.

The following example workflow, which you can put into .forgejo/workflows/publish.yaml, checks out the repository, performs a placeholder build step, and publishes the built site contents to https://username.codeberg.page/:

name:Publishon:push:jobs:publish:runs-on:codeberg-tinysteps:- uses:actions/checkout@v5- run:| # Use your favorite static site generator here!
 mkdir _site
 cp *.html _site/- uses:actions/git-pages@v2with:site:https://username.codeberg.page/token:${{ secrets.GIT_PAGES_TOKEN }}source:_site/

Reference

Action inputs (provided via with:):

  • site (required): the URL (http:// or https://) of a site being published.
  • path (optional): if provided, the directory will be uploaded to this path underneath the site URL; site contents outside of the given path will remain unchanged.
  • server (optional): the hostname of a git-pages server publishing the site; if provided, the initial publishing of a site to a custom domain can be done via HTTPS.
  • password (optional): the password for DNS Challenge authorization method (Method B on Grebedoc).
  • token (optional): the token for Forge authorization method.
  • source (required): the directory containing site contents; e.g. if it is _site, then the index page will be uploaded from _site/index.html.

The URL where the site contents will be available is the result of joining site and path, for example:

  • With site: "https://domain.tld" and path: "", contents will be available at https://domain.tld/.
  • With site: "https://domain.tld/project/" and path: "", contents will be available at https://domain.tld/project/.
  • With site: "https://domain.tld/preview/" and path: "pr/190", contents will be available at https://domain.tld/preview/pr/190/.

License

0-clause BSD