InfoGrab DocsInfoGrab Docs

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와 같은 암호화되지 않은 파일에 이러한 시크릿을 저장하지 마세요.

  • 패키지 작성자로 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를 통한 게시를 설정하려면:

  • 패키지를 게시하기 위한 job을 .gitlab-ci.yml에 구성하세요. 예시는 아래에 제공되어 있습니다.

  • 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 파이프라인은 프로젝트 인수인계를 간소화하고 위험을 최소화합니다.

npm 패키지 게시 가이드라인

GitLab v19.1
원문 보기
요약

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와 같은 암호화되지 않은 파일에 이러한 시크릿을 저장하지 마세요.

  • 패키지 작성자로 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를 통한 게시를 설정하려면:

  • 패키지를 게시하기 위한 job을 .gitlab-ci.yml에 구성하세요. 예시는 아래에 제공되어 있습니다.

  • 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 파이프라인은 프로젝트 인수인계를 간소화하고 위험을 최소화합니다.