whitequark.org
[mirror] Command-line application for uploading a site to a git-pages server
1git-pages-cli
2=============
3
4_git-pages-cli_ is a command-line application for publishing sites to [git-pages].
5
6> [!TIP]
7> If you want to publish a site from a CI workflow, use the [Forgejo Action][git-pages-action] instead.
8
9[git-pages]: https://codeberg.org/git-pages/git-pages
10[git-pages-action]: https://codeberg.org/git-pages/action
11
12
13Installation
14------------
15
16You can install _git-pages-cli_ using one of the following methods:
17
181. **Downloading a binary**. You can download the [latest build][latest] or pick a [release][releases].
19
201. **Installing a package**.
21
22 [](https://repology.org/project/git-pages-cli/versions)
23
241. **Using a Docker container**. Choose between the latest build or a [release tag][containers]. Then run:
25
26 ```console
27 $ docker run --rm codeberg.org/git-pages/git-pages-cli:latest ...
28 ```
29
301. **Installing from source**. First, install [Go](https://go.dev/) 1.25 or newer. Then run:
31
32 ```console
33 $ go install codeberg.org/git-pages/git-pages-cli@latest
34 ```
35
36[latest]: https://codeberg.org/git-pages/git-pages-cli/releases/tag/latest
37[releases]: https://codeberg.org/git-pages/git-pages-cli/releases
38[containers]: https://codeberg.org/git-pages/-/packages/container/git-pages-cli/versions
39
40
41Usage
42-----
43
44To prepare a DNS challenge for a given site and password:
45
46```console
47$ git-pages-cli https://example.org --challenge # generate a random password
48password: 28a616f4-2fbe-456b-8456-056d1f38e815
49_git-pages-challenge.example.org. 3600 IN TXT "a59ecb58f7256fc5afb6b96892501007b0b65d64f251b1aca749b0fca61d582c"
50$ git-pages-cli https://example.org --password xyz --challenge
51_git-pages-challenge.example.org. 3600 IN TXT "6c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8"
52$ git-pages-cli https://example.org --password xyz --challenge-bare
536c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8
54```
55
56To publish a site from a git repository available on the internet (`--password` may be omitted if the repository is allowlisted via DNS):
57
58```console
59$ git-pages-cli https://example.org --upload-git https://codeberg.org/username/example.org.git
60$ git-pages-cli https://example.org --password xyz --upload-git https://codeberg.org/username/example.org.git
61```
62
63To publish a site from a directory on your machine:
64
65```console
66$ git-pages-cli https://example.org --password xyz --upload-dir site-contents
67```
68
69To delete a site:
70
71```console
72$ git-pages-cli https://example.org --password xyz --delete
73```
74
75It 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:
76
77```console
78$ git-pages-cli https://example.org --server grebedoc.dev --password xyz --upload-dir ...
79```
80
81### Forge authorization
82
83Uploading 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).
84
85To create such an access token on Forgejo:
861. Open _Settings_ > _Applications_ > _Access tokens_.
871. Expand _Select permissions_, pick _Read and write_ under _repository_.
881. Set _Token name_ to something informative (e.g. "git-pages publishing").
891. Click _Generate token_.
901. The token will appear in a notification (a long string of hexadecimal numbers all on its own).
91
92To deploy using an access token:
93
94```console
95$ git-pages-cli https://username.grebedoc.dev --token <token> --upload-dir ...
96```
97
98**Keep the access token safe and secure!** Anyone who has it will be able to change the data in any of your repositories.
99
100
101Advanced usage
102--------------
103
104To retrieve the site manifest (for debugging only: manifest schema is not versioned and **subject to change without notice**, including renaming of existing fields):
105
106```console
107$ git-pages-cli https://example.org --password xyz --debug-manifest
108{
109 "contents": {
110 "": {
111 "type": "Directory"
112 },
113 "index.html": {
114 "type": "InlineFile",
115 "size": "5",
116 "data": "bWVvdwo=",
117 "contentType": "text/html; charset=utf-8"
118 }
119 },
120 "originalSize": "5",
121 "compressedSize": "5",
122 "storedSize": "0",
123 "redirects": [],
124 "headers": [],
125 "problems": []
126}
127```
128
129
130License
131-------
132
133[0-clause BSD](LICENSE.txt)