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 (or PASSWORD) 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:v6
    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 (mandatory if not using PASSWORD)
SERVER	Server at which git-pages is hosted (needed for first deploy with custom domain)
EXPIRES	Number of days after which the website will expire (if enabled on git-pages server)
PASSWORD	Password to authenticate (mandatory 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
DELETE	Delete site	false
PRETTY_URLS	Normalize URLs of *.html files by stripping the extension	false