@deposition.cloud/node-pipeline v1.6.1

Node Pipeline Template

A batteries‑included GitLab CI/CD template that gives every Node.js project the same, battle‑tested pipeline in one line of YAML. Use it to ship NPM packages, publish Docker images, and generate changelogs automatically—without copying any YAML between repos.

✨ Vision

"Define a secure, repeatable, zero‑maintenance release workflow for every Node project in the organisation." Instead of bespoke .gitlab-ci.yml files, teams simply include this template and inherit a pipeline that already follows our best practices:

• Single source of truth – fixes & improvements land once, benefit everyone.
• Security by default – credentials are injected at runtime, never committed.
• Semantic, automated releases – human‑friendly versioning & changelogs.
• Multi‑registry publishing – GitLab ⇢ Docker Hub ⇢ GHCR in one shot.

🔑 Core Features

📚 Typical Use Cases

1. Private NPM libraries that should be versioned & installable via GitLab’s registry.
2. Microservices / CLIs that ship as Docker images to multiple registries.
3. Frontend apps that just want a lint→test→semantic‑release flow without extra wiring.

🚀 Quick Start

Add a single include in your project‑level .gitlab-ci.yml:

include:
  - project: "deposition.cloud/infra/devops/node-pipeline-template"
    file: "/.gitlab-ci-template.yml"

That’s it. The default jobs will build, test and release on every push/tag.

Required CI/CD variables

You can override or extend any job with extends:—for example, to add linting:

lint:
  extends: .unit   # runs before semantic‑release
  script:
    - npm run lint

Here’s a suggested 🧪 Development section you can add to the README to guide internal contributors working on this template:

🧪 Development

This repo is not a typical Node app — it’s a pipeline template. That means most development focuses on the following:

Key Areas to Modify

• .gitlab-ci-template.yml: add or improve reusable job blocks (e.g., .build, .semantic)
• release.config.ts: update semantic-release logic (e.g., new Docker registries or tagging logic)
• Dockerfile: adjust Node installation or improve CI image stages
• docs/CHANGELOG.md: is auto-updated by semantic-release
• package.json: only defines minimal scripts and dependencies required for CI

Local Testing

You don’t “run” this repo locally. But to validate changes:

1. Clone a test project that includes this template.

2. In that test project’s .gitlab-ci.yml, point to a specific branch or ref:

   include:
     - project: 'deposition.cloud/infra/devops/node-pipeline-template'
       ref: 'your-feature-branch'
       file: '/.gitlab-ci-template.yml'

3. Push and observe the CI pipeline behavior.

Publishing Changes

• All changes must follow Conventional Commits.

• Pushing to main triggers semantic-release, which:

  • bumps package.json
  • updates CHANGELOG.md
  • creates a GitLab release
  • publishes Docker images and NPM package

✅ Quick Local Build & Test

1. Build the image

You can build any stage explicitly using --target.

# To build the full release image (prod)
docker build -t node-pipeline-release .

# To build just the dev stage (includes node_modules, scripts)
docker build --target dev -t node-pipeline-dev .

# To build the test stage (runs lint & test scripts)
docker build --target test -t node-pipeline-test .

Add --progress=plain if you want more verbose output.

2. Run it

docker run --rm -it node-pipeline-dev

This will execute:

dumb-init npm run start

Which, in this template project, just logs Hello world!.

3. Override commands

To run custom scripts, override the default CMD:

# Open a shell
docker run --rm -it --entrypoint sh node-pipeline-dev

# Or run tests
docker run --rm -it --entrypoint npm node-pipeline-test run test

4. Use BuildKit cache (optional but faster)

DOCKER_BUILDKIT=1 docker build -t node-pipeline-dev .

You can also mount cache explicitly like CI does:

docker build \
  --build-arg BUILD_WORKDIR=/app \
  --mount type=cache,target=/app/.npm \
  -t node-pipeline-dev .

🛠 Pipeline Overview

🧩 How It Works

1. before_script writes .npmrc using templated $CI_API_V4_URL, $CI_JOB_TOKEN, namespace, and project ID.
2. Dockerfile installs Node 23 either via official binaries or source build (fallback for unusual arches), then defines dev, test, release stages.

3. release.config.ts wires semantic-release plugins:

   • GitLab release + Changelog + Git commit
   • @eclass/semantic-release-docker twice: once for ‑dev images, once for prod.

4. Versioning follows Conventional Commits; change the commit message → pipeline decides the next version.

🤝 Contributing

1. Fork & clone this repo.
2. npm ci
3. Make your change, commit using Conventional Commits.
4. Push → the pipeline will run locally; once merged, downstream projects get the new template via include: ref: pinning.

Please open MRs for:

• New pipeline features or job types
• Docs & examples
• Bug fixes in .npmrc handling, release workflow, or Dockerfile

🪪 License

Released under the Hippocratic 2.1 License — ethical open source. See LICENSE for details.