참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.
소개
이 가이드에서는 Node.js 코드를 빌드하고 테스트하는 CI(연속 통합) 워크플로를 만드는 방법을 보여 줍니다. CI 테스트에 통과하면 코드를 배포하거나 패키지를 게시할 수 있습니다.
필수 조건
Node.js, YAML, 워크플로 구성 옵션과 워크플로 파일을 만드는 방법을 기본적으로 이해하는 것이 좋습니다. 자세한 내용은 다음을 참조하세요.
- "워크플로 작성"
- “Node.js 시작”
GitHub Enterprise Server에서 자체 호스팅 실행기 사용
실행기를 자체 호스팅하는 GitHub Enterprise Server에서 actions/setup-LANGUAGE
같은 설정 작업을 사용할 경우 인터넷에 액세스할 수 없는 실행기에서 도구 캐시를 설정해야 할 수 있습니다. 자세한 정보는 "인터넷에 액세스할 수 없는 자체 호스팅 실행기에서 도구 캐시 설정"을(를) 참조하세요.
Node.js 워크플로 템플릿 사용
빠르게 시작하려면 워크플로 템플릿을 리포지토리의 .github/workflows
디렉터리에 추가합니다.
GitHub는 대부분의 Node.js 기반 Java 프로젝트에서 작동하는 Node.js 워크플로 템플릿을 제공합니다. 이 가이드의 후속 섹션에서는 이 워크플로 템플릿을 사용자 지정하는 방법에 대한 예시를 제공합니다.
-
GitHub에서 리포지토리의 기본 페이지로 이동합니다.
-
리포지토리 이름 아래에서 작업을 클릭합니다.
-
리포지토리에 워크플로가 이미 있는 경우 새 워크플로를 클릭합니다.
-
"워크플로 선택" 페이지에는 권장되는 워크플로 템플릿의 선택 항목이 표시됩니다. "Node.js"를 검색합니다.
-
지속적 통합을 클릭하여 워크플로 선택을 필터링합니다.
-
"Node.js" 워크플로에서 구성을 클릭합니다.
“Node.js” 워크플로 템플릿을 찾을 수 없는 경우 다음 워크플로 코드를 리포지토리의
.github/workflows
디렉터리에 있는 이름이node.js.yml
인 새 파일에 복사합니다.YAML name: Node.js CI on: push: branches: [ "main" ] pull_request: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [18.x, 20.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - uses: actions/checkout@v4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: 'npm' - run: npm ci - run: npm run build --if-present - run: npm test
name: Node.js CI on: push: branches: [ "main" ] pull_request: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [18.x, 20.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: - uses: actions/checkout@v4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: 'npm' - run: npm ci - run: npm run build --if-present - run: npm test
-
필요에 따라 워크플로를 편집합니다. 예를 들어 사용하려는 노드 버전을 변경합니다.
-
변경 내용 커밋을 클릭합니다.
Node.js 버전 지정
Node.js 버전을 지정하는 가장 쉬운 방법은 GitHub에서 제공하는 setup-node
작업을 사용하는 것입니다. 자세한 내용은 setup-node
를 참조하세요.
이 setup-node
작업은 Node.js 버전을 입력으로 사용하고 실행기에서 해당 버전을 구성합니다. setup-node
작업은 각 실행기의 도구 캐시에서 Node.js의 특정 버전을 찾아 필수 이진 파일을 PATH
에 추가합니다. 이 이진 파일은 나머지 작업 동안 유지됩니다. setup-node
작업을 사용하는 것은 다양한 실행기 및 Node.js 버전 간에 일관된 동작을 보장하므로 GitHub Actions로 Node.js를 사용하는 데 권장되는 방법입니다. 자체 호스트 실행기를 사용하는 경우 Node.js를 설치하고 이를 PATH
에 추가해야 합니다.
워크플로 템플릿에는 node-version
에 나열된 Node.js 버전으로 코드를 빌드하고 테스트하는 행렬형 전략이 포함되어 있습니다. ‘x’는 버전에 사용할 수 있는 최신 부 버전 및 패치 릴리스와 일치하는 와일드카드 문자입니다. node-version
배열에 지정된 Node.js의 각 버전은 동일한 단계를 실행하는 작업을 만듭니다.
각 작업은 matrix
컨텍스트를 사용하여 매트릭스 node-version
배열에 정의된 값에 액세스할 수 있습니다. setup-node
작업은 컨텍스트를 node-version
입력으로 사용합니다. setup-node
작업은 코드를 빌드하고 테스트하기 전에 다른 Node.js 버전으로 각 작업을 구성합니다. 행렬 전략 및 컨텍스트에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 및 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을(를) 참조하세요.
strategy: matrix: node-version: ['18.x', '20.x'] steps: - uses: actions/checkout@v4 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }}
strategy:
matrix:
node-version: ['18.x', '20.x']
steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
또는 정확한 Node.js 버전으로 빌드하고 테스트할 수 있습니다.
strategy: matrix: node-version: ['10.17.0', '17.9.0']
strategy:
matrix:
node-version: ['10.17.0', '17.9.0']
단일 버전의 Node.js를 사용하여 빌드하고 테스트할 수도 있습니다.
name: Node.js CI on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - run: npm ci - run: npm run build --if-present - run: npm test
name: Node.js CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- run: npm ci
- run: npm run build --if-present
- run: npm test
Node.js 버전을 지정하지 않으면 GitHub에서 환경의 기본 Node.js 버전을 사용합니다. 자세한 내용은 "GitHub 호스팅 실행기 사용" 항목을 참조하세요.
종속성 설치
GitHub 호스트 실행기에는 npm 및 Yarn 종속성 관리자가 설치되어 있습니다. 코드를 빌드하고 테스트하기 전에 npm 및 Yarn을 사용하여 워크플로에 종속성을 설치할 수 있습니다. Windows 및 Linux GitHub호스트 실행기에도 Grunt, Gulp, Bower가 설치되어 있습니다.
종속성을 캐시하여 워크플로 속도를 높일 수도 있습니다. 자세한 내용은 "워크플로 속도를 높이기 위한 종속성 캐싱"을(를) 참조하세요.
npm을 사용한 예시
이 예시에서는 package-lock.json 또는 npm-shrinkwrap.json 파일에 버전을 설치하고 잠금 파일이 업데이트를 방지합니다. 일반적으로 npm ci
를 사용하는 것이 npm install
을 실행하는 것보다 빠릅니다. 자세한 내용은 npm ci
및 “더 빠르고 안정적인 빌드를 위한 npm ci
소개”를 참조하세요.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - name: Install dependencies run: npm ci
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- name: Install dependencies
run: npm ci
npm install
을(를) 사용하면 package.json 파일에 정의된 종속성이 설치됩니다. 자세한 내용은 npm install
를 참조하세요.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - name: Install dependencies run: npm install
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- name: Install dependencies
run: npm install
Yarn을 사용한 예시
이 예시에서는 yarn.lock 파일에 정의된 종속성을 설치하고 yarn.lock 파일에 대한 업데이트를 방지합니다. 자세한 내용은 yarn install
를 참조하세요.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - name: Install dependencies run: yarn --frozen-lockfile
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- name: Install dependencies
run: yarn --frozen-lockfile
또는 package.json 파일에 정의된 종속성을 설치할 수 있습니다.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - name: Install dependencies run: yarn
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- name: Install dependencies
run: yarn
프라이빗 레지스트리를 사용하고 .npmrc 파일을 만드는 예시
setup-node
작업을 사용하여 기본 레지스트리 및 범위를 구성하는 실행기에서 로컬 .npmrc 파일을 만들 수 있습니다. 또한 setup-node
작업은 프라이빗 레지스트리에 액세스하거나 노드 패키지를 게시하는 데 사용되는 입력으로 인증 토큰을 허용합니다. 자세한 내용은 setup-node
를 참조하세요.
프라이빗 레지스트리에 인증하려면 npm 인증 토큰을 비밀로 저장해야 합니다. 예를 들어 NPM_TOKEN
이라는 레지스트리 비밀을 만듭니다. 자세한 내용은 "GitHub Actions에서 비밀 사용"을(를) 참조하세요.
아래 예시에서 비밀 NPM_TOKEN
은 npm 인증 토큰을 저장합니다. setup-node
작업은 NODE_AUTH_TOKEN
환경 변수에서 npm 인증 토큰을 읽도록 .npmrc 파일을 구성합니다. setup-node
작업을 사용하여 .npmrc 파일을 만들 때 npm 인증 토큰이 포함된 비밀로 NODE_AUTH_TOKEN
환경 변수를 설정해야 합니다.
종속성을 설치하기 전에 setup-node
작업을 사용하여 .npmrc 파일을 만듭니다. 작업에는 두 개의 입력 매개 변수가 있습니다. node-version
매개 변수는 Node.js 버전을 설정하고 registry-url
매개 변수는 기본 레지스트리를 설정합니다. 패키지 레지스트리에서 범위를 사용하는 경우 scope
매개 변수를 사용해야 합니다. 자세한 내용은 npm-scope
를 참조하세요.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: always-auth: true node-version: '20.x' registry-url: https://registry.npmjs.org scope: '@octocat' - name: Install dependencies run: npm ci env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
always-auth: true
node-version: '20.x'
registry-url: https://registry.npmjs.org
scope: '@octocat'
- name: Install dependencies
run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
위의 예시에서는 다음 콘텐츠가 포함된 .npmrc 파일을 만듭니다.
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true
종속성 캐싱 예시
setup-node
작업을 사용하여 종속성을 캐시하고 복원할 수 있습니다.
다음 예시에서는 npm에 대한 종속성을 캐시합니다.
steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - run: npm install - run: npm test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm install
- run: npm test
다음 예시에서는 Yarn에 대한 종속성을 캐시합니다.
steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'yarn' - run: yarn - run: yarn test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'yarn'
- run: yarn
- run: yarn test
다음 예시에서는 pnpm(v6.10 이상)에 대한 종속성을 캐시합니다.
# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다. # 작업은 타사에서 제공하며 # 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다. # 참조하세요. # NOTE: pnpm caching support requires pnpm version >= 6.10.0 steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad with: version: 6.10.0 - uses: actions/setup-node@v4 with: node-version: '20' cache: 'pnpm' - run: pnpm install - run: pnpm test
# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.
# NOTE: pnpm caching support requires pnpm version >= 6.10.0
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
with:
version: 6.10.0
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
사용자 지정 요구사항이 있거나 캐싱에 대한 세부적인 제어가 필요한 경우 cache
작업을 사용할 수 있습니다. 자세한 내용은 "워크플로 속도를 높이기 위한 종속성 캐싱"을(를) 참조하세요.
코드 빌드 및 테스트
코드를 빌드하고 테스트하기 위해 로컬에서 사용하는 것과 동일한 명령을 사용할 수 있습니다. 예를 들어 npm run build
를 실행하여 package.json 파일에 정의된 빌드 단계를 실행하고 npm test
를 실행하여 테스트 모음을 실행하는 경우 워크플로 파일에 해당 명령을 추가합니다.
steps: - uses: actions/checkout@v4 - name: Use Node.js uses: actions/setup-node@v4 with: node-version: '20.x' - run: npm install - run: npm run build --if-present - run: npm test
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test
워크플로 데이터를 아티팩트로 패키지
빌드 및 테스트 단계에서 아티팩트를 저장하여 작업이 완료된 후 볼 수 있습니다. 예를 들어 로그 파일, 코어 덤프, 테스트 결과 또는 스크린샷을 저장해야 할 수 있습니다. 자세한 내용은 "워크플로에서 데이터 저장 및 공유"을(를) 참조하세요.
패키지 레지스트리에 게시
CI 테스트에 통과하면 Node.js 패키지를 패키지 레지스트리에 게시하도록 워크플로를 구성할 수 있습니다. npm 및 GitHub Packages에 게시하는 방법에 대한 자세한 내용은 “Node.js 패키지 게시”를 참조하세요.