Many thanks for your prompt reply. With a lot of discussion with my GPT friend, I was able to get it up and running!. Here is my documentation for the process
______________________________________________________________________
LibrePCB Library Server on GitLab Pages
This guide explains how to publish your own LibrePCB library server using GitLab Pages.
Starting point: You already created a LibrePCB library:
Test_Library.lplib
The goal is to host it so LibrePCB can install it via a remote library source.
1. Create a Git Repository and Enable GitLab Pages
Create a new project on your GitLab instance.
Example:
librepcb-library-server
Clone it locally:
git clone git@gitlab.git.nrw:username/librepcb-library-server.git
cd librepcb-library-server
Create the GitLab Pages configuration file:
.gitlab-ci.yml
Content:
pages:
stage: deploy
script:
- echo "Publishing LibrePCB library server"
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
GitLab Pages publishes everything inside:
public/
Don’t forget to make GitLab Pages publicly accessible.
In your GitLab project:
Go to Settings
→ Open General
→ Find Visibility, project features, permissions
→ Look for Pages
→ Set it to Everyone
After pushing, the site will be available at:
https://<project>.pages.git.nrw/
2. Create the Directory Structure
Create the directories:
mkdir -p public/api/v1/libraries
mkdir -p public/libs
mkdir -p libraries
mkdir -p scripts
Directory purpose:
libraries/ → editable LibrePCB libraries (sources)
public/libs/ → zipped libraries for download
public/api/ → API JSON for LibrePCB
scripts/ → helper scripts
3. Add the Library Source
Copy your LibrePCB library into:
libraries/Test_Library.lplib
The library should contain:
.librepcb-lib
library.lp
sym/
pkg/
cmp/
dev/
4. Create the Library ZIP
LibrePCB downloads libraries as ZIP archives.
Create the ZIP file:
cd libraries/Test_Library.lplib
zip -r ../../public/libs/Test_Library.lplib.zip . -x ".lock"
cd ../../
Verify the archive:
unzip -l public/libs/Test_Library.lplib.zip
The root must contain:
.librepcb-lib
library.lp
5. Create the LibrePCB API JSON
Create the API endpoint file:
public/api/v1/libraries/v2
Example JSON:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": {
"default": "Test Library"
},
"description": {
"default": "Example LibrePCB library"
},
"keywords": {
"default": "example,test"
},
"author": "Your Name",
"version": "0.1",
"deprecated": false,
"url": "https://gitlab.git.nrw/username/librepcb-library-server",
"dependencies": [],
"component_categories": 0,
"package_categories": 0,
"symbols": 0,
"packages": 0,
"components": 0,
"devices": 0,
"recommended": true,
"updated_at": "2026-06-04T12:00:00+00:00",
"format_version": "2",
"icon_url": null,
"download_url": "https://<project>.pages.git.nrw/libs/Test_Library.lplib.zip",
"download_size": 12345,
"download_sha256": "abcdef123456..."
}
]
}
Explanation of JSON Fields
| Field |
Description |
| uuid |
Library UUID from library.lp |
| name |
Human readable library name |
| description |
Short description |
| keywords |
Search keywords |
| author |
Library author |
| version |
Library version |
| deprecated |
Mark library obsolete |
| url |
Homepage or repository |
| dependencies |
UUIDs of required libraries |
| component_categories |
Number of component categories |
| package_categories |
Number of package categories |
| symbols |
Number of symbols |
| packages |
Number of packages |
| components |
Number of components |
| devices |
Number of devices |
| recommended |
Suggest installation |
| updated_at |
ISO‑8601 timestamp |
| format_version |
Library format version |
| icon_url |
Optional icon |
| download_url |
Direct ZIP download link |
| download_size |
ZIP file size in bytes |
| download_sha256 |
SHA256 checksum |
6. Calculate File Size and SHA256
Calculate ZIP size:
stat -c %s public/libs/Test_Library.lplib.zip
Calculate SHA256:
sha256sum public/libs/Test_Library.lplib.zip
Insert these values into the JSON.
7. Push to GitLab
Commit everything:
git add .
git commit -m "Add Test Library"
git push
GitLab CI will publish the Pages site.
Test the API:
curl https://<project>.pages.git.nrw/api/v1/libraries/v2 | jq
this should return a working json file
8. Add the Server to LibrePCB
Open LibrePCB:
Workspace Settings → Internet
Enter:
https://<project>.pages.git.nrw/api/v1/libraries/v2
LibrePCB should now list and install the library.
9. Automation Script
Create:
scripts/build_library.sh
Content:
#!/bin/bash
LIBNAME=Test_Library.lplib
ZIP=public/libs/$LIBNAME.zip
cd libraries/$LIBNAME
zip -r ../../$ZIP . -x ".lock"
cd ../../
SIZE=$(stat -c %s $ZIP)
SHA=$(sha256sum $ZIP | cut -d " " -f1)
echo "Size: $SIZE"
echo "SHA256: $SHA"
Make executable:
chmod +x scripts/build_library.sh
Run:
scripts/build_library.sh
The script rebuilds the ZIP and prints the values needed for the JSON.
Result
You now have a fully working LibrePCB library server hosted on GitLab Pages.
Automatic Script
For those who want to use this setup in a production environment, automating the process is highly recommended. A script can extract the required information, generate the ZIP archives, and create the necessary directory structure and JSON metadata automatically.
You can find my current implementation attached: create_librePCB_json.sh. Just copy your libraries in the /libraries folder and the .sh script in the scripts folder of your git repo.
Feel free to use it and let me know if you have any suggestions or improvements.
Final advice: LibrePCB uses the version number in library.lp to determine whether a remote library needs to be updated. Therefore, whenever you publish a new version of your library, remember to update this version number as well.
