ship.zone/szci
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

BREAKING CHANGE(szci): Rename project from npmci to szci and migrate runtime to Deno; add compiled binaries, installer and wrapper; update imports, env handling and package metadata

Browse Source
This commit is contained in:
Jürgen Kunz
2025-10-26 15:23:56 +00:00
parent 4854d27a19
commit 88f64536c2
58 changed files with 1550 additions and 867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

682
readme.md
View File

@@ -1,30 +1,115 @@
# @ship.zone/npmci
A tool to enhance Node.js and Docker workflows within GitLab CI, providing various CI/CD utilities.
# @ship.zone/szci
## Install
**Serve Zone CI** - A powerful CI/CD tool for streamlining Node.js and Docker workflows within CI environments (GitLab CI, GitHub CI, Gitea CI). Now powered by Deno with standalone executables.
To install `@ship.zone/npmci`, you can use npm or yarn:
## ✨ Features
- 🚀 **Standalone Executables** - No Node.js installation required
- 🐳 **Docker Integration** - Build, tag, and push Docker images
- 📦 **NPM Management** - Install, test, and publish npm packages
- 🔧 **Node.js Version Management** - Install and switch between Node versions
- 🔐 **SSH Key Management** - Deploy SSH keys from environment variables
- ☁️ **Multi-Registry Support** - Push to multiple Docker registries
- 🎯 **Cross-Platform** - Binaries for Linux, macOS, and Windows
## 📥 Installation
### NPM (Recommended)
```sh
# Using npm
npm install @ship.zone/npmci
# Using yarn
yarn add @ship.zone/npmci
npm install -g @ship.zone/szci
```
## Usage
The package will automatically download the appropriate pre-compiled binary for your platform.
`npmci` is designed to streamline CI/CD processes, particularly in Docker and Node.js environments. The following sections illustrate its usage in various scenarios, from handling Node versions to building Docker images and more.
### From Source (Deno Required)
### 1. Integration with GitLab CI, GitHub CI, and Gitea CI
```sh
git clone https://code.foss.global/ship.zone/szci.git
cd szci
deno task compile
```
#### GitLab CI
## 🚀 Quick Start
An example of integrating `npmci` into a GitLab CI configuration could look like this:
```sh
# Install Node.js
szci node install stable
# Install dependencies
szci npm install
# Build Docker images
szci docker build
# Run tests
szci npm test
# Push Docker images
szci docker push registry.example.com
```
## 📖 Usage
### Node.js Management
```sh
# Install specific Node.js version
szci node install lts
szci node install stable
szci node install 18
# Install from .nvmrc
szci node install legacy
```
### NPM Commands
```sh
# Install dependencies
szci npm install
# Run tests
szci npm test
# Publish package
szci npm publish
```
### Docker Workflows
```sh
# Prepare Docker environment
szci docker prepare
# Build all Dockerfiles
szci docker build
# Push to registry
szci docker push registry.example.com
# Pull from registry
szci docker pull registry.example.com
# Test Dockerfiles
szci docker test
```
### SSH Key Management
```sh
# Deploy SSH keys from environment
szci ssh prepare
```
Set environment variables like `NPMCI_SSHKEY_1`, `NPMCI_SSHKEY_2`, etc.
## 🔧 CI/CD Integration
### GitLab CI
```yaml
image: hosttoday/ht-docker-node:npmci
image: denoland/deno:alpine
stages:
- prepare
@@ -32,463 +117,184 @@ stages:
- test
- deploy
default:
before_script:
- npmci node install stable
- npmci npm install
variables:
SZCI_VERSION: "latest"
before_script:
- deno install --allow-all --global --name szci https://code.foss.global/ship.zone/szci/raw/branch/master/mod.ts
# OR use the npm package:
# - npm install -g @ship.zone/szci
prepare:
stage: prepare
script:
- npmci prepare npm
- npmci prepare docker
- szci node install stable
- szci npm install
build:
stage: build
script:
- npmci docker build
- szci docker build
test:
stage: test
script:
- npmci npm test
- szci npm test
deploy:
stage: deploy
script:
- npmci publish npm
- npmci docker push
environment:
name: production
url: http://example.com
- szci docker push $CI_REGISTRY
only:
- master
```
#### GitHub Actions
Similarly, you can set up `npmci` in GitHub Actions:
### GitHub Actions
```yaml
name: CI Pipeline
on:
push:
branches:
- main
branches: [main]
jobs:
prepare:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Node.js
uses: actions/setup-node@v2
with:
node-version: '14'
- run: npm install -g @ship.zone/npmci
- run: npmci node install stable
- run: npmci npm install
build:
runs-on: ubuntu-latest
needs: prepare
steps:
- run: npmci docker build
- uses: actions/checkout@v3
test:
runs-on: ubuntu-latest
needs: build
steps:
- run: npmci npm test
- name: Install SZCI
run: npm install -g @ship.zone/szci
deploy:
runs-on: ubuntu-latest
needs: test
steps:
- run: npmci publish npm
- run: npmci docker push
- name: Setup Node.js
run: szci node install stable
- name: Install Dependencies
run: szci npm install
- name: Build Docker Images
run: szci docker build
- name: Run Tests
run: szci npm test
- name: Push Images
if: github.ref == 'refs/heads/main'
run: szci docker push ghcr.io
```
#### Gitea CI
Lastly, for Gitea CI:
```yaml
image: hosttoday/ht-docker-node:npmci
pipelines:
default:
- step:
name: Prepare
image: hosttoday/ht-docker-node:npmci
commands:
- npmci node install stable
- npmci npm install
- npmci prepare npm
- npmci prepare docker
- step:
name: Build
image: hosttoday/ht-docker-node:npmci
commands:
- npmci docker build
- step:
name: Test
image: hosttoday/ht-docker-node:npmci
commands:
- npmci npm test
- step:
name: Deploy
image: hosttoday/ht-docker-node:npmci
commands:
- npmci publish npm
- npmci docker push
```
### 2. Handle Node Versions
One of the core features of `npmci` is managing Node versions in your CI environment. You can specify which version of Node to install:
```typescript
import { Npmci } from '@ship.zone/npmci';
async function manageNodeVersions() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.nodejsManager.handleCli({
_: ['node', 'install', 'stable'] // Installs the latest stable version
});
await npmciInstance.nodejsManager.handleCli({
_: ['node', 'install', 'lts'] // Installs the Long-Term Support (LTS) version
});
await npmciInstance.nodejsManager.handleCli({
_: ['node', 'install', 'legacy'] // Installs a legacy version
});
await npmciInstance.nodejsManager.handleCli({
_: ['node', 'install', '14.17.0'] // Install a specific version of Node
});
}
manageNodeVersions().then(() => console.log('Node versions managed successfully.'));
```
### 3. Handling npm and Yarn Tasks
`npmci` provides numerous utilities to streamline npm and yarn workflow tasks within a CI/CD pipeline.
```typescript
import { Npmci } from '@ship.zone/npmci';
async function manageNpmTasks() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.npmManager.handleCli({ _: ['npm', 'install'] }); // Installs dependencies
await npmciInstance.npmManager.handleCli({ _: ['npm', 'test'] }); // Runs tests
await npmciInstance.npmManager.handleCli({ _: ['npm', 'publish'] }); // Publishes the package
}
manageNpmTasks().then(() => console.log('Npm tasks handled successfully.'));
```
### 4. Docker Task Handling
`npmci` simplifies Docker operations, particularly in building, testing, and publishing Docker images.
**Prepare Docker Environment:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function prepareDocker() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'prepare'] }); // Prepares Docker environment
}
prepareDocker().then(() => console.log('Docker environment prepared successfully.'));
```
**Building Docker Images:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function buildDockerImages() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'build'] }); // Builds Docker images
}
buildDockerImages().then(() => console.log('Docker images built successfully.'));
```
**Testing Docker Images:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function testDockerImages() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'test'] }); // Tests Docker images
}
testDockerImages().then(() => console.log('Docker images tested successfully.'));
```
**Publishing Docker Images:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function pushDockerImages() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'push'] }); // Pushes Docker images to registry
}
pushDockerImages().then(() => console.log('Docker images pushed successfully.'));
```
### 5. Managing Docker Registries
`npmci` can handle multiple Docker registries and allows for easy integration within your CI pipeline.
**Logging in to Docker Registries:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function loginToDockerRegistries() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'login'] }); // Logs into all configured Docker registries
}
loginToDockerRegistries().then(() => console.log('Logged into Docker registries.'));
```
**Pulling Docker Images:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function pullDockerImages() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'pull', 'registry.gitlab.com/mygroup/myrepo'] }); // Pulls Docker images from a registry
}
pullDockerImages().then(() => console.log('Docker images pulled successfully.'));
```
### 6. SSH Key Management
`npmci` also simplifies the management of SSH keys, which is crucial for accessing private repositories and servers.
**Preparing SSH Keys:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function prepareSshKeys() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.sshManager.handleCli({ _: ['ssh', 'prepare'] }); // Prepares SSH keys from environment variables
}
prepareSshKeys().then(() => console.log('SSH keys prepared successfully.'));
```
### 7. Cloudron Integration
For users deploying applications on Cloudron, `npmci` provides a set of utilities for automating Cloudron tasks.
**Deploying to Cloudron:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function deployToCloudron() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.cloudronManager.handleCli({
_: ['cloudron', 'deploy']
}); // Deploys application to Cloudron platform
}
deployToCloudron().then(() => console.log('Deployment to Cloudron completed.'));
```
**Preparing Cloudron Manifest:**
Before deployment, replace version placeholders in the Cloudron Manifest:
```typescript
import { Npmci } from '@ship.zone/npmci';
import * as fs from 'fs';
import * as path from 'path';
async function prepareCloudronManifest(version: string) {
const manifestPath = path.join(process.cwd(), "CloudronManifest.json");
let manifestFile = fs.readFileSync(manifestPath, { encoding: 'utf-8' });
manifestFile = manifestFile.replace(/##version##/g, version);
fs.writeFileSync(manifestPath, manifestFile);
console.log('CloudronManifest prepared');
}
async function deployWithPreparedManifest() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await prepareCloudronManifest('1.0.0');
await npmciInstance.cloudronManager.handleCli({
_: ['cloudron', 'deploy']
}); // Deploys application to Cloudron platform
}
deployWithPreparedManifest().then(() => console.log('Deployment to Cloudron with manifest preparation completed.'));
```
### 8. Webhook Triggers
`npmci` supports webhook triggers, allowing you to trigger builds and other activities based on various conditions.
**Triggering Webhooks:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function triggerWebhooks() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.triggerManager.handleCli({
_: ['trigger']
}); // Triggers webhooks based on environment variables
}
triggerWebhooks().then(() => console.log('Webhooks triggered successfully.'));
```
### 9. Using the bash Helper
`npmci` includes a bash helper for executing commands within a bash shell, useful for various custom tasks.
**Using bash to Execute Commands:**
```typescript
import { bash } from '@ship.zone/npmci';
async function runCustomBashCommand(command: string) {
const output = await bash(command);
console.log('Command output:', output);
}
runCustomBashCommand('echo Hello World').then(() => console.log('Custom command executed successfully.'));
```
### Full Features and Use Cases
Below is a comprehensive set of features and use cases supported by `npmci`. This section ensures you can take full advantage of the library's capabilities in multiple scenarios.
### Comprehensive Docker Workflow
**Step-by-step Docker Image Handling:**
1. **Detect and Build All Dockerfiles:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function detectAndBuildDockerfiles() {
const npmciInstance = new Npmci();
await npmciInstance.start();
const dockerfiles = await npmciInstance.dockerManager.getDockerfiles();
console.log('Dockerfiles detected:', dockerfiles.map(d => d.filePath));
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'build'] });
console.log('Dockerfiles built successfully.');
}
detectAndBuildDockerfiles().then(() => console.log('Docker detection and build process completed.'));
```
2. **Test All Dockerfiles:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function testAllDockerfiles() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'test'] });
console.log('Dockerfiles tested successfully.');
}
testAllDockerfiles().then(() => console.log('Docker testing process completed.'));
```
3. **Push Dockerfiles to a Registry:**
```typescript
import { Npmci } from '@ship.zone/npmci';
async function pushDockerfilesToRegistry() {
const npmciInstance = new Npmci();
await npmciInstance.start();
await npmciInstance.dockerManager.handleCli({ _: ['docker', 'push'] });
console.log('Dockerfiles pushed to registry successfully.');
}
pushDockerfilesToRegistry().then(() => console.log('Docker push process completed.'));
```
**Dockerfile Class Example:**
Here's a snippet showcasing how the `Dockerfile` class can be used to handle Dockerfile-specific operations:
```typescript
import { Dockerfile } from '@ship.zone/npmci';
async function handleDockerfileOperations() {
// Initialize Dockerfile instances
const dockerfile1 = new Dockerfile(/* required parameters */);
const dockerfile2 = new Dockerfile(/* required parameters */);
// Read and sort Dockerfiles
const dockerfiles = await Dockerfile.readDockerfiles(/* required parameters */);
const sortedDockerfiles = await Dockerfile.sortDockerfiles(dockerfiles);
// Build and Test Dockerfiles
await Dockerfile.buildDockerfiles(sortedDockerfiles);
await Dockerfile.testDockerfiles(sortedDockerfiles);
// Push Dockerfile images to a registry
for (const dockerfile of sortedDockerfiles) {
await dockerfile.push(/* registry and tag parameters */);
## ⚙️ Configuration
Create an `npmextra.json` file in your project root:
```json
{
"npmci": {
"npmGlobalTools": [],
"npmAccessLevel": "public",
"npmRegistryUrl": "registry.npmjs.org",
"dockerRegistries": [
"registry.gitlab.com"
],
"dockerRegistryRepoMap": {
"registry.gitlab.com": "mygroup/myrepo"
},
"dockerBuildargEnvMap": {
"ARG_NAME": "ENV_VAR_NAME"
}
}
console.log('Dockerfile operations completed successfully.');
}
handleDockerfileOperations().then(() => console.log('Dockerfile processing flow completed.'));
```
This completes the comprehensive guide to `@ship.zone/npmci`. With the examples and explanations provided, you should be able to harness the full power and flexibility of the library to streamline your CI/CD processes effectively.
undefined
## 🐳 Docker Registry Authentication
SZCI supports automatic authentication with:
- GitLab CI Registry (via `CI_JOB_TOKEN`)
- Custom registries via environment variables
Set `NPMCI_LOGIN_DOCKER*` environment variables:
```sh
NPMCI_LOGIN_DOCKER_1="registry.example.com|username|password"
NPMCI_LOGIN_DOCKER_2="another-registry.com|user2|pass2"
```
## 🏗️ Development
### Prerequisites
- Deno 1.40+ installed
### Building from Source
```sh
# Clone the repository
git clone https://code.foss.global/ship.zone/szci.git
cd szci
# Compile for all platforms
deno task compile
# Compile for current platform only
deno compile --allow-all --output szci mod.ts
# Run tests
deno task test
# Development mode
deno task dev --help
```
### Testing
Tests will be migrated to Deno's native test framework:
```sh
deno task test
```
## 📦 Binary Sizes
The standalone executables are approximately:
- Linux x64: ~800MB
- Linux ARM64: ~800MB
- macOS x64: ~796MB
- macOS ARM64: ~796MB
- Windows x64: ~804MB
Sizes include all dependencies and the Deno runtime.
## 🔄 Migration from npmci
If you're upgrading from the old `@ship.zone/npmci` package:
1. Update package references:
```sh
npm uninstall -g @ship.zone/npmci
npm install -g @ship.zone/szci
```
2. Update CI configuration files - replace `npmci` with `szci`
3. The command interface remains the same, only the binary name changed
## 📝 License
MIT © Lossless GmbH
## 🔗 Links
- [Repository](https://code.foss.global/ship.zone/szci)
- [Issues](https://code.foss.global/ship.zone/szci/issues)
- [Changelog](./changelog.md)
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
---
**Built with Deno 🦕**