Cloud customer?
 Upgrade in MyJFrog >

Search





Overview

This pipeline demonstrates the definition of a simple pipeline that builds and publishes an npm package. An example Pipelines DSL is used to show how to use integrations, resources, and steps to construct a simple, automated workflow.

This example shows the following:

Page Contents

A successful run of the pipeline in this quickstart looks like this:


Before you Begin

Before trying this quickstart, ensure that you have:

  • A GitHub account. This is required for forking the example repository.
  • A JFrog Platform account, or self-hosted JFrog Pipelines
  • Set up Artifactory as an npm Registry:
    • Set up a remote npm registryRemote Repositories defined in Artifactory serve as a caching proxy for a registry managed at a remote URL such as https://registry.npmjs.org. Artifacts (such as TGZ files) requested from a remote repository are cached on demand.
    • A local npm registry. 
    • A virtual npm registry. A Virtual Repository defined in Artifactory aggregates packages from both local and remote repositories. This allows you to access both locally hosted npm packages and remote proxied npm registries from a single URL defined for the virtual repository.
      When adding the virtual npm registry, ensure that both the remote and local npm registries are selected, and the Default Deployment Repository is set to the local npm registry.

  • At least one node pool. This is the set of nodes that all pipeline steps will execute in. For more information, see Managing Pipelines Node Pools.

Running This Example

Perform the steps below to build and push your npm image:

  1. Fork the repository

    The Pipelines DSL for this example is available in the npm-example repository in the JFrog GitHub account.

    The DSL file is a yaml file that contains the pipeline definitions. This example uses two yaml files:

    • pipelines.yml, which contains the declarations for all the resources and workflow steps required to run the pipeline.
    • values.yml, which contains the values required for the pipelines.yml file.

    For a full breakup of all the resources, pipelines and steps used in the yml file, see the pipelines.yml section below.

    Fork this repository to your account or organization. This is important since you need admin access to repositories that are used as Pipeline Sources or GitRepo resources, in order to add webhooks to these repositories and listen for change events.

  2. Sign in to Artifactory

    Sign in to JFrog Platform with your Artifactory credentials.

  3. Add Integrations

    a. Go to Administration | Pipelines | Integrations to add two integrations:

    • GitHub Integration: This integration is used to add the Pipeline source, as well as the GitRepo resource defined in values.yml
    • Artifactory Integration: This integration is used to authenticate with Artifactory to download npm depedencies from Artifactory, and to pack and upload the built package to Artifactory. 

    b. Write down the names of both GitHub and Artifactory integrations as these are required for the next step. Ensure that the names are unique and easy to remember.

  4. Update values.yml and pipelines.yml

    The pipelines configuration is available in the values.yml file. Edit this file in your fork of this repo and replace the following:

    TagDescriptionExample

    gitProvider

    Provide the name of the Github integration you added in the previous step.

    gitProvider: my_github

    path

    Provide the path to your fork of this repository.

    path: myuser/project-examples

    Edit the pipelines.yml file and replace the following:

    TagDescriptionExample

    sourceArtifactory

    Provide your Artifactory integration.

    sourceArtifactory: art

    repositoryName

    Provide the name of the npm repository in Artifactory.

    repositoryName: npm-virtual

    All pipeline names are global across your JFrog Pipelines. The names of your pipelines and resources need to be unique within JFrog Pipelines.

  5. Add Pipeline Sources

    The Pipeline Source represents the git repository where our pipelines definition files are stored. A pipeline source connects to the repository through an  integration , which we added in step 3.  

    In your left navigation bar, go to Administration | Pipelines | Pipeline Sources. Click on Add a Pipeline Source and then choose From YAML. Follow instructions to  add a Pipeline Source  This automatically adds your configuration to the platform and pipelines are created based on your YAML.  

    An example of adding a pipeline source is shown below. Please ensure that the Repository Full Name points to your forked repository and the Pipeline Config File Filter is entered correctly as (pipelines|values).yml so that both your config files are included. 
     


  6. Execute the Pipeline

    After your Pipeline Source is synced successfully, navigate to Pipelines | My Pipelines in the left navbar to see the newly added pipeline. In this example, npm_example_pipeline_jfp is the name of our pipeline. Click the name of the pipeline. This renders a real-time, interactive, diagram of the pipeline and the results of its most current run.  

    You can trigger the pipeline by committing a change to your repository, or by manually triggering it through the UI.  The steps in the pipeline execute in sequence. Multiple steps can execute in parallel if the node pool has multiple build nodes available.

    Once the pipeline has completed, a new run is listed. 





pipelines.yml

