git-pages-woodpecker-plugin

This plugin allows you to submit the output of your CI pipeline to a git-pages deployment – e.g. the new Codeberg Pages or grebedoc.dev by using the git-pages-cli behind the scenes.

It's particularly useful for the output of static site generations, where the simple webhook approach of git-pages would not easily work.

*Note: If you use Forgejo Actions instead of Woodpecker, a corresponding action exists.

Usage

The minimum things you will need to specify are the forgejo TOKEN and the SITE_URL. The SITE_URL specifies the URL to which the website will be deployed, the TOKEN authenticates the script against the forge.

A simple example is:

  deploy:
    image: codeberg.org/gedankenstuecke/git-pages-woodpecker-plugin:v2
    settings:
      TOKEN:
        from_secret: FORGEJO_ACCESS_TOKEN
      UPLOAD_DIR: _site
      SITE_URL: https://example.com

To create such an access token on Forgejo:

1. Open your Settings > Applications > Access tokens.
2. Select permissions, use Read under user and Read and write under repository.
3. Give a name for the token ("git-pages deployment" or similar).
4. Click Generate token.
5. Copy the token that will appear
6. Go to the Woodpecker setup you use, and add the token as a secret under /user/secrets (to use globally) or add it to the Woodpecker settings of your repository

Features

So far, not all the possible settings of git-pages-cli have been implemented, but for the vast majority of use cases it should already work.

See the full list of settings below

Settings

Parameter	Description	Default
SITE_URL	URL of the website to which you want to deploy (mandatory)
TOKEN	Token used for authentication to the forge
EXPIRES	Number of days after which the website will expire (if enabled on git-pages server)
PASSWORD	Password to authenticate (when not using tokens)
PASSWORD_FILE	File in which password is stored, if not passed as PASSWORD
PATH	Upload contents to
UPLOAD_DIR	Replace whole site with the specified directory
UPLOAD_GIT	Replace site with specified git repository