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.
- Set up Artifactory as a Docker registry. For more information, see Getting Started with Artifactory as a Docker Registry and Docker Registry.
- Installed and configured JFrog Distribution.
- Generated, uploaded, and deployed GPG Keys for JFrog Distribution.
- At least one Pipelines node pool. This is the set of nodes that all pipeline steps will execute in. For more information, see Managing Pipelines Node Pools.
- Successfully run the Docker Build and Push pipeline.
Running This Example
Perform the steps below to run this pipeline:
Sign in
Sign in to JFrog Platform with your Artifactory credentials.Add integrations
Go to Application | Pipelines | Integrations to add these integrations:
- GitHub Integration: This integration is used to add the Pipeline source.
myGithub
is the name of the GitHub integration used in this example. - Distribution Integration: This integration connects your JFrog Pipeline Automation platform to a Distribution instance.
myDist
is the name of the Distribution integration used in this example. - Artifactory Integration: This integration is used to authenticate with Artifactory to to get artifacts including Docker images, and maintain build information.
myArtifactory
is the name of Artifactory integration used in this example.
- GitHub Integration: This integration is used to add the Pipeline source.
- Write down the names of the Artifactory and Distribution integrations as these are required for the next step. Ensure that the names are unique and easy to remember.
Fork GitHub repository
The Pipelines DSL for this example is available in the jfrog-pipelines-cd-sample repository in the JFrog GitHub account.
The DSL file is a yaml file that contains the pipeline definitions. The example uses two YAML files,
pipelines.yml
andvalues.yml
. The pipelines.yml file contains the declarations for all resources and workflow steps. Thevalues.yml
file contains the values required for thepipelines.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, which is required to add webhooks to these repositories and listen for change events.
Update values.yml
The pipelines configuration is available in the values.yml file. If required, edit this file in your fork of this repo and replace the following:
Tag Description Example gitProvider
Provide the name of the Github integration you added in the previous step. gitProvider: myGithub
sourceArtifactory
Provide your Artifactory integration. sourceArtifactory: myArtifactory
sourceDistribution
Provide your Distribution integration. sourceDistribution:
myDist
All pipeline names are global across your JFrog Pipelines. The names of your pipelines and resources need to be unique within JFrog Pipelines.
Add Pipeline Source
The Pipeline Source represents the Git repo where our Pipelines definition files are stored. A pipeline source connects to the repository through an integration, which was added in the previous step.
Add a Pipeline Source. Enter
.yml
in the Pipeline Config File Filter field. This automatically adds your configuration to the platform and a pipeline is created based on your YAML.
After your Pipeline Source syncs successfully, navigate to Pipelines | My Pipelines in the left navbar to see the newly added pipeline. In this example,
cd_
demo_release_mgmt
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.
Execute the pipeline
You can now commit to the repo to trigger your pipeline, or trigger it manually 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.
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:
BuildInfo
A BuildInfo
resource is the metadata associated with a build in Artifactory.
JFrog Pipelines automatically creates BuildInfo when any of the Build steps like MvnBuild, NpmBuild, GradleBuild, or DockerBuild are used to generate packages. BuildInfo is published to Artifactory through the PublishBuildInfo step, by setting a flag in Build steps or by providing that resource in steps like NpmPublish, GoPublishModule, GoPublishBinary, and DockerPush.
# Build info of build to bundle - name: gosvc_promoted_build_info type: BuildInfo configuration: sourceArtifactory: {{ .Values.artifactoryIntegration }} buildName: dbp_build buildNumber: 1
Tag | Description | Required/Optional |
---|---|---|
name |
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 | | Required |
buildName |
| Optional |
buildNumber | The number of the build to associate with the BuildInfo. | Optional |
ReleaseBundle
A ReleaseBundle
resource specifies a set of artifacts in Artifactory that are distributed to Artifactory Edge nodes as a JFrog Distribution Release Bundle.
This resource can be used with CreateReleaseBundle or DistributeReleaseBundle. This resource can be used to represent both signed and unsigned Release Bundle.
- name: release_bundle type: ReleaseBundle configuration: sourceDistribution: {{ .Values.distributionIntegration }} name: demo_rb version: v1.0.0 - name: signed_bundle type: ReleaseBundle configuration: sourceDistribution: {{ .Values.distributionIntegration }} name: demo_rb version: v1.0.0
Tag | Description | Required/Optional |
---|---|---|
name | release_bundle and signed_bundle are ReleaseBundle resources. While release_bundle is the release bundle, signed_bundle is the signed version of the release bundle. | Required |
sourceDistribution | myDist is the name of the Distribution Integration. | Required |
version | Version number of the release bundle. | Required |
DistributionRule
A DistributionRule resource is the set of Destination rules that can be applied to distributing a release bundle using JFrog Distribution.
- name: distribution_rules type: DistributionRule configuration: sourceDistribution: {{ .Values.distributionIntegration }} serviceName: "*" siteName: "*" cityName: "*" countryCodes: - "*"
Tag | Description | Required/Optional |
---|---|---|
name | distribution_rules is the name of the DistributionRule resource. | Required |
sourceDistribution | myDist is the name of the Distribution Integration. | Required |
serviceName | The Artifactory Edge Node service name with a wildcard pattern. | Required |
siteName | The Artifactory Edge Node site name with a wildcard pattern. | Required |
cityName | The Artifactory Edge Node city name with a wildcard pattern. | Required |
countryCodes | The Artifactory Edge Node country codes with a wildcard pattern. | Required |
Pipelines
cd_demo_release_mgmt
, the pipeline definition for signing a release bundle and releasing it to an Artifactory edge node.
Steps
The cd_demo_release_mgmt
pipeline is made up of the following native steps:
CreateReleaseBundle
The CreateReleaseBundle native step produces a Release Bundle for distribution to an Artifactory Edge Node . The step can be used to create a signed or unsigned release bundle.
- name: bundle type: CreateReleaseBundle configuration: releaseBundleName: demo_rb releaseBundleVersion: v1.0.${run_number} dryRun: false sign: false description: "some random test description" inputResources: - name: gosvc_promoted_build_info trigger: false outputResources: - name: release_bundle releaseNotes: syntax: markdown content: | ## Heading * Bullet * Points
Tag | Description of usage | Required/Optional |
---|---|---|
name | bundle is the name that identifies the CreateReleaseBundle step. | Required |
inputResources | Must specify either a named BuildInfo resource(s) or an Aql resource. If BuildInfo | Required |
outputResources | Must specify a ReleaseBundle resource. The | Required |
releaseBundleName | An alphanumeric name for the release bundle. demo_rb is the name used in this example. | Required |
releaseBundleVersion | Version string for the release bundle | Required |
dryRun | When set to Default is true. | Optional |
sign | Specifies whether the release bundle version is signed. Default is false. | Optional |
storeAtSourceArtifactory | Controls whether to store release bundle version in the source Artifactory while signing. | Optional |
description | Description of the release bundle. | Optional |
releaseNotes | Describes the release notes for the release bundle version. | Optional |
SignReleaseBundle
The SignReleaseBundle native step signs a Release Bundle in preparation for distributing it to Edge nodes.
- name: sign type: SignReleaseBundle configuration: inputResources: - name: release_bundle outputResources: - name: signed_bundle
Tag | Description of usage | Required/Optional |
---|---|---|
name | sign is the name that identifies the SignReleaseBundle step. | Required |
inputResources | Must specify a ReleaseBundle resource whose This step accepts | Required |
outputResources | Must specify a ReleaseBundle resource. This ReleaseBundle is updated with the This step specifies | Required |
DistributeReleaseBundle
The DistributeReleaseBundle native step triggers the distribution of a Release Bundles to an Artifactory Edge Node. This step requires a signed release bundle and one or more distribution rules to successfully execute.
- name: distribute type: DistributeReleaseBundle configuration: dryRun: false inputResources: - name: signed_bundle - name: distribution_rules
Tag | Description of usage | Required/Optional |
---|---|---|
name | distribute is the name that identifies the DistributeReleaseBundle step. | Required |
inputResources | Must specify a ReleaseBundle resource (signed_bundle) and one DistributionRule resource (distribution_rules) . | Required |
dryRun | Controls whether this should be a dry run to test if the release bundle can distribute to the Edge nodes matching the distribution rule. The default is true. | Optional |