이 페이지에서는 Cloud Build를 사용하여 Node.js 애플리케이션을 빌드 및 테스트하고, Artifact Registry의 npm 저장소에 빌드된 아티팩트를 저장하고, 빌드 출처 정보를 생성하는 방법을 설명합니다.
Cloud Build를 사용하면 공개적으로 사용 가능한 컨테이너 이미지를 사용하여 작업을 실행할 수 있습니다. Docker Hub의 공개 node 이미지는 npm 도구가 사전 설치된 상태로 제공됩니다. 이 도구를 사용하여 Node.js 프로젝트를 빌드하도록 Cloud Build를 구성할 수 있습니다.
시작하기 전에
이 페이지의 안내는 사용자가 Node.js에 익숙하다고 가정합니다. 또한 다음 사항도 적용됩니다.
Docker Hub의 node 이미지에서 작업을 수행하려면 Cloud Build 구성 파일의 name 필드에 이미지 URL을 지정합니다.
Cloud Build는 이미지의 기본 진입점을 사용하여 name 필드에 지정된 컨테이너를 시작합니다. 기본 진입점을 재정의하고 호출된 빌드 단계의 실행 방법을 정의하려면 빌드 단계에서 entrypoint 필드를 추가합니다. Docker Hub의 node 이미지는 npm 도구가 사전 설치된 상태로 제공됩니다. 빌드 단계의 진입점으로 호출하도록 entrypoint 필드에 도구를 지정합니다.
빌드 구성 파일 예시는 다음과 같습니다.
name 필드는 Docker Hub의 node 이미지가 태스크 수행을 위해 Cloud Build에 사용되도록 지정합니다. node 이미지를 지정할 경우, 노드 버전을 생략하여 기본적으로 :latest가 사용되도록 하거나, 특정 버전을 사용하도록 노드 버전을 지정할 수 있습니다. 예를 들어 name: node는 노드의 최신 버전을 사용하고 name: node:12는 node:12를 사용합니다.
entrypoint 필드는 node 이미지가 호출될 때 npm 도구가 사용되도록 지정합니다.
steps:
- name: 'node'
entrypoint: 'npm'
Node.js 빌드 구성
프로젝트 루트 디렉터리에 cloudbuild.yaml이라는 구성 파일을 만듭니다.
종속 항목 설치: 애플리케이션을 빌드하려면 먼저 프로젝트의 모든 종속 항목이 npm에서 설치되었는지 확인해야 합니다. 종속 항목은 npm 빌드 단계 내에서 install 명령어를 사용하여 설치할 수 있습니다. 빌드 단계의 args 필드는 인수 목록을 가져와서 이름 필드로 참조되는 이미지에 전달합니다. 빌드 구성 파일에서 install을 args 필드에 추가하여 install 명령어를 호출합니다.
커스텀 명령어 실행: package.json에 커스텀 명령어가 포함된 경우 이 명령어를 실행하도록 Cloud Build를 구성할 수 있습니다. args 필드에서 run을 첫 번째 인수로 추가하고, 커스텀 명령어 이름을 지정합니다. 다음 빌드 구성 파일에는 build라는 커스텀 명령어를 실행하기 위한 인수가 포함되어 있습니다.
PACKAGE_PATH: Artifact Registry에 업로드하려는 npm 패키지가 포함된 로컬 디렉터리의 경로입니다. 절대 경로를 사용하는 것이 좋습니다. PACKAGE_PATH 값을 .로 설정하여 현재 작업 디렉터리를 사용할 수 있지만 이 필드는 생략하거나 비워둘 수 없습니다. 이 디렉터리에는 package.json 파일이 포함되어야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2024-12-21(UTC)"],[[["\u003cp\u003eCloud Build can be used to build and test Node.js applications using the public \u003ccode\u003enode\u003c/code\u003e image from Docker Hub, which comes pre-installed with the \u003ccode\u003enpm\u003c/code\u003e tool.\u003c/p\u003e\n"],["\u003cp\u003eYou can configure Cloud Build to install dependencies, run tests, and execute custom commands defined in your \u003ccode\u003epackage.json\u003c/code\u003e file within the \u003ccode\u003enode\u003c/code\u003e environment.\u003c/p\u003e\n"],["\u003cp\u003eBuilt artifacts can be uploaded to an npm repository in Artifact Registry by specifying the repository details and package path in your \u003ccode\u003ecloudbuild.yaml\u003c/code\u003e configuration file.\u003c/p\u003e\n"],["\u003cp\u003eCloud Build allows for generating verifiable SLSA build provenance metadata to enhance the security of your continuous integration pipeline.\u003c/p\u003e\n"],["\u003cp\u003eYou can run tests on multiple Node.js versions by using substitution variables in the build config file and creating separate Cloud Build triggers for each version.\u003c/p\u003e\n"]]],[],null,["# Build and test Node.js applications\n\nThis page explains how to use Cloud Build to build and test `Node.js`\napplications, store built artifacts in an npm repository in Artifact Registry, and\ngenerate build provenance information.\n\nCloud Build enables you to use any publicly available container image\nto execute your tasks. The public\n[`node` image from Docker Hub](https://hub.docker.com/_/node/)\ncomes preinstalled with the `npm` tool. You can configure Cloud Build\nto build your `Node.js` project with this tool.\n\nBefore you begin\n----------------\n\nThe instructions on this page assume that you are familiar with `Node.js`. In\naddition:\n\n- Be familiar with [npm](https://docs.npmjs.com/about-npm).\n- Have your `Node.js` project handy, including `package.json` and `test.js` files.\n- Make sure your `package.json` file includes a `start` script and a `test` script.\n- Be familiar with [how to write a Cloud Build configuration file](/build/docs/build-config).\n- Have an npm repository in Artifact Registry. If you don't have one, [create a new repository](/artifact-registry/docs/repositories/create-repos).\n- To run the `gcloud` commands in this page, install the [Google Cloud CLI](/sdk).\n\nBuilding with `npm`\n-------------------\n\nTo execute your tasks in the `node` image from Docker Hub, specify the image URL\nin the `name` field in the [Cloud Build config file](/build/docs/build-config-file-schema).\nCloud Build starts the container specified in the `name`\nfield using the image's default entrypoint. To override the default entrypoint\nand define how the build step should be run when it is invoked, add an\n`entrypoint` field in your build step. The `node` image in Docker Hub comes\npreinstalled with the `npm` tool. Specify the tools in the `entrypoint` field to\ninvoke them as the entrypoint of your build step.\n\nIn the following example build config file:\n\n- The `name` field specifies that the `node` image from Docker Hub is used by Cloud Build to execute your task. When you're specifying the `node` image, you can either omit the node version to default to `:latest`, or specify a [node version](https://hub.docker.com/_/node/) to use a specific version. For example, `name: node` will use the latest version of node, and `name: node:12` will use `node:12`.\n- The `entrypoint` field specifies that the `npm` tool is used\n when the `node` image is invoked.\n\n steps:\n - name: 'node'\n entrypoint: 'npm'\n\nConfiguring `Node.js` builds\n----------------------------\n\n1. In your project root directory, create a\n config file named `cloudbuild.yaml`.\n\n2. **Install dependencies** : Before you can build your application, you must\n ensure that all of your project's dependencies are installed from `npm`. You\n can install dependencies using the `install` command within the `npm` build\n step. The `args` field of a build step takes a list of arguments and passes\n them to the image referenced by the name field. In your build config file,\n add `install` to the `args` field to invoke the `install` command:\n\n steps:\n - name: 'node'\n entrypoint: 'npm'\n args: ['install']\n\n3. **Add tests** : If you've defined a `test` script in your `package.json`, you\n can configure Cloud Build to run the script by adding `test` to the\n `args` field:\n\n steps:\n - name: 'node'\n entrypoint: 'npm'\n args: ['install']\n - name: 'node'\n entrypoint: 'npm'\n args: ['test']\n\n4. **Run custom commands** : If your `package.json` contains any custom commands,\n you can configure Cloud Build to run that command. In the `args`\n field, add `run` as the first argument followed by the name of the custom\n command. The following build config file has arguments to run a custom\n command called `build`:\n\n steps:\n - name: 'node'\n entrypoint: 'npm'\n args: ['install']\n - name: 'node'\n entrypoint: 'npm'\n args: ['test']\n - name: 'node'\n entrypoint: 'npm'\n args: ['run', 'build']\n\n5. **Upload to Artifact Registry**:\n\n In your config file, add the `npmPackages` field and specify your npm\n repository in Artifact Registry: \n\n artifacts:\n npmPackages:\n - repository: 'https://\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e-npm.pkg.dev/\u003cvar translate=\"no\"\u003ePROJECT-ID\u003c/var\u003e/\u003cvar translate=\"no\"\u003eREPOSITORY_NAME\u003c/var\u003e'\n packagePath: '\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003ePACKAGE_PATH\u003c/span\u003e\u003c/var\u003e'\n\n Replace the following values:\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the [location](/artifact-registry/docs/repo-locations) for your repository in Artifact Registry.\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of the Google Cloud project that contains your Artifact Registry repository.\n - \u003cvar translate=\"no\"\u003eREPOSITORY_NAME\u003c/var\u003e: the name of your npm repository in Artifact Registry.\n - \u003cvar translate=\"no\"\u003ePACKAGE_PATH\u003c/var\u003e: the path for the local directory containing the npm package that you want to upload to Artifact Registry. We recommend using an absolute path. Your \u003cvar translate=\"no\"\u003ePACKAGE_PATH\u003c/var\u003e value can be `.` to use the current working directory, but the field cannot be omitted or left empty. This directory must contain a `package.json` file.\n6. **Optional: Enable provenance generation**\n\n Cloud Build can generate verifiable\n [Supply chain Levels for Software Artifacts (SLSA)](https://slsa.dev/) build\n provenance metadata to help secure your continuous integration pipeline.\n\n To enable provenance generation, add\n [`requestedVerifyOption: VERIFIED`](/build/docs/build-config-file-schema#options)\n to the `options` section in your config file.\n7. **Start your build** : [manually](/build/docs/running-builds/start-build-manually) or\n [using build triggers](/build/docs/automating-builds/create-manage-triggers).\n\n Once your build completes, you can [view repository details](/artifact-registry/docs/repositories/list-repos)\n in Artifact Registry.\n\n You can also [view build provenance metadata](/build/docs/securing-builds/generate-validate-build-provenance#view) and [validate provenance](/build/docs/securing-builds/generate-validate-build-provenance#validate_provenance).\n\nRunning tests on multiple `node` versions\n-----------------------------------------\n\nSometimes it is necessary to ensure that your project works across multiple\nversions of `node`. You can create and configure\n[Cloud Build triggers](/build/docs/running-builds/create-manage-triggers)\nsuch that:\n\n- In your build config file, specify the `node` version as a [substitution variable](/build/docs/configuring-builds/substitute-variable-values).\n- Create one trigger for each version of `node` against which you want to build your application.\n- In each of the trigger settings, use the substitution variable value field to indicate the version of the `node` for that trigger.\n\nThe following steps explain how to specify the `node` version using trigger-specific\nsubstitution variables:\n\n1. In your repository root, add a build config file, which specifies the\n `node`version as a substitution variable. In the following example build\n config file, `$_NODE_VERSION` is a [user-defined substitution variable](/build/docs/configuring-builds/substitute-variable-values#using_user-defined_substitutions):\n\n steps:\n - name: 'node:$_NODE_VERSION'\n entrypoint: 'npm'\n args: ['install']\n - name: 'node:$_NODE_VERSION'\n entrypoint: 'npm'\n args: ['test']\n\n2. For each version of `node` you want to build against, create a build trigger\n using the following steps:\n\n 1. Open the **Triggers** page in the Google Cloud console:\n\n [Open Triggers page](https://console.cloud.google.com/cloud-build/triggers)\n 2. Select your project from the project selector drop-down menu at the top of\n the page.\n\n 3. Click **Open**.\n\n 4. Click **Create trigger**.\n\n On the **Create trigger** page, enter the following settings:\n 1. Enter a name for your trigger.\n\n 2. Select the repository event to start your trigger.\n\n 3. Select the repository that contains your source code and build\n config file.\n\n 4. Specify the regex for the branch or tag name that will start your\n trigger.\n\n 5. **Configuration**: Choose the build config file you created\n previously.\n\n 6. Under **Substitution variables** , click **Add variable**.\n\n 1. Under **Variable** , specify the `node` version variable you used in your build config file, and under **Value** specify the version of the `node`. For example, `_NODE_VERSION` and `12`.\n 5. Click **Create** to save your build trigger.\n\nYou can use these triggers to build your code on the version of `node` you\nspecified in the trigger.\n\nWhat's next\n-----------\n\n- Learn how to [view build results](/build/docs/view-build-results).\n- Learn how to [safeguard builds](/software-supply-chain-security/docs/safeguard-builds).\n- Learn how to [build container images](/build/docs/building/build-containers).\n- Learn how to [build Go applications](/build/docs/building/build-go).\n- Learn how to [perform blue/green deployments on Compute Engine](/build/docs/deploying-builds/deploy-compute-engine).\n- Learn how to [troubleshoot build errors](/build/docs/troubleshooting)."]]
