@xbibzlibrary/telebibz 0.1.12 → 0.1.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.id.md +4 -2
- package/README.md +2 -0
- package/README.zh-CN.md +4 -2
- package/RELEASE_AUTOMATION.md +10 -6
- package/docs/API.md +2 -2
- package/docs/GITHUB_PACKAGES.id.md +82 -0
- package/docs/GITHUB_PACKAGES.md +82 -0
- package/docs/GITHUB_PACKAGES.zh-CN.md +82 -0
- package/package.json +1 -1
package/README.id.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
Referensi API lengkap: [English](docs/API.md) · **Indonesia** · [中文](docs/API.zh-CN.md)
|
|
10
10
|
|
|
11
|
+
Panduan GitHub Packages: [English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
|
|
12
|
+
|
|
11
13
|

|
|
12
14
|
|
|
13
15
|
## Instalasi
|
|
@@ -143,7 +145,7 @@ Daftar method dihasilkan dari dokumentasi Telegram Bot API saat skema diperbarui
|
|
|
143
145
|
|
|
144
146
|
## Otomatisasi release
|
|
145
147
|
|
|
146
|
-
Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main` menjalankan quality gates, memilih patch version yang belum dipakai, membuat commit dan tag, menerbitkan
|
|
148
|
+
Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main` menjalankan quality gates, memilih patch version yang belum dipakai, membuat commit dan tag, menerbitkan tarball yang sama ke npmjs dan GitHub Packages, lalu membuat GitHub Release. Karena source repository bersifat private, workflow menggunakan `--provenance=false` untuk npmjs. GitHub Packages memakai `GITHUB_TOKEN` dengan permission `packages: write`. Konfigurasikan secret `NPM_TOKEN` pada GitHub Actions sebelum mengandalkan publish otomatis. Lihat [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) dan panduan [GitHub Packages](docs/GITHUB_PACKAGES.id.md).
|
|
147
149
|
|
|
148
150
|
## Policy project dan kontribusi
|
|
149
151
|
|
|
@@ -155,7 +157,7 @@ Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main
|
|
|
155
157
|
| [GOVERNANCE.md](GOVERNANCE.md) | Peran, pengambilan keputusan, triage, perlindungan repository, dan perubahan aturan. |
|
|
156
158
|
| [SECURITY.md](SECURITY.md) | Pelaporan vulnerability privat, batas security, dan rotasi credential. |
|
|
157
159
|
| [SUPPORT.md](SUPPORT.md) | Channel support, aturan laporan aman, dan ekspektasi response. |
|
|
158
|
-
| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | Automation GitHub-to-npm dan setup `NPM_TOKEN`. |
|
|
160
|
+
| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | Automation GitHub-to-npm/GitHub Packages dan setup `NPM_TOKEN`. |
|
|
159
161
|
| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Kontrol immutable release dan hardening. |
|
|
160
162
|
| [NOTICE.md](NOTICE.md) | Atribusi declaration pihak ketiga. |
|
|
161
163
|
|
package/README.md
CHANGED
|
@@ -12,6 +12,8 @@
|
|
|
12
12
|
|
|
13
13
|
Complete API references: [English](docs/API.md) · [Indonesia](docs/API.id.md) · [中文](docs/API.zh-CN.md)
|
|
14
14
|
|
|
15
|
+
GitHub Packages guide: [English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
|
|
16
|
+
|
|
15
17
|

|
|
16
18
|
|
|
17
19
|
## Installation
|
package/README.zh-CN.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
完整 API 参考:[English](docs/API.md) · [Indonesia](docs/API.id.md) · **中文**
|
|
10
10
|
|
|
11
|
+
GitHub Packages 指南:[English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
|
|
12
|
+
|
|
11
13
|

|
|
12
14
|
|
|
13
15
|
## 安装
|
|
@@ -143,7 +145,7 @@ npm run release:check
|
|
|
143
145
|
|
|
144
146
|
## 发布自动化
|
|
145
147
|
|
|
146
|
-
GitHub repository 提供 CI 和自动发布 workflow。每次推送到 `main` 都会运行 quality gates,选择尚未使用的 patch version,创建 commit 和 tag
|
|
148
|
+
GitHub repository 提供 CI 和自动发布 workflow。每次推送到 `main` 都会运行 quality gates,选择尚未使用的 patch version,创建 commit 和 tag,将相同的 tarball 发布到 npmjs 和 GitHub Packages,然后创建 GitHub Release。由于 source repository 是 private,npmjs 发布使用 `--provenance=false`;GitHub Packages 使用带有 `packages: write` 权限的 `GITHUB_TOKEN`。依赖自动发布前,请在 GitHub Actions 中配置 `NPM_TOKEN` secret。请参阅 [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) 和 [GitHub Packages 指南](docs/GITHUB_PACKAGES.zh-CN.md)。
|
|
147
149
|
|
|
148
150
|
## 项目 policy 和贡献
|
|
149
151
|
|
|
@@ -155,7 +157,7 @@ GitHub repository 提供 CI 和自动发布 workflow。每次推送到 `main`
|
|
|
155
157
|
| [GOVERNANCE.md](GOVERNANCE.md) | 角色、决策、triage、repository protection 和规则修改。 |
|
|
156
158
|
| [SECURITY.md](SECURITY.md) | 私密漏洞报告、security boundary 和 credential rotation。 |
|
|
157
159
|
| [SUPPORT.md](SUPPORT.md) | Support channel、安全报告规则和 response 预期。 |
|
|
158
|
-
| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | GitHub-to-npm automation 和 `NPM_TOKEN` setup。 |
|
|
160
|
+
| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | GitHub-to-npm/GitHub Packages automation 和 `NPM_TOKEN` setup。 |
|
|
159
161
|
| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Immutable release 和 hardening 控制。 |
|
|
160
162
|
| [NOTICE.md](NOTICE.md) | 第三方 declaration attribution。 |
|
|
161
163
|
|
package/RELEASE_AUTOMATION.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# GitHub-to-npm Release Automation
|
|
1
|
+
# GitHub-to-npm and GitHub Packages Release Automation
|
|
2
2
|
|
|
3
|
-
Repository ini menggunakan GitHub Actions untuk menjaga source GitHub dan package
|
|
3
|
+
Repository ini menggunakan GitHub Actions untuk menjaga source GitHub, package npmjs, dan package GitHub Packages tetap sinkron melalui satu jalur release yang tervalidasi. Repository source tetap private; karena itu workflow menggunakan npm publish tanpa provenance, sesuai batasan registry npm untuk source private. Panduan instalasi GitHub Packages tersedia dalam [English](docs/GITHUB_PACKAGES.md), [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md), dan [简体中文](docs/GITHUB_PACKAGES.zh-CN.md).
|
|
4
4
|
|
|
5
5
|
## Alur otomatis
|
|
6
6
|
|
|
@@ -12,21 +12,24 @@ Setiap push ke branch `main` menjalankan workflow `.github/workflows/auto-publis
|
|
|
12
12
|
| Install | Menjalankan `npm ci --ignore-scripts`. |
|
|
13
13
|
| Version | Membaca versi dari `package.json`, membaca versi latest npm, lalu memilih patch version berikutnya yang lebih tinggi dari keduanya. |
|
|
14
14
|
| Verification | Menjalankan typecheck, type-level tests, lint, runtime tests, build ESM/CommonJS, security audit, dan release check. |
|
|
15
|
-
| Immutable guard | Menolak publish jika versi target sudah ada di
|
|
15
|
+
| Immutable guard | Menolak publish jika versi target sudah ada di npmjs atau GitHub Packages. |
|
|
16
16
|
| Git sync | Commit otomatis `chore(release): vX.Y.Z [skip release]`, membuat annotated tag `vX.Y.Z`, lalu push commit dan tag ke GitHub. |
|
|
17
|
-
|
|
|
17
|
+
| npmjs publish | Menerbitkan tarball terverifikasi ke npmjs menggunakan `NPM_TOKEN`; provenance dinonaktifkan karena npm menolak provenance dari source repository private. |
|
|
18
|
+
| GitHub Packages publish | Menerbitkan tarball yang sama ke `https://npm.pkg.github.com` menggunakan `GITHUB_TOKEN` dan permission `packages: write`. |
|
|
18
19
|
| GitHub Release | Membuat GitHub Release dengan generated notes. |
|
|
19
20
|
|
|
20
21
|
Push commit version otomatis tidak memicu release kedua karena mengandung `[skip release]`. Workflow menggunakan concurrency sehingga release berjalan satu per satu.
|
|
21
22
|
|
|
22
|
-
## Secret yang wajib tersedia
|
|
23
|
+
## Secret dan permission yang wajib tersedia
|
|
23
24
|
|
|
24
|
-
Buka repository GitHub, kemudian masuk ke **Settings → Secrets and variables → Actions** dan tambahkan repository secret:
|
|
25
|
+
Workflow membutuhkan `packages: write` untuk GitHub Packages dan `contents: write` untuk version bump, tag, serta GitHub Release. Buka repository GitHub, kemudian masuk ke **Settings → Secrets and variables → Actions** dan tambahkan repository atau environment secret berikut:
|
|
25
26
|
|
|
26
27
|
```text
|
|
27
28
|
NPM_TOKEN=${NPM_TOKEN}
|
|
28
29
|
```
|
|
29
30
|
|
|
31
|
+
GitHub Packages menggunakan `GITHUB_TOKEN` bawaan Actions; tidak perlu membuat atau menyimpan GitHub PAT sebagai repository secret untuk package yang diterbitkan oleh workflow repository ini.
|
|
32
|
+
|
|
30
33
|
Jika memakai GitHub Environment bernama `npm-release`, secret dapat disimpan sebagai environment secret dan environment tersebut dapat diberi required reviewers untuk approval manual sebelum publish.
|
|
31
34
|
|
|
32
35
|
Jangan menyimpan token di repository, `.npmrc`, source code, issue, commit, atau workflow. Token npm yang pernah ditempelkan di chat harus dicabut dan diganti dengan granular token baru.
|
|
@@ -63,4 +66,5 @@ Setelah workflow selesai, verifikasi:
|
|
|
63
66
|
|
|
64
67
|
```bash
|
|
65
68
|
npm view @xbibzlibrary/telebibz version dist.integrity dist.tarball
|
|
69
|
+
npm view @xbibzlibrary/telebibz version --registry=https://npm.pkg.github.com
|
|
66
70
|
```
|
package/docs/API.md
CHANGED
|
@@ -1001,7 +1001,7 @@ interface PluginApi<Context> {
|
|
|
1001
1001
|
}
|
|
1002
1002
|
```
|
|
1003
1003
|
|
|
1004
|
-
In this release, `registerMiddleware`
|
|
1004
|
+
In this release, `registerMiddleware` connects plugin middleware to `bot.use()`, and `registerRoute` connects plugin routes to `bot.router.route()`. The bot lifecycle invokes plugin `onUpdate` and `onStop` hooks automatically.
|
|
1005
1005
|
|
|
1006
1006
|
### `ServiceContainer`
|
|
1007
1007
|
|
|
@@ -1032,7 +1032,7 @@ new PluginManager<Context>(bot: unknown): PluginManager<Context>
|
|
|
1032
1032
|
| `dispose()` | Executes `dispose` in reverse registration order. |
|
|
1033
1033
|
| `list()` | Returns a read-only list of plugins. |
|
|
1034
1034
|
|
|
1035
|
-
`Bot.handleUpdate()`
|
|
1035
|
+
`Bot.handleUpdate()` calls `plugins.update()` automatically after the update is processed, and `Bot.stop()` invokes plugin stop hooks before disposal.
|
|
1036
1036
|
|
|
1037
1037
|
---
|
|
1038
1038
|
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# GitHub Packages
|
|
2
|
+
|
|
3
|
+
`@xbibzlibrary/telebibz` dirilis ke [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) dan registry npm GitHub Packages. Repository GitHub resminya adalah [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
|
|
4
|
+
|
|
5
|
+
## Registry
|
|
6
|
+
|
|
7
|
+
URL registry GitHub Packages:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
https://npm.pkg.github.com
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Mapping scope npm:
|
|
14
|
+
|
|
15
|
+
```ini
|
|
16
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Workflow release mempublikasikan tarball yang sama ke npmjs dan GitHub Packages setelah typecheck, test, build, security audit, dan release check berhasil. Workflow menggunakan `GITHUB_TOKEN` dengan permission `packages: write`; personal access token GitHub tidak disimpan di repository atau workflow.
|
|
20
|
+
|
|
21
|
+
## Instalasi package
|
|
22
|
+
|
|
23
|
+
Untuk package public, tambahkan mapping berikut pada `.npmrc` project yang memakai package:
|
|
24
|
+
|
|
25
|
+
```ini
|
|
26
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Jika package atau repository bersifat private, gunakan **personal access token (classic)** dengan minimal akses `read:packages`. Simpan token di luar repository, sebaiknya melalui environment variable reference pada konfigurasi npm user:
|
|
30
|
+
|
|
31
|
+
```ini
|
|
32
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
33
|
+
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Kemudian jalankan:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export GITHUB_PACKAGES_TOKEN="<token-read-packages-kamu>"
|
|
40
|
+
npm install @xbibzlibrary/telebibz
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Jangan mengganti placeholder dengan token asli di file yang di-commit. Jangan commit `.npmrc` yang berisi kredensial literal, dan jangan memasukkan token ke issue, pull request, log, atau chat.
|
|
44
|
+
|
|
45
|
+
## Publikasi lokal
|
|
46
|
+
|
|
47
|
+
Cara yang direkomendasikan adalah workflow GitHub Actions yang telah dilindungi. Workflow memeriksa versi dan hanya publish setelah seluruh release gate berhasil. Publikasi lokal hanya untuk maintainer yang memiliki personal access token (classic) dengan `write:packages` serta permission repository:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
export GITHUB_PACKAGES_TOKEN="<token-write-packages-kamu>"
|
|
51
|
+
printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
|
|
52
|
+
npm run build
|
|
53
|
+
npm pack
|
|
54
|
+
npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Gunakan semantic version baru untuk setiap publikasi. Versi registry bersifat immutable dan tidak boleh ditimpa.
|
|
58
|
+
|
|
59
|
+
## Permission GitHub Actions
|
|
60
|
+
|
|
61
|
+
Workflow release menggunakan permission minimum berikut:
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
permissions:
|
|
65
|
+
contents: write
|
|
66
|
+
packages: write
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`NPM_TOKEN` tetap menjadi environment secret untuk publikasi ke npmjs. GitHub Packages menggunakan `GITHUB_TOKEN` otomatis, sehingga tidak memerlukan secret GitHub tambahan untuk package milik repository ini. Jika kebijakan organisasi menonaktifkan pewarisan akses package, hubungkan package ke repository dan berikan akses workflow melalui pengaturan package.
|
|
70
|
+
|
|
71
|
+
## Troubleshooting
|
|
72
|
+
|
|
73
|
+
Respons `401 Unauthorized` biasanya berarti token tidak ada, sudah kedaluwarsa, atau tidak mempunyai scope package yang benar. Respons `403 Forbidden` biasanya berarti akun atau workflow tidak memiliki permission package, atau kebijakan organisasi memblokir publikasi. Respons `404 Not Found` dapat muncul ketika package private diakses tanpa autentikasi atau scope belum diarahkan ke `https://npm.pkg.github.com`.
|
|
74
|
+
|
|
75
|
+
Untuk instalasi dari npmjs, hapus mapping GitHub scope atau gunakan registry npm default. Kedua registry berisi nama package dan versi yang sama, tetapi autentikasi dan access control dikelola secara terpisah.
|
|
76
|
+
|
|
77
|
+
## Referensi
|
|
78
|
+
|
|
79
|
+
1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
|
|
80
|
+
2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
|
|
81
|
+
3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
|
|
82
|
+
4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# GitHub Packages
|
|
2
|
+
|
|
3
|
+
`@xbibzlibrary/telebibz` is released to both [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) and the GitHub Packages npm registry. The canonical GitHub repository is [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
|
|
4
|
+
|
|
5
|
+
## Registry
|
|
6
|
+
|
|
7
|
+
GitHub Packages uses the following npm registry URL:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
https://npm.pkg.github.com
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The package scope is mapped to GitHub Packages with:
|
|
14
|
+
|
|
15
|
+
```ini
|
|
16
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The release workflow publishes the same verified tarball to npmjs and GitHub Packages after the type checks, tests, build, security audit, and release checks pass. The workflow uses `GITHUB_TOKEN` with `packages: write`; no GitHub personal access token is stored in the repository or workflow file.
|
|
20
|
+
|
|
21
|
+
## Installing the package
|
|
22
|
+
|
|
23
|
+
For a public package, use a GitHub Packages-aware `.npmrc` in the consuming project:
|
|
24
|
+
|
|
25
|
+
```ini
|
|
26
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
If the package or repository is private, authenticate with a **personal access token (classic)** that has at least `read:packages` access. Store the token outside the repository, preferably in the user-level npm configuration or an environment-variable reference:
|
|
30
|
+
|
|
31
|
+
```ini
|
|
32
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
33
|
+
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Then install the package:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
|
|
40
|
+
npm install @xbibzlibrary/telebibz
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Do not replace the placeholder with a real token in a committed file. Do not commit `.npmrc` files containing literal credentials, and do not paste tokens into issues, pull requests, logs, or chat.
|
|
44
|
+
|
|
45
|
+
## Publishing locally
|
|
46
|
+
|
|
47
|
+
The recommended publishing path is the protected GitHub Actions workflow. It verifies the version and publishes only after all release gates succeed. Local publishing is intended for maintainers who have a classic personal access token with `write:packages` and repository permission to publish packages:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
|
|
51
|
+
printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
|
|
52
|
+
npm run build
|
|
53
|
+
npm pack
|
|
54
|
+
npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use a new semantic version for every publication. Registry versions are immutable; an existing version must never be overwritten.
|
|
58
|
+
|
|
59
|
+
## GitHub Actions permissions
|
|
60
|
+
|
|
61
|
+
The release workflow declares the minimum package permission required for publication:
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
permissions:
|
|
65
|
+
contents: write
|
|
66
|
+
packages: write
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`NPM_TOKEN` remains an environment secret for npmjs publication. GitHub Packages uses the automatically provided `GITHUB_TOKEN`, so no additional GitHub token secret is required for the repository's own package. If organization policy disables automatic package access inheritance, connect the package to the repository and grant the workflow access under the package's settings.
|
|
70
|
+
|
|
71
|
+
## Troubleshooting
|
|
72
|
+
|
|
73
|
+
A `401 Unauthorized` response normally means the token is missing, expired, or lacks the required package scope. A `403 Forbidden` response usually means the account or workflow does not have permission to the package, or that organization policy blocks publication. A `404 Not Found` response can occur when a private package is queried without authentication or when the scope is not mapped to `https://npm.pkg.github.com`.
|
|
74
|
+
|
|
75
|
+
For npmjs installation, omit the GitHub scope mapping or use the default npm registry. Both registries contain the same package name and release version, but authentication and access control are handled independently.
|
|
76
|
+
|
|
77
|
+
## References
|
|
78
|
+
|
|
79
|
+
1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
|
|
80
|
+
2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
|
|
81
|
+
3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
|
|
82
|
+
4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# GitHub Packages
|
|
2
|
+
|
|
3
|
+
`@xbibzlibrary/telebibz` 同时发布到 [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) 和 GitHub Packages npm registry。官方 GitHub 仓库是 [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz)。
|
|
4
|
+
|
|
5
|
+
## Registry
|
|
6
|
+
|
|
7
|
+
GitHub Packages 使用以下 npm registry 地址:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
https://npm.pkg.github.com
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
npm scope 映射如下:
|
|
14
|
+
|
|
15
|
+
```ini
|
|
16
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
release workflow 会在 typecheck、测试、构建、安全审计和 release check 全部通过后,将同一个经过验证的 tarball 发布到 npmjs 和 GitHub Packages。workflow 使用具有 `packages: write` 权限的 `GITHUB_TOKEN`,不会把 GitHub personal access token 存储在仓库或 workflow 文件中。
|
|
20
|
+
|
|
21
|
+
## 安装 package
|
|
22
|
+
|
|
23
|
+
对于 public package,可以在使用方项目的 `.npmrc` 中加入:
|
|
24
|
+
|
|
25
|
+
```ini
|
|
26
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
如果 package 或 repository 是 private,请使用具有至少 `read:packages` 权限的 **personal access token (classic)**。请将 token 保存在仓库之外,建议使用 npm 用户配置中的环境变量引用:
|
|
30
|
+
|
|
31
|
+
```ini
|
|
32
|
+
@xbibzlibrary:registry=https://npm.pkg.github.com
|
|
33
|
+
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
然后执行:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
|
|
40
|
+
npm install @xbibzlibrary/telebibz
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
不要把真实 token 写入已经提交的文件。不要提交包含明文凭据的 `.npmrc`,也不要在 issue、pull request、日志或聊天中粘贴 token。
|
|
44
|
+
|
|
45
|
+
## 本地发布
|
|
46
|
+
|
|
47
|
+
推荐使用受保护的 GitHub Actions workflow 发布。workflow 会检查版本,并且只有所有 release gate 成功后才会发布。本地发布仅适用于拥有 `write:packages` classic token 以及 repository 发布权限的 maintainer:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
|
|
51
|
+
printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
|
|
52
|
+
npm run build
|
|
53
|
+
npm pack
|
|
54
|
+
npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
每次发布必须使用新的 semantic version。registry 中的版本是 immutable,不能覆盖已有版本。
|
|
58
|
+
|
|
59
|
+
## GitHub Actions 权限
|
|
60
|
+
|
|
61
|
+
release workflow 声明了发布所需的最小权限:
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
permissions:
|
|
65
|
+
contents: write
|
|
66
|
+
packages: write
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`NPM_TOKEN` 仍然作为 npmjs 发布所需的 environment secret。GitHub Packages 使用自动提供的 `GITHUB_TOKEN`,因此本仓库的 package 不需要额外的 GitHub token secret。如果组织策略关闭了 package 权限自动继承,请在 package 设置中连接 repository,并授予 workflow 访问权限。
|
|
70
|
+
|
|
71
|
+
## 故障排查
|
|
72
|
+
|
|
73
|
+
`401 Unauthorized` 通常表示 token 缺失、过期或没有正确的 package scope。`403 Forbidden` 通常表示账号或 workflow 没有 package 权限,或者组织策略禁止发布。访问 private package 时没有认证,或 scope 没有映射到 `https://npm.pkg.github.com`,也可能得到 `404 Not Found`。
|
|
74
|
+
|
|
75
|
+
从 npmjs 安装时,请删除 GitHub scope mapping 或使用默认 npm registry。两个 registry 包含相同的 package 名称和版本,但认证和 access control 独立管理。
|
|
76
|
+
|
|
77
|
+
## 参考资料
|
|
78
|
+
|
|
79
|
+
1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
|
|
80
|
+
2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
|
|
81
|
+
3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
|
|
82
|
+
4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)
|
package/package.json
CHANGED