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>.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;
• with a wildcard domain (matching);
• with a wildcard domain (matching pull request);
• with a wildcard domain (non-matching).

With a custom domain

A Forgejo Actions automatic token is sufficient provided the domain has an appropriate DNS record published and the server runs git-pages 0.8.0 or a later version. To allow a Forgejo Actions workflow in a repository https://codeberg.org/username/reponame.git to publish a site on a domain domainname.tld, add the following DNS record:

_git-pages-forge-allowlist.domainname.tld. TXT "https://codeberg.org/username/reponame.git"

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://domainname.tld/ using Forge DNS Allowlist Authorization:

name: Publish
on:
  push:
    branches: [main]
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://domainname.tld/
          server: codeberg.page
          token: ${{ forge.token }}
          source: _site/

This workflow assumes that the hosting provider is https://codeberg.page; change the server option when using a different provider.

To publish multiple sites on the same domain (e.g. independently built documentation for a few related projects), several _git-pages-forge-allowlist TXT records may be used.

As an alternative, the password-based DNS Challenge Authorization method can be used, but is not recommended in cases where Forge DNS Allowlist Authorization is available.

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.codeberg.page/ using Forge Wildcard Authorization:

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/
      - if: ${{ forge.event_name == 'push' && forge.event.ref == 'refs/heads/main' }}
        uses: actions/git-pages@v2
        with:
          site: https://${{ forge.event.repository.owner.username }}.codeberg.page/${{ forge.event.repository.name }}/
          token: ${{ forge.token }}
          source: _site/

With a wildcard domain (matching pull request)

Special functionality is included to publish previews of a website, project documentation, etc. built from pull requests by using only an unprivileged Forgejo Actions automatic token and without using insecure pull_request_target workflows.

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.preview.codeberg.page/website@123/ using Forge Wildcard Authorization:

name: Publish
on:
  pull_request:
jobs:
  publish:
    runs-on: codeberg-tiny
    steps:
      - uses: actions/checkout@v5
      - run: |
          # Use your favorite static site generator here!
          mkdir _site
          cp *.html _site/
      - if: ${{ forge.event_name == 'pull_request' }}
        uses: actions/git-pages@v2
        with:
          site: https://${{ forge.event.repository.owner.username }}.preview.codeberg.page/${{ forge.event.repository.name }}@${{ forge.event.number }}/
          token: ${{ forge.token }}
          source: _site/

This workflow can be combined with the workflow from the previous section by including both on: triggers and both uses: actions/git-pages@v2 steps in the same job.

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/ using Forge Wildcard Authorization:

name: Publish
on:
  push:
    branches: [main]
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://${{ forge.event.repository.owner.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 B on Grebedoc).
• token (optional): the token for Forge DNS Allowlist Authorization and Forge Wildcard Authorization methods.
• source (required): the directory containing site contents; e.g. if it is _site, then the index page will be uploaded from _site/index.html.
• expires (optional): the lifetime of the published site; if provided and the server allows it, the site will be removed after approximately this many days.

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