Guide: Accessing & Using Internal Packages

Purpose

Enable developers to discover, authenticate, install, and safely use internal packages (shared libraries, SDKs, UI kits) across projects—without security or versioning issues.

Scope

• Applies to all projects using private registries or internal repos.
• Covers discovery → access/auth → install → update → troubleshooting → deprecation/migration.
• Tech-agnostic with examples for Node (npm/yarn/pnpm), Python (pip/Poetry), Java (Maven/Gradle), iOS (CocoaPods/SPM), Flutter (pub).

Objectives

• Standardize how internal packages are consumed.
• Ensure secure access (tokens, least-privilege).
• Reduce breakage via semantic versioning & pinning.
• Create a clear path for updates and deprecations.

Step-by-Step Usage

Step 1 — Discover the right package

1. Open the Internal Package Catalog (Notion/Confluence page or Nexus/Artifactory index).
2. Filter by language → capability → status (stable/experimental/deprecated).
3. Read the README & CHANGELOG for install instructions and breaking changes.
4. Confirm compatibility matrix (runtime versions, platform, frameworks).

If the package is missing, submit a New Package Request (template at the end).

Step 2 — Get access (one-time)

A. Obtain credentials

• Request scoped access via “Access Request & Tool Provisioning Workflow” (EPIC 1 – Doc 7).
• Receive token via the secrets manager (never via chat/email).

B. Configure your client

Node (npm/yarn/pnpm)

Create/update ~/.npmrc (user-level) or use project-level .npmrc:

# Example for GitHub Packages
@our-scope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}always-auth=true

Python (pip/Poetry)

Create/update ~/.pip/pip.conf (Windows: %APPDATA%\pip\pip.ini) or project pip.conf:

[global]index-url = https://<user>:${PIP_TOKEN}@pypi.our-internal.com/simple

Poetry:

# pyproject.toml[[tool.poetry.source]]name = "internal"url = "https://pypi.our-internal.com/simple"priority = "primary"

Java (Maven/Gradle)

Maven ~/.m2/settings.xml:

<servers>
  <server>
    <id>internal</id>
    <username>${env.ART_USER}</username>
    <password>${env.ART_TOKEN}</password>
  </server>
</servers>

pom.xml:

<repositories>
  <repository>
    <id>internal</id>
    <url>https://maven.our-internal.com/repository/releases</url>
  </repository>
</repositories>

iOS (CocoaPods / SPM)

CocoaPods ~/.netrc or keychain credentials; Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://git.our-internal.com/ios-specs.git'

SPM: Add internal Git URL in Xcode → Package Dependencies (use SSH).

Flutter (pub)

version: ^1.2.0

Security: Store tokens in env vars (e.g., NPM_TOKEN, ART_TOKEN) injected by your shell/profile or direnv—never commit to VCS.

Step 3 — Install & pin versions

Node

npm i @our-scope/feature-lib@^2.3.0
# or
yarn add @our-scope/feature-lib@~2.3.4

• Use ^ to accept minor & patch updates, ~ for patch-only, or exact for strict pinning (critical paths).

Python

pip install our-sdk==1.4.2
# Poetry
poetry add our-sdk@^1.4

Java

<dependency>
  <groupId>com.our</groupId>
  <artifactId>core-sdk</artifactId>
  <version>1.5.3</version>
</dependency>

iOS

pod 'OurSDK', '~> 1.4'# or SPM exact/range in Xcode UI

our_sdk: ^1.4.0

Governance & Standards

Versioning & Stability

• All internal packages must use SemVer: MAJOR.MINOR.PATCH.
• Breaking changes → bump MAJOR and provide migration notes.
• Consumers should pin (~) or lock (lockfile) for deterministic builds.

Security & Access

• Tokens are scoped (read-only for consumers).
• Tokens live in vault and are injected via CI or local secrets; no plaintext in repos.
• Remove access when a developer rolls off the project (EPIC 7 – Security).

Quality Signals (before adoption)

• Package must have: README, CHANGELOG, LICENSE (internal), tests ≥ 70% cov, CI status badge, semantic-release or documented release process.

Deprecation Policy

• Mark as Deprecated in Catalog with EOL date and migration path.
• Provide a compat layer or codemod where feasible.
• Communicate via release notes + #dev-announcements.

Troubleshooting (Quick Reference)

Templates & Snippets

1) .npmrc (project–level)

@our-scope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}always-auth=true

2) pip.conf (project-level)

[global]index-url = https://<user>:${PIP_TOKEN}@pypi.our-internal.com/simple
timeout = 60

3) CHANGELOG format (keepachangelog style)

## [2.3.0] - 2025-08-01### Added- New AuthClient.refreshToken()

### Fixed- Retry logic for 429

### Breaking- Removed deprecated `AuthClient.legacyLogin()`  - Migrate to `AuthClient.login(email, otp)`

4) Deprecation Notice (maintainer → consumers)

**Package**: @our-scope/logger
**Status**: DEPRECATED
**EOL**: 2025-12-31
**Replacement**: @our-scope/telemetry
**Migration**:
1) Replace imports
2) Update config key `logger.level` → `telemetry.logLevel`
3) Remove manual batching; built-in exporter enabled by default

5) New Package Request (submit in portal)

Do’s & Don’ts

Do’s

• Use scoped tokens and project-level config where possible.
• Pin or lock versions for deterministic builds.
• Read CHANGELOG before updates; test migrations on a branch.
• Log issues with repro, logs, and env.

Don’ts

• Don’t commit tokens or .env to VCS.
• Don’t auto-upgrade majors in CI.
• Don’t publish internal code to public registries.
• Don’t fork & drift—contribute upstream to the internal package.