npm 패키지 게시 가이드라인

요약

GitLab은 프로젝트 내부와 프로젝트 사이의 코드 재사용성과 모듈성을 높이는 수단으로 npm 패키지를 사용합니다. 이 가이드라인을 따르면 NPM 패키지를 안전하고 신뢰할 수 있게 게시할 수 있으며, GitLab 생태계의 신뢰와 일관성을 높일 수 있습니다.

GitLab은 프로젝트 내부와 프로젝트 사이의 코드 재사용성과 모듈성을 높이는 수단으로 npm 패키지를 사용합니다. 이 문서에서는 npmjs.com에 npm 패키지를 안전하게 게시하기 위한 모범 사례와 가이드라인을 설명합니다.

이 가이드라인을 따르면 NPM 패키지를 안전하고 신뢰할 수 있게 게시할 수 있으며, GitLab 생태계의 신뢰와 일관성을 높일 수 있습니다.

npm 계정 설정#

npmjs.com에서 계정을 생성할 때는 GitLab 회사 이메일 ID를 사용합니다.
보안을 강화하기 위해 이중 인증(2FA)을 활성화합니다.
계정 변경 사항(예: 이메일 변경, 소유권 이전)은 이슈를 통해 직접 책임을 지는 팀에 공유합니다.

패키지 게시 가이드라인#

보안 및 소유권#

npm 별칭을 사용한다면 별칭이 가리키는 패키지가 정당하고 안전한지 확인합니다. npm info <yourpackage> alias를 실행하면 해당 별칭이 무엇을 가리키는지 확인할 수 있습니다. 모든 별칭이 신뢰할 수 있는 정당한 패키지를 가리키는지 확신할 수 있어야 합니다.
GitLab 프로젝트에서 다음을 활성화하여 npm 레지스트리(예: npmjs.com, GitLab npm 레지스트리 등)에 시크릿이 게시되지 않도록 합니다.
- 시크릿 푸시 보호
- 시크릿 탐지
레지스트리와 상호 작용하는 데 사용하는 NPM 토큰을 안전하게 관리합니다.
- OpenBao 나 Vault 같은 외부 시크릿 저장소 사용을 적극적으로 검토합니다
- 최소한 GitLab CI/CD 파이프라인의 환경 변수에 토큰을 안전하게 저장하고 마스킹과 보호가 활성화되어 있는지 확인합니다.
- 로컬 머신의 안전하지 않은 위치에 토큰을 저장하지 않습니다. 대신 1Password에 토큰을 저장하고, 셸 프로필, .npmrc, .env처럼 암호화되지 않은 파일에는 이러한 시크릿을 두지 않습니다.
패키지의 author로 gitlab-bot을 추가합니다. 이렇게 하면 팀원의 오프보딩 과정에서 이메일이 유효하지 않게 되더라도 조직이 소유권을 유지합니다.

의존성 무결성#

잠금 파일(package-lock.json 또는 yarn.lock)을 사용하여 환경 전반에서 의존성의 일관성을 확보합니다.
특정 버전을 고정하고 악성 버전이나 취약한 버전으로의 의도치 않은 업그레이드를 막기 위해 의존성 고정·명시를 검토합니다. 이 경우 의존성 업그레이드 작업이 더 번거로워질 수 있습니다.
CI/CD 파이프라인에서는 npm install 대신 npm ci(또는 yarn install --frozen-lockfile)를 사용하여 잠금 파일에 정의된 그대로 의존성이 설치되도록 합니다.
잠금 파일의 무결성을 보호하려면 untamper-my-lockfile을 실행합니다.

CI/CD 전용 게시 강제#

패키지는 로컬 개발자 머신이 아니라 보호된 브랜치의 GitLab CI/CD 파이프라인에서만 게시해야 합니다. 이렇게 하면 다음을 보장할 수 있습니다.

시크릿을 안전하게 관리합니다
워크플로가 문서화되고 자동화되므로 팀원 간 인수인계가 매끄럽습니다.
우발적인 노출이나 무단 게시의 위험을 최소화합니다.

GitLab CI/CD를 통한 게시를 설정하는 절차는 다음과 같습니다.

.gitlab-ci.yml에 패키지를 게시하는 job을 구성합니다. 예시는 아래에 있습니다
NPM 토큰을 안전하게 저장합니다. OpenBAO 나 Vault 같은 외부 시크릿 저장 도구를 사용하는 방식이 될 수 있습니다. 최후의 수단으로는 마스킹과 보호를 활성화한 GitLab CI/CD 변수를 사용합니다.
게시 전에 시크릿 탐지와 코드 품질 검사 단계가 파이프라인에 포함되어 있는지 확인합니다.

레지스트리 접근 보안#

다른 사용자에 의한 네임스페이스 오염이나 이름 선점을 막기 위해 스코프 패키지(@organization-name/package-name)를 사용합니다.
레지스트리 권한을 제한합니다.
- 조직 전용 NPM 스코프를 사용하고 패키지 접근이나 게시에 대한 권한을 강제합니다.

패키지 메타데이터 보안#

package.json 파일에 민감한 정보가 노출되지 않도록 합니다.
- 시크릿이나 내부 URL(예: 비공개 API 엔드포인트)이 포함되지 않았는지 확인합니다.
- 게시되는 패키지에 필요한 파일만 명시적으로 포함되도록 package.json의 files를 제한합니다.
패키지를 공개할 의도가 아니라면 publishConfig.access: 'restricted'로 공개 범위를 제어합니다.

CI/CD 구성 예시#

다음은 NPM 패키지를 게시하는 .gitlab-ci.yml 구성 예시입니다. 이 코드 블록은 그대로 사용하기 위한 것이 아니며 구성에 따라 수정이 필요합니다. 즉, 아래 예시에 npmjs 게시 토큰의 위치를 반영하도록 수정해야 합니다.

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: node:22
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: node:22
  script:
    - npm ci
    - npm run build

publish:
  stage: deploy
  image: node:22
  script:
    - npm ci
    - npm run build
    - npm publish
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

패키지 보안 모범 사례#

무단 게시를 막기 위해 패키지 게시에 npm 2FA를 활성화합니다.
프로젝트에 의존성 스캔을 활성화하고 취약점 보고서를 정기적으로 검토합니다.
게시된 패키지에 비정상적인 활동이나 무단 업데이트가 없는지 모니터링합니다.
사용자와 명확하게 소통할 수 있도록 README.md에 패키지의 목적과 범위를 문서화합니다.

안전한 패키지 이름 예시#

unique-package: GitLab에 한정되지 않은 일반 패키지입니다.
existing-package-gitlab: GitLab 전용 수정 사항이 반영된 포크 패키지입니다.
@gitlab/specific-package: GitLab 내부용으로 개발된 패키지입니다.

로컬 시크릿 및 수동 게시 방지#

다음을 보장하기 위해 수동 워크플로는 피해야 합니다.

시크릿의 안전한 유지: 토큰과 기타 민감한 정보는 안전한 CI/CD 환경에만 존재해야 합니다.
일관되고 감사 가능한 워크플로: CI/CD 파이프라인은 모든 게시 단계가 반복 가능하고 문서화되도록 보장합니다.
복잡성 감소: 중앙화된 CI/CD 파이프라인은 프로젝트 인수인계를 단순하게 만들고 위험을 최소화합니다.