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:

• using with a custom domain;
• using with a wildcard domain (matching);
• using with a wildcard domain (non-matching).

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: Publish
on:
  push:
jobs:
  publish:
    runs-on: codeberg-tiny
    steps:
      - uses: actions/checkout@v5
      - run: |
          # Use your favorite static site generator here!
          mkdir _site
          cp *.html _site/
      - uses: actions/git-pages@v2
        with:
          site: https://example.org/
          server: grebedoc.dev
          password: ${{ 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: Publish
on:
  push:
jobs:
  publish:
    runs-on: codeberg-tiny
    steps:
      - uses: actions/checkout@v5
      - run: |
          # Use your favorite static site generator here!
          mkdir _site
          cp *.html _site/
      - uses: actions/git-pages@v2
        with:
          # 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: Publish
on:
  push:
jobs:
  publish:
    runs-on: codeberg-tiny
    steps:
      - uses: actions/checkout@v5
      - run: |
          # Use your favorite static site generator here!
          mkdir _site
          cp *.html _site/
      - uses: actions/git-pages@v2
        with:
          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