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: 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@v1
        with:
          site: https://example.org/
          server: grebedoc.dev
          password: ${{ secrets.SITE_PASSWORD }}
          path: _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@v1
        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 }}
          path: _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@v1
        with:
          site: https://username.codeberg.page/
          token: ${{ secrets.GIT_PAGES_TOKEN }}
          path: _site/

Reference

Action parameters (provided via with:):

• site (required): the URL (http:// or https://) of a site where the contents should appear after publishing.
• server: (optional): the hostname of a git-pages server publishing the site; if provided, publishing the first site to a domain via HTTPS becomes possible.
• password (optional): the password for DNS Challenge authorization method (Method B on Grebedoc).
• token (optional): the token for Forge authorization method.
• path (required): the directory containing site contents; e.g. if it is _site, then the index page will be uploaded from _site/index.html.

License

0-clause BSD