git-pages-cli

git-pages-cli is a command-line application for publishing sites to git-pages.

Tip

If you want to publish a site from a CI workflow, use the Forgejo Action instead.

Installation

You can install git-pages-cli using one of the following methods:

1. Downloading a binary. You can download the latest build or pick a release.

2. Installing a package.

   

3. Using a Docker container. Choose between the latest build or a release tag. Then run:

   $ docker run --rm codeberg.org/git-pages/git-pages-cli:latest ...
   

4. Installing from source. First, install Go 1.25 or newer. Then run:

   $ go install codeberg.org/git-pages/git-pages-cli@latest
   

Usage

To prepare a DNS challenge for a given site and password:

$ git-pages-cli https://example.org --challenge  # generate a random password
password: 28a616f4-2fbe-456b-8456-056d1f38e815
_git-pages-challenge.example.org. 3600 IN TXT "a59ecb58f7256fc5afb6b96892501007b0b65d64f251b1aca749b0fca61d582c"
$ git-pages-cli https://example.org --password xyz --challenge
_git-pages-challenge.example.org. 3600 IN TXT "6c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8"
$ git-pages-cli https://example.org --password xyz --challenge-bare
6c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8

To publish a site from a git repository available on the internet (--password may be omitted if the repository is allowlisted via DNS):

$ git-pages-cli https://example.org --upload-git https://codeberg.org/username/example.org.git
$ git-pages-cli https://example.org --password xyz --upload-git https://codeberg.org/username/example.org.git

To publish a site from a directory on your machine:

$ git-pages-cli https://example.org --password xyz --upload-dir site-contents

To delete a site:

$ git-pages-cli https://example.org --password xyz --delete

All of the operations above also accept the --dry-run option, which checks authorization only and doesn't perform any destructive operations:

$ git-pages-cli https://example.org --password zyx --delete --dry-run
result: error
unauthorized

It is not possible to publish a site to a domain for the first time using HTTPS, since the git-pages server is not allowed to acquire a TLS certificate for a domain before a site is published on that domain. Either use plain HTTP instead, or provide a hostname for which the server does have a TLS certificate using the --server option:

$ git-pages-cli https://example.org --server grebedoc.dev --password xyz --upload-dir ...

If enabled by the server administrator, it is possible to publish ephemeral sites that get automatically removed (e.g. in 14 days in this example):

$ git-pages-cli https://example.org --password xyz --upload-dir site-contents --expires 14

Forge authorization

Important

If you are using Forgejo Actions, read the documentation for git-pages/action first.

Uploading a directory to a site on a wildcard domain (e.g. https://<owner>.grebedoc.dev/<repo>) requires the use of an access token with push permissions for the corresponding repository (https://codeberg.org/<owner>/<repo>.git in this case).

To create such an access token on Forgejo:

1. Open Settings > Applications > Access tokens.
2. Expand Select permissions, then pick Read under user and Read and write under repository.
3. Set Token name to something informative (e.g. "git-pages publishing").
4. Click Generate token.
5. The token will appear in a notification (a long string of hexadecimal numbers all on its own).

To deploy using an access token:

$ git-pages-cli https://username.grebedoc.dev --token <token> --upload-dir ...

Keep the access token safe and secure! Anyone who has it will be able to change the data in any of your repositories.

Specifying secrets

While secrets may be specified using the command-line arguments --password and --token, this is not always desirable. The alternatives to the --password flag are the --password-file flag and the GIT_PAGES_PASSWORD environment variable, and the alternative to the --token flag is the GIT_PAGES_TOKEN environment variable. When both the environment variable and the command-line argument are provided, the command-line argument takes priority.

Advanced usage

To retrieve the site manifest (for debugging only: manifest schema is not versioned and subject to change without notice, including renaming of existing fields):

$ git-pages-cli https://example.org --password xyz --debug-manifest
{
  "contents": {
    "": {
      "type": "Directory"
    },
    "index.html": {
      "type": "InlineFile",
      "size": "5",
      "data": "bWVvdwo=",
      "contentType": "text/html; charset=utf-8"
    }
  },
  "originalSize": "5",
  "compressedSize": "5",
  "storedSize": "0",
  "redirects": [],
  "headers": [],
  "problems": []
}

License

0-clause BSD