# Verdaccio
Verdaccio is a **lightweight private npm proxy registry** built in **Node.js**
# Verdaccio
### Tổng quan về Verdaccio.
Verdaccio là một proxy server và private registry cho các package.
#### Tính năng chính.
****Lưu trữ các package**** mà không cần publish lên các package manager public.
****Proxy và cache các package public****: Verdaccio có thể proxy, cache các package bạn đã tải từ đó giúp:
- Tăng tốc độ cài đặt package
- Giảm phụ thuộc vào internet hoặc registery chính.
- Cải thiện độ ổn định trong CI/CD
****Tạo môi trường phát triển an toàn và kiểm soát hơn****: Verdaccio cho phép bạn cấu hình quyền truy cập cho user, chỉ ai có quyền truy cập mới có thể publish hoặc install package cụ thể.
#### Ưu điểm chính.
****Dễ cài đặt****: Có thể cài đặt bằng lệnh `npm install` hoặc trên Docker
****Không cần cơ sở dữ liệu****: Dữ liệu được lưu dưới dạng file (yaml, json) phù hợp với các dự án nhỏ, trung bình.
****Tích hợp CI/CD tốt****: Hỗ trợ pipeline CI/CD để test, publish các gói nội bộ.
****Hỗ trợ plugins****: Có thể mở rộng chức năng qua plugin.
### Cài đặt Verdaccio.
Trong bài viết này mình sẽ cài Verdaccio bằng Docker trên NAS XPEnology.
#### Step 1: Prepare
Trong File Station tạo một shared folder tên là docker (có thể sử dụng cho nhiều container) và cấp quyền ****Read&Write**** cho ContainerManager (nếu sau này gặp lỗi có thể cấp thêm quyền Read & Write cho Everyone)
Tạo folder Verdaccio bên trong folder docker vừa tạo ở bước trên.
Trong folder Verdaccio tạo thêm các folder `conf, plugins, storage` để mapping trong quá trình cài đặt container ****(Việc map folder sẽ giúp tránh mất dữ liệu khi Container gặp vấn đề, hoặc uninstall container)****
[](https://knowledge.thanhdv.com/uploads/images/gallery/2025-05/61447.png)
Trong folder ****docker/Verdaccio/conf**** tạo file ****config.yaml**** với nội dung như sau:
```yaml
max_body_size: 143mb
storage: /verdaccio/storage
plugins: /verdaccio/plugins
web:
enable: true
title: ThanhDV's Verdaccio
auth:
htpasswd:
file: ./htpasswd
packages:
'@*/*':
access: $all
publish: $authenticated
unpublish: $authenticated
'**':
access: $all
publish: $authenticated
unpublish: $authenticated
log:
- { type: stdout, format: pretty, level: info }
```
#### Step 2: Download Image
Truy cập Container Manager trên NAS tải về image `verdaccio/verdaccio:7x-next`
Sau khi tải về xong chuột phải vào image và chọn Run.
#### Step 3: Setup
##### General Settings
[](https://knowledge.thanhdv.com/uploads/images/gallery/2025-05/37416.png)
- ****Container Name:**** Đặt tuỳ ý
- ****Enable Auto-restart:**** Bật để container tự khởi động lại
Xong chọn ****Next.****
##### Advanced Settings
****Port Settings**** điền số cổng để truy cập đến Verdaccio (mặc định là 4873)
[](https://knowledge.thanhdv.com/uploads/images/gallery/2025-05/84259.png)
Sau đó nhấn ****Next****.
Kiểm tra lại cài đặt một lượt rồi nhấn ****Done.****
Nếu thành công bạn có thể truy cập giao diện web của Verdaccio qua http://localhost:4873 hoặc nếu bạn có domain riêng đã setup thì có thể truy cập qua domain name [http://domain.com:4873](http://domain.com:4873)
[](https://knowledge.thanhdv.com/uploads/images/gallery/2025-05/15225.png)
#### Step 4: Cài đặt Reverse Proxy (Optional)
Trên NAS, tạo Reverse Proxy mới, ****Control Panel > Login Portal > Advanced > Reverse Proxy > Create****
[](https://knowledge.thanhdv.com/uploads/images/gallery/2025-05/15446.png)
****Source****
- ****Reverse Proxy Name****: Tuỳ chọn
- ****Protocol:**** HTTPS
- ****Hostname****: Địa chỉ bạn muốn sử dụng để truy cập Verdaccio
- ****Port:**** 443
- ****Enable HSTS****: true
****Destination****
- ****Protocol****: HTTP (giao thức của Verdaccio khi cài đặt qua Docker)
- ****Hostname****: localhost (hoặc local IP)
- ****Port:**** 4873 (cổng truy cập khi cài đặt trên Docker)
Chọn ****Save**** để hoàn tất.
Đến đây mình đã có thể truy cập Verdaccio qua domain. Nhưng vẫn sẽ nhận được thông báo bảo mật. Cần cài đặt thêm ****Certificate****.
Truy cập ****Control Panel > Security > Certificate > Add**** tạo một Certificate mới và gán cho địa chỉ vừa tạo ở bước trên.
****Doneeeeeeeee!!!!!!!!****
### Sử dụng cơ bản
Create user
`npm adduser --registry https://your-domain.com`
Login
`npm login --registry https://your-domain.com`
Publish
`npm publish --registry https://your-domain.com`
Unpublish
`npm unpublish package.id --force --registry https://your-domain.com`
# CI/CD cho Verdaccio với Jenkins
Thiết lập hệ thống CI/CD cho Verdaccio. Tự động publish package khi có commit mới.
### Chuẩn bị
**Verdaccio Server**
**Jenkins**
- [Jenkins Controller.](https://docs.thanhdv.com/other/ci-cd-trong-unity-part-3/)
- [Jenkins Agent.](https://docs.thanhdv.com/other/ci-cd-trong-unity-part-4/)
**Jenkins Plugins**
- Blue Ocean
- NodeJS (Cài đặt tự động NodeJS lên Agent)
- Credentials
- Credentials Binding
- GitHub (Cần cho Webhook)
- Discord (Thông báo khi pipeline chạy xong)
**Package Repo** (Repo trên Git, Github, Gitlab… folder package chứa [Jenkinsfile](#bkmrk-jenkinsfile-demo "Jenkinsfile demo") và package.json)
**Jenkins Credentials** ([Cài đặt Credentials](#bkmrk-c%C3%A0i-%C4%91%E1%BA%B7t-credentials "Cài đặt Credentials"))
- Credential cho Verdaccio (chứa username, password đăng nhập Verdaccio)
- Credential cho Github (chứa username và PAT xác thực Github)
- Credential cho Github Secret (chứa Webhook Secret của Github)
- Credential cho Discord Webhook URL (chứa Webhook URL của Discord)
### Tạo và cấu hình Jenkins Jobs
Tạo item mới với type là **Pipeline**.
Cấu hình Jobs
- **General** (tuỳ chọn)
- Description: mô tả
- Github project: link đến github repo (không quan trọng)
- **Trigger**
- Chọn **GitHub hook trigger for GITScm polling** để trigger từ GitHub.
- **Poll SCM** để kiểm tra bào build định kỳ.
- Để **trống** nếu muốn chạy thủ công.
- **Pipeline**
- Definition:
- **Pipeline script from SCM** để sử dụng jenkinsfile trong repo (recommend)
- **Pipeline script** để viết trược tiếp jenkinsfile
- SCM chọn Git
- Repositories
- Repository URL: URL của GitHub repo (Ex: `https://github.com/ThanhDang143/Backup.UniTask.git`)
- Credentials: chọn GitHub Credentials đã tạo.
- Branches to build: nhánh GitHub cần theo dõi
- Script Path: Đường dẫn đến Jenkinsfile trong repo (mặc định là `Jenkinsfile`. Ex: `src/UniTask/Assets/Plugins/UniTask/Jenkinsfile`)
### Chạy và kiểm tra
Tại đây ta đã có thể chạy **build thủ công.**
Truy cập Blue Ocean. Để theo dõi tiến trình.
Kiểm tra kết quả và debug.
Nếu thành công thì có thể chuyển sang bước tiếp theo.
### Cấu hình Trigger tự động
Tiếp đến là cấu hình để Jenkins tự động chạy job khi có commit mới trên GitHub.
- Đảm bảo Jenkins Job đã chọn **GitHub hook trigger for GITScm polling** [khi tạo Job](#bkmrk-t%E1%BA%A1o-v%C3%A0-c%E1%BA%A5u-h%C3%ACnh-jenk "Tạo và cấu hình Jenkins Jobs").
- Cấu hình webhook trên GitHub Repo
- Truy cập **GitHub Repo > Settings > Webhook > Add webhook**
- **Payload URL**:
- Mặc định là URL Jenkins theo sau là `/github-webhook/` (Ex: `https://jenkins.thanhdv.com/github-webhook/`)
- URL Jenkins phải truy cập được từ internet.
- **Content type**: chọn `application/json`
- **Secret** là Credential cho Discord Webhook URL đã chuẩn bị
- **Which events**? chọn `Just the push event.`
- Đảm bảo đã tick chọn **Active** > **Add Webhook**
Sau khi add webhook github sẽ ping tới server. Kiểm tra tab **Recent Deliveries** để biết trạng thái ping
- Nếu không thành công kiểm tra lại các lỗi cơ bản như sai **Payload URL**, sai **Secret**, chưa **thêm secret vào Shared secrets**
- Nếu thành công có thể push một commit mới để test.
### Gửi thông báo qua Discord
Tạo Discord Webhoook, trên Discord truy cập **Server Settings > Integrations > Create Webhook.**
Copy Webhook URL đã tạo. Truy cập Jenkins Server tạo **Credential cho Discord Webhook URL**.
Trong bước tiếp theo ta cần cập nhật trong Jenkinsfile (**Đã có đầy đủ trong Jenkinsfile demo**)
- Tạo một biến môi trường `DISCORD_WEBHOOK = "CREDENTIAL_ID_DISCORD_WEBHOOK_URL"` để đảm bảo tính bảo mật không sử dụng trực tiếp Discord Webhook URL trong Jenkinsfile.
- Chỉnh sửa bên các khối sự kiện `success{ }, failure { }, aborted { }` bên trong khối `post` với nội dung demo như hình dưới. Chỉnh sửa lại nội dung cho phù hợp.
```dart
script {
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "ℹ️ Aborted: ${env.JOB_NAME}",
description: "Build #${env.BUILD_NUMBER} for job `${env.JOB_NAME}` was aborted.",
result: "ABORTED",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
```
### Phụ lục
#### Cài đặt Credentials
##### Thêm Domain (Tuỳ chọn)
**Jenkins Manager > Credentials > System > Add domain**. Tại đây điền Name và Desc cho domain mới.
Nếu không tạo domain mới có thể sử dụng domain Global.
##### Thêm Credentials
**Jenkins Manager > Credentials > System > Domain > Add Credentials**
- **Kind**
- Username with password với Credential cho Verdaccio hoặc Credential cho Github…
- Secret text với Credential cho Discord Webhook URL…
- …
- **Scope**: global
- **Username**
- **Password**: password hoặc PAT…
- **Secret**: chuỗi text
- **ID**: cần để sử dụng trong Jenkinsfile hoặc những nơi cần thiết…
- **Description**: mô tả.
**Chú ý:**
- Với **Credential cho GitHub Secret** sau khi tạo cần thêm vào **Shared secrets**
- **Jenkins Manager > System > GitHub > Advanced > Shared Secrets > Add Shared Secret** tại đây điền **ID** của Credential.
- Nếu không thấy **GitHub** kiểm tra lại GitHub Plugin
#### Lỗi thường gặp khi chạy Jenkins Job
Lỗi **`FileNotFoundException`**: Sai đường dẫn. Kiểm tra lại các path trong Jenkinsfile (PROJECT\_PATH…)
Lỗi **`Cannot run program "sh"`**: sh là lệnh của Linux. Nếu máy Agent là Window thay `sh` bằng `bat`.
Lỗi **`RejectedAccessException`** (`new java.net.URI`): Bị chặn bởi Script Security sandbox. Phê duyệt tại **Jenkins Manager > In-process Script Approval**
#### Jenkinsfile demo
##### Windows
```c
def packageVersionFromFile = ""
def packageName = ""
def verdaccioPackageUrl = ""
pipeline {
// Agent with Node.js & Git required
agent { label "thanhsserver" }
// Ensure Node.js tool is available (configure in Jenkins Global Tool Config)
tools {
nodejs "NodeJS22"
}
environment {
// Path to the directory containing package.json
PROJECT_PATH = "src/UniTask/Assets/Plugins/UniTask"
// Verdaccio registry URL
VERDACCIO_REGISTRY_URL = "https://upm.thanhdv.com"
// Jenkins Credential ID for Verdaccio auth (e.g., Secret Text or User/Pass with token)
VERDACCIO_CREDENTIAL_ID = "THANHDV_VERDACCIO_AUTH"
// Jenkins Credential ID for Git auth (MUST be "Username with password" type)
// Username: your git username
// Password: your git access token
GIT_CREDENTIAL_ID = "THANHDV_GITHUB_JENKINS_CREDENTIAL"
// Discord webhook create on Discord and add to Jenkins credential
DISCORD_WEBHOOK = "DISCORD_VERDACCIO_WEBHOOK"
// Release if commit has this key
RELEASE_KEYWORD = "Release v"
}
// === End Configuration ===
// Pipeline options
options {
timestamps()
buildDiscarder(logRotator(numToKeepStr: "10"))
timeout(time: 30, unit: "MINUTES")
disableConcurrentBuilds()
}
stages {
stage("Checkout") {
steps {
// Get source code
checkout scm
// git lfs pull // Uncomment if using Git LFS
}
}
// stage("Validate Commit Message") {
// steps {
// dir(env.PROJECT_PATH) {
// script {
// def isManualTrigger = false
// currentBuild.getBuildCauses().each{ cause ->
// if (cause instanceof hudson.model.Cause$UserIdCause || cause.shortDescription.contains("Started by user ")) {
// isManualTrigger = true
// }
// }
// if (isManualTrigger) {
// echo "Build triggered by User! Ignore Validate Commit Message."
// } else {
// def commitMessage = bat(script: 'git log -1 --pretty=%%B', returnStdout: true).trim()
// echo "Checking commit message: ${commitMessage}"
// if (!commitMessage.contains(RELEASE_KEYWORD)) {
// echo "Build condition not met! Aborting pipeline..."
// currentBuild.result = 'ABORTED'
// return
// }
// }
// echo "Commit message is valid for release."
// }
// }
// }
// }
stage("Prepare") {
when {
expression { return currentBuild.result != "ABORTED" }
}
steps {
// Operate within the project directory
dir(env.PROJECT_PATH) {
script {
// Read version directly from package.json
def pkg = readJSON file: "package.json" // Assumes package.json is at PROJECT_PATH root
if (!pkg || !pkg.version || !pkg.name) {
error "Could not read version from package.json"
}
// Store the version in the script-level variable
packageVersionFromFile = pkg.version
echo "Package version: ${packageVersionFromFile}"
packageName = pkg.name
echo "Package name: ${packageName}"
verdaccioPackageUrl = "${env.VERDACCIO_REGISTRY_URL}/-/web/detail/${packageName}"
echo "Package URL: ${verdaccioPackageUrl}"
if (!packageVersionFromFile || !packageName || !verdaccioPackageUrl) {
error "Failed to set variable."
}
withCredentials([usernamePassword(credentialsId: env.VERDACCIO_CREDENTIAL_ID, usernameVariable: "NPM_USER", passwordVariable: "NPM_PASS")]) {
echo "Configuring npm for Verdaccio using Username/Password..."
// Encrypt username:password to Base64
def userPass = "${NPM_USER}:${NPM_PASS}"
def encodedAuth = java.util.Base64.getEncoder().encodeToString(userPass.getBytes("UTF-8"))
def registryUri = new URI(env.VERDACCIO_REGISTRY_URL)
def registryAuthority = registryUri.getAuthority()
def registryHostPath = "//${registryAuthority}/"
// Configure .npmrc for Verdaccio registry & auth token
bat "echo registry=${env.VERDACCIO_REGISTRY_URL} > .npmrc"
bat "echo ${registryHostPath}:_auth=\"${encodedAuth}\" >> .npmrc"
echo ".npmrc configured."
}
// Install dependencies (might run prepublish scripts)
// echo "Running npm install..."
// bat "npm install"
}
}
}
}
stage("Publish") {
when {
expression { return currentBuild.result != "ABORTED" }
}
steps {
// Operate within the project directory
dir(env.PROJECT_PATH) {
script {
// Use the version read from package.json
echo "Publishing package version ${packageVersionFromFile} to ${env.VERDACCIO_REGISTRY_URL}"
try {
// Publish using npm (reads package.json for name/version, uses .npmrc for auth/registry)
bat "npm publish --registry ${env.VERDACCIO_REGISTRY_URL}"
echo "Package version ${packageVersionFromFile} published successfully!"
} catch (err) {
echo "ERROR: Failed to publish package!"
error "Publish failed: ${err.getMessage()}"
}
}
}
}
}
// // (Optional) Tag commit with the existing version from package.json
// stage("Tag Existing Version") {
// // Only run on overall success so far
// when { expression { currentBuild.result == null || currentBuild.result == "SUCCESS" } }
// steps {
// // Operate within the project directory
// dir(env.PROJECT_PATH) {
// script {
// echo "Tagging commit with existing version v${packageVersionFromFile}..."
// // Inject Git credentials (Username = Git user, Password = Access Token)
// withCredentials([usernamePassword(credentialsId: env.GIT_CREDENTIAL_ID, usernameVariable: "GIT_USERNAME", passwordVariable: "GIT_ACCESS_TOKEN")]) {
// // Configure Git user (may not be needed if just tagging)
// bat "git config user.email \"vanthanh1998@gmail.com\"" // EDIT Or use a specific user
// bat "git config user.name \"ThanhDVs Jenkins\""
// // NO commit needed here as we didn"t change package.json version via npm version
// // Create annotated tag using the version from package.json
// bat "git tag -a v${packageVersionFromFile} -m \"Release v${packageVersionFromFile}\"" // Use the read version
// // Push tag using HTTPS URL with embedded token
// def repoUrl = scm.userRemoteConfigs[0].url
// if (!repoUrl || !repoUrl.startsWith("https://")) {
// error "Could not determine HTTPS repository URL from SCM configuration."
// }
// def repoUrlClean = repoUrl.replaceAll(/https?:\/\/[^\/]+@/, "https://")
// def pushUrl = repoUrlClean.replaceFirst("https://", "https://${GIT_USERNAME}:${GIT_ACCESS_TOKEN}@")
// // Push only the tag
// bat "git push ${pushUrl} refs/tags/v${packageVersionFromFile}:refs/tags/v${packageVersionFromFile}"
// echo "Version tag v${packageVersionFromFile} pushed successfully."
// }
// }
// }
// }
// }
}
// Post-build actions
post {
// Always run cleanup
always {
echo "Build finished. Cleaning up..."
// Clean up sensitive .npmrc file
dir(env.PROJECT_PATH) {
script {
try {
bat "del /F /Q .npmrc"
} catch (err) {
echo "Could not delete .npmrc (maybe it doesn't exist): ${err.getMessage()}"
}
}
}
}
// On success
success {
echo "Pipeline successful!"
// Save artifacts if need
// archiveArtifacts artifacts: '**/*.tgz', allowEmptyArchive: true
echo "Cleaning up workspace..."
deleteDir()
echo "Sending success notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "✅ Success: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} published package `${packageName}@${packageVersionFromFile}` successfully.\nBuild Log: ${env.BUILD_URL}.\nPackage URL: ${verdaccioPackageUrl}",
result: "SUCCESS",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
// On failure
failure {
echo "Pipeline failed!"
echo "Sending failure notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "❌ Failure: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} failed to publish package `${packageName}`.\nBuild Log: ${env.BUILD_URL}",
result: "FAILURE",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
aborted {
echo "Pipeline aborted!"
echo "Sending abort notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "ℹ️ Aborted: ${env.JOB_NAME}",
description: "Build #${env.BUILD_NUMBER} for job `${env.JOB_NAME}` was aborted.",
result: "ABORTED",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
unstable {
echo "Pipeline unstable!"
echo "Sending unstable notification to Discord..."
script {
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "⚠️ Unstable: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} finished with unstable status during processing of package `${packageName}`.\nBuild Log: ${env.BUILD_URL}",
result: "UNSTABLE",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
}
}
```
##### Linux
```c#
def packageVersionFromFile = ""
def packageName = ""
def verdaccioPackageUrl = ""
pipeline {
// Agent with Node.js & Git required
agent { label "verdaccio-publisher" }
// Ensure Node.js tool is available (configure in Jenkins Global Tool Config)
tools {
nodejs "NodeJS22"
}
environment {
// Path to the directory containing package.json
PROJECT_PATH = "Assets/Packages/DeviceDebugger"
// Verdaccio registry URL
VERDACCIO_REGISTRY_URL = "https://upm.thanhdv.com"
// Jenkins Credential ID for Verdaccio auth (e.g., Secret Text or User/Pass with token)
VERDACCIO_CREDENTIAL_ID = "THANHDV_VERDACCIO_AUTH"
// Jenkins Credential ID for Git auth (MUST be "Username with password" type)
// Username: your git username
// Password: your git access token
GIT_CREDENTIAL_ID = "THANHDV_GITHUB_JENKINS_CREDENTIAL"
// Discord webhook create on Discord and add to Jenkins credential
DISCORD_WEBHOOK = "DISCORD_VERDACCIO_WEBHOOK"
// Release if commit has this key
RELEASE_KEYWORD = "Release v"
}
// === End Configuration ===
// Pipeline options
options {
timestamps()
buildDiscarder(logRotator(numToKeepStr: "10"))
timeout(time: 30, unit: "MINUTES")
disableConcurrentBuilds()
}
stages {
stage("Checkout") {
steps {
// Get source code
checkout scm
// git lfs pull // Uncomment if using Git LFS
}
}
// stage("Validate Commit Message") {
// steps {
// dir(env.PROJECT_PATH) {
// script {
// def isManualTrigger = false
// currentBuild.getBuildCauses().each{ cause ->
// if (cause instanceof hudson.model.Cause$UserIdCause || cause.shortDescription.contains("Started by user ")) {
// isManualTrigger = true
// }
// }
// if (isManualTrigger) {
// echo "Build triggered by User! Ignore Validate Commit Message."
// } else {
// def commitMessage = sh(script: 'git log -1 --pretty=%%B', returnStdout: true).trim()
// echo "Checking commit message: ${commitMessage}"
// if (!commitMessage.contains(RELEASE_KEYWORD)) {
// echo "Build condition not met! Aborting pipeline..."
// currentBuild.result = 'ABORTED'
// return
// }
// }
// echo "Commit message is valid for release."
// }
// }
// }
// }
stage("Prepare") {
when {
expression { return currentBuild.result != "ABORTED" }
}
steps {
// Operate within the project directory
dir(env.PROJECT_PATH) {
script {
// Read version directly from package.json
def pkg = readJSON file: "package.json" // Assumes package.json is at PROJECT_PATH root
if (!pkg || !pkg.version || !pkg.name) {
error "Could not read version from package.json"
}
// Store the version in the script-level variable
packageVersionFromFile = pkg.version
echo "Package version: ${packageVersionFromFile}"
packageName = pkg.name
echo "Package name: ${packageName}"
verdaccioPackageUrl = "${env.VERDACCIO_REGISTRY_URL}/-/web/detail/${packageName}"
echo "Package URL: ${verdaccioPackageUrl}"
if (!packageVersionFromFile || !packageName || !verdaccioPackageUrl) {
error "Failed to set variable."
}
withCredentials([usernamePassword(credentialsId: env.VERDACCIO_CREDENTIAL_ID, usernameVariable: "NPM_USER", passwordVariable: "NPM_PASS")]) {
echo "Configuring npm for Verdaccio using Username/Password..."
// Encrypt username:password to Base64
def userPass = "${NPM_USER}:${NPM_PASS}"
def encodedAuth = java.util.Base64.getEncoder().encodeToString(userPass.getBytes("UTF-8"))
def registryUri = new URI(env.VERDACCIO_REGISTRY_URL)
def registryAuthority = registryUri.getAuthority()
def registryHostPath = "//${registryAuthority}/"
// Configure .npmrc for Verdaccio registry & auth token
sh "echo ${registryHostPath}:_auth=\"${encodedAuth}\" > .npmrc"
sh "echo registry=${env.VERDACCIO_REGISTRY_URL} >> .npmrc"
echo ".npmrc configured."
}
// Install dependencies (might run prepublish scripts)
echo "Running npm install..."
sh "npm install"
}
}
}
}
stage("Publish") {
when {
expression { return currentBuild.result != "ABORTED" }
}
steps {
// Operate within the project directory
dir(env.PROJECT_PATH) {
script {
// Use the version read from package.json
echo "Publishing package version ${packageVersionFromFile} to ${env.VERDACCIO_REGISTRY_URL}"
try {
// Publish using npm (reads package.json for name/version, uses .npmrc for auth/registry)
sh "npm publish --registry ${env.VERDACCIO_REGISTRY_URL}"
echo "Package version ${packageVersionFromFile} published successfully!"
} catch (err) {
echo "ERROR: Failed to publish package!"
error "Publish failed: ${err.getMessage()}"
}
}
}
}
}
// // (Optional) Tag commit with the existing version from package.json
// stage("Tag Existing Version") {
// // Only run on overall success so far
// when { expression { currentBuild.result == null || currentBuild.result == "SUCCESS" } }
// steps {
// // Operate within the project directory
// dir(env.PROJECT_PATH) {
// script {
// echo "Tagging commit with existing version v${packageVersionFromFile}..."
// // Inject Git credentials (Username = Git user, Password = Access Token)
// withCredentials([usernamePassword(credentialsId: env.GIT_CREDENTIAL_ID, usernameVariable: "GIT_USERNAME", passwordVariable: "GIT_ACCESS_TOKEN")]) {
// // Configure Git user (may not be needed if just tagging)
// sh "git config user.email \"vanthanh1998@gmail.com\"" // EDIT Or use a specific user
// sh "git config user.name \"ThanhDVs Jenkins\""
// // NO commit needed here as we didn"t change package.json version via npm version
// // Create annotated tag using the version from package.json
// sh "git tag -a v${packageVersionFromFile} -m \"Release v${packageVersionFromFile}\"" // Use the read version
// // Push tag using HTTPS URL with embedded token
// def repoUrl = scm.userRemoteConfigs[0].url
// if (!repoUrl || !repoUrl.startsWith("https://")) {
// error "Could not determine HTTPS repository URL from SCM configuration."
// }
// def repoUrlClean = repoUrl.replaceAll(/https?:\/\/[^\/]+@/, "https://")
// def pushUrl = repoUrlClean.replaceFirst("https://", "https://${GIT_USERNAME}:${GIT_ACCESS_TOKEN}@")
// // Push only the tag
// sh "git push ${pushUrl} refs/tags/v${packageVersionFromFile}:refs/tags/v${packageVersionFromFile}"
// echo "Version tag v${packageVersionFromFile} pushed successfully."
// }
// }
// }
// }
// }
}
// Post-build actions
post {
// Always run cleanup
always {
echo "Build finished. Cleaning up..."
// Clean up sensitive .npmrc file
dir(env.PROJECT_PATH) {
script {
try {
sh "rm -f .npmrc"
} catch (err) {
echo "Could not delete .npmrc (maybe it doesn't exist): ${err.getMessage()}"
}
}
}
}
// On success
success {
echo "Pipeline successful!"
// Save artifacts if need
// archiveArtifacts artifacts: '**/*.tgz', allowEmptyArchive: true
echo "Cleaning up workspace..."
deleteDir()
echo "Sending success notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "✅ Success: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} published package `${packageName}@${packageVersionFromFile}` successfully.\nBuild Log: ${env.BUILD_URL}.\nPackage URL: ${verdaccioPackageUrl}",
result: "SUCCESS",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
// On failure
failure {
echo "Pipeline failed!"
echo "Sending failure notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "❌ Failure: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} failed to publish package `${packageName}`.\nBuild Log: ${env.BUILD_URL}",
result: "FAILURE",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
aborted {
echo "Pipeline aborted!"
echo "Sending abort notification to Discord..."
script {
// Send
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "ℹ️ Aborted: ${env.JOB_NAME}",
description: "Build #${env.BUILD_NUMBER} for job `${env.JOB_NAME}` was aborted.",
result: "ABORTED",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
unstable {
echo "Pipeline unstable!"
echo "Sending unstable notification to Discord..."
script {
withCredentials([string(credentialsId: "${env.DISCORD_WEBHOOK}", variable: 'DISCORD_WEBHOOK_URL_SECRET')]) {
discordSend(
webhookURL: DISCORD_WEBHOOK_URL_SECRET,
title: "⚠️ Unstable: ${env.JOB_NAME}",
description: "Job `${env.JOB_NAME}` build #${env.BUILD_NUMBER} finished with unstable status during processing of package `${packageName}`.\nBuild Log: ${env.BUILD_URL}",
result: "UNSTABLE",
link: env.BUILD_URL,
footer: "Jenkins Build Notification"
)
}
}
}
}
}
```
# CI/CD cho Verdaccio với GitHub Actions
### Lý do chuyển từ Jenkins sang GitHub Actions
#### Đơn giản hóa cài đặt và bảo trì
Jenkins là một hệ thống lâu đời với rất nhiều plug-in phức tạp. Khi cài đặt và bảo trì rất dễ gặp vấn đề với các plug-in.
Với GitHub Actions. GitHub đã lo phần quản lý máy chủ và bạn có thể tùy chọn triển khai Runner (tương tự Agent) hoặc chọn sử dụng Runner của GitHub (miễn phí có giới hạn).
#### Đơn giản hóa quy trình
Khi code được lưu trữ trên GitHub bạn sẽ dễ dàng cài đặt và kích hoạt quy trình. Không cần phải config webhook để nối từ GitHub sang Jenkins.
#### Cộng đồng mạnh mẽ
Với GitHub Actions bạn có thể tận dụng sức mạnh của cộng đồng GameCI đã tạo sẵn các Action cực kỳ mạnh được nhiều người kiểm chứng. Giúp bạn tiết kiệm được cả đống thời gian viết và sửa lỗi kịch bản.
#### Tính ổn định cao và gần như miễn phí
So với self-host mình đang có thì hạ tầng của GitHub vượt trội hơn về mọi mặt. Từ sức mạnh xử lý, tính ổn định...
Với người dùng miễn phí GitHub Actions giới hạn 2000 phút với các repo private. Các repo của mình chủ yếu là public, và tốc độ publish là rất nhanh (chỉ khoảng 15s) thì GitHub Actions có thể coi là miễn phí đối với mình
### Các bước thực hiện
#### Tạo biến môi trường
Chúng ta cần chuẩn bị 2 biến môi trường để lưu trữ token đăng nhập Verdaccio (`VERDACCIO_TOKEN`) và Discord Webhook (`DISCORD_WEBHOOK`)
Lấy Verdaccio token
1. Chạy lệnh `npm login --registry https://youraddress.com`
2\. Tiến hành đăng nhập
3.1 Trên Windows
Mở hộp thoại Run (Win + R) và điền `%USERPROFILE%\.npmrc` và Enter
3.2 Trên MacOS/Linux
Dùng lệnh `cat ~/.npmrc`
4\. Bạn thấy dòng có dạng sau
`//youraddress.com/:_authToken="npm_xxxxxxxxxxxxxxxxx_xxxxxxxxxxxx"`
Phần nằm trong dấu nháy kép chính là token bạn cần.
Lấy Discord webhook
1\. Truy cập server của bạn
2\. Mở settings của channel bạn muốn nhận tin nhắn
3\. Chọn mục Integrations (tích hợp) > Webhook
4\. Tại đây thêm mới hoặc sao lấy URL Webhook đã có.