git-pages-cli #

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

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 quickly create a redirect:

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

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

Certain hosting platforms, like GitHub Pages and Netlify, provide a built-in "pretty URL" feature, where *.html files can be accessed without the extension. For example, /about.html can be accessed as /about and/or /about/. To assist with migration from one of these platforms, a similar feature can be enabled when using --upload-dir:

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

The "pretty URL" feature is implemented entirely within git-pages-cli: this tool discovers every *.html file and generates appropriate _redirects file entries. If a site-contents/_redirects file exists, the generated redirect rules will be appended to its contents (so that user-defined rules take priority).

Forge authorization #

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
{
  "comment": "0000000000000000000000000000000000000000",
  "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": []
}

To embed a free-form comment in the site manifest, for example to record the exact commit from which a site has been built:

$ git-pages-cli https://example.org --password xyz --upload-dir site-contents --comment "$(git rev-parse HEAD)"

License #

0-clause BSD