The pipelines.yml file is made up of resources, pipelines and steps, as shown below:

Resources

This example uses the following types of resources:

GitRepo

GitRepo resource is used to connect JFrog Pipelines to a source control repository. Adding it creates a webhook to the repo so that future commits will automatically create a new version with the webhook payload.

resources
  - name: npm_example_repo_jfp
    type: GitRepo
    configuration:
      # SCM integration where the repository is located
      gitProvider: {{ .Values.myRepo.gitProvider }}
      # Repository path, including org name/repo name
      path: {{ .Values.myRepo.path }}
      branches:
        # Specifies which branches will trigger dependent steps
        include: master

Tag

Description

Required/Optional
name

npm_example_repo_jfp is the name of the GitRepo resource pointing to the repository containing the yaml files and other source code required to build the image. 

This name is used to refer to the resource in steps, and must be unique across all repositories in your JFrog Pipelines environment.

Required

gitProvider 

The name of the GitHub integration. Its value is retrieved from the values.yml file.Required
path The path of the repository from the integration root. Its value is retrieved from the values.yml file.Required
branches
  • include -- (optional) Regular expression to include branches from the repo
  • exclude -- (optional) Regular expression to exclude branches from the repo 

The include: master tag indicates that the GitRepo resource is listening to the master branch.

Optional


BuildInfo

BuildInfo is automatically created when the NpmBuild step is used to generate packages. BuildInfo is then published to the configured Artifactory repo (sourceArtifactory: demoArt) by providing that resource in the NpmPublish step.

resources
  - name: npm_example_buildinfo_jfp
    type: BuildInfo
    configuration:
      sourceArtifactory: demoArt

Tag

Description

Required/Optional
name

npm_example_buildinfo_jfp is the name of the BuildInfo resource, which is the metadata associated with the build in Artifactory.

This name is used to refer to the resource in steps, and must be unique across all repositories in your JFrog Pipelines environment.

Required

sourceArtifactory

The name of the Artifactory Integration. Its value is retrieved from the values.yml file.

Required

Pipelines

npm_example_pipeline_jfp is the name of the pipeline, which contains the steps for running the pipeline.

Steps

The npm_example_pipeline_jfp pipeline contains the following native steps:

NpmBuild

The NpmBuild native step builds an npm source. This step automatically performs npm-install on the source in a Git repository. 

steps
      - name: npm_build_step
        type: NpmBuild
        configuration:
          repositoryName: npm-virtual      # required, npm repository name on artifacctory
          sourceLocation: ./npm-example      # required, location of package.json file
          integrations:
            - name:  demoArt  # required
          inputResources:
            - name: npm_example_repo_jfp         # required

Tag

Description of usage

Required/Optional

namenpm_build_step is the name that identifies the step.
This is the name used when the step is assigned as an input to the next step, npm_publish_step.
Required
repositoryNamenpm-virtual is the name of the npm repository in Artifactory.Required
sourceLocation./npm-example is the directory containing the package.json file, relative to the GitRepo path.Required
integrationsSpecifies an Artifactory Integration where modules will be published. If a FileSpec resource is specified in inputResources then this is optional. Otherwise, it is required.May be required
inputResources 

Must specify GitRepo resource. The npm-install runs on the Git repository at sourceLocation.

This step accepts npm_example_repo_jfp, which is the GitRepo resource, as the inputResource

Required

Optional


NpmPublish

The NpmPublish step publishes an npm package to the registry in Artifactory following an NpmBuild step.

steps
      - name: npm_publish_step
        type: NpmPublish
        configuration:
          # for payloadType npm:
          repositoryName: npm-virtual        # required, npm repository name on artifactory
          autoPublishBuildInfo: true       # optional
          integrations:
            - name: demoArt      # required
          inputSteps:
            - name: npm_build_step                # required
          outputResources:
            - name: npm_example_buildinfo_jfp                 # optional

Tag

Description of usage

Required/Optional

namenpm_publish_step is the name that identifies the step.Required
repositoryName

npm-virtual is the name of the npm repository to publish in Artifactory.

Required
autoPublishBuildInfo

When set to true, publishes build info to Artifactory. Default is false.

Once published, the build info can be viewed in Artifactory, in the Build Browser under Builds.

Optional
integrationsMust specify an Artifactory Integration.Required
inputSteps 

Must specify a named NpmBuild or Bash step.

npm_build_step is the name of the NpmBuild step.

Required
outputResources 

Must specify a BuildInfo resource if autoPublishBuildInfo is set to true. 

npm_example_buildinfo_jfp is specified as the outputResource

May be required
Copyright © 2021 JFrog Ltd.