System Templates

Add System Template (1.31.0 and higher)

This section provides information about the steps required for creating and publishing system templates.

Step 1: Create System Template Files

1. In your SCM repository, create a new directory. For example: templates.

2. In the directory, create three new files:

   • templatesDefinition.yml: This should contain the pipeline definition and should be a validymlfile. For more information, see the exampletemplatesDefinition.ymlfile.

   • values.yml.example: This should be a valid yml file and it is used to specify the details required for thetemplateDefinition.ymlfile. For more information, see the examplevalues.ymlfile.

   • readme.md(optional): This is optional and the information in thereadme.mdfile will be available as Documentation for the template.

Step 2: Use System Template to Create a Pipeline Source

After creating the relevant files for your template, use the pre-loadedPublishTemplatetemplate to publish and use your system templates:

1. In the Pipelines UI:
   • Add an integration for one of the following Git providers:
     • Bitbucket Integration
     • Bitbucket Server Integration
     • GitHub Enterprise Integration
     • GitHub Integration
     • GitLab Integration
   • Add anArtifactory Integration

2. In your SCM repository, create a new directory named.jfrog-pipelines.

3. In the directory, create two new files:

   • pipelines.yml

   • values.yml

4. Add the following in thepipelines.ymlfile:

   valuesFilePath: ./values.yml Include: template: jfrog/PublishTemplate/1.0.0

   Where:

   • jfrogis the predefined namespace to be used for thePublishTemplatetemplate. This is mandatory and cannot be changed.
   • PublishTemplateis the predefined name of the pre-loaded template that is used for publishing other templates. This is mandatory and cannot be changed.
   • 1.0.0is the version of thePublishTemplatetemplate. This is mandatory and cannot be changed.

5. Update thevalues.ymlwith the following values:

   templateRepository: gitProvider:  path:  branch:  templateFolder:  publishTemplate: namespace:  name: myPipelineTemplate  version: 1.0.0  pipelineName:  artifactoryIntegration: 

   Example

   templateRepository: gitProvider: myGithub path: john/templates branch: main templateFolder: templates/my_name_space/myPipelineTemplate publishTemplate: namespace: newTemplates name: myPipelineTemplate version: 1.0.0 pipelineName: PublishTemplate artifactoryIntegration: myArtifactory

   Where:

   • templateRepositoryprovides information about where the template is stored.
   • gitProvideris the name of the Git integration you created in the first step.
   • pathis the Git repository path.
   • branchis the name of the branch where the template is available.
   • templateFolderis the relative path from the root where the template files are located.
   • publishTemplateprovides requisite metadata for publishing the template.
   • namespaceis the namespace used for storing the template in Artifactory.
   • nameis the name used for storing the template in Artifactory.
   • versionis the version of the template.
   • pipelineNameis the default name of the pipeline that is used for publishing the template to Artifactory. While PublishTemplate is the default name, this can be used to provide an alternative name for the pipeline. It is recommended that you change the default name as there could be a pipeline name conflict if you are using the same template multiple times.
   • artifactoryIntegration你cre Artifactory集成的名称ated in the first step.
6. In the JFrog Platform, go toAdministration → Pipelines → Pipeline Sourcesand add the PublishTemplate pipeline as a pipeline source.
   After your Pipeline Source syncs successfully, you can view the newly added pipeline by navigating toMy Pipelineson the left navbar and clickingPipelines→My Pipelines.
7. Go toApplication → Pipelines → My Pipelines → All Pipelinesand run the pipeline.

Structure of Template Source Repository (1.30.0 and lower)

The system template files should be stored in the template source repository in a specific order for them to be uploaded to Pipelines:

• There must be a directory calledtemplatesin the root directory of the repository.
• In thetemplatesdirectory, there must be a subdirectory path of the form:namespace/<name>/.

Where:

• namespaceis the name the template belongs to.
• nameis the name of the template.

• filesare the template-related files.
  

  The namespace and subdirectories can only contain letters, underscores, and numbers.

  
  

• The following files can be added as part of the templates:

  File	Description	Mandatory/Optional
  templateDefinition.yml	This should contain the pipeline definition and should be a validymlfile.	Mandatory
  values.yml.example	Use this file as a sample for creating a values.yml file. This should be a valid yml file and it is used to specify the details required for templateDefinition.yml file.	Optional
  readme.md	This should contain the documentation for the template.	Optional

  Using {{gitBranch}}

  • BothtemplateDefintion.ymlandvalues.ymlsupport the in-built keyword{{gitBranch}}. The value of{{gitBranch}}is substituted with the branch against which the pipeline source was created. For more information, seeCreating Multibranch Pipelines.
  • When used in a conditional or comparison logic,{{gitBranch}}placeholders must be wrapped within double quotes.
    Example:{{ if eq "{{gitBranch}}" "master" }}

templateDefinition.yml: This is a sample templateDefinition.yml. This can be edited to create your own version of the file.

pipelines: - name: basic steps: - name: basic1 type: Bash configuration: runtime: type: image execution: onExecute: - printenv {{ .Values.foo.bar }} - name: basic2 type: Bash configuration: runtime: type: image inputSteps: - name: basic1 execution: onExecute: - printenv {{ .Values.foo.baz }} - name: basic3 type: Bash configuration: runtime: type: image inputSteps: - name: basic2 execution: onExecute: - printenv {{ .Values.foo.zoo }}

values.yml.example: Use this file as a sample to create thevalues.ymlfile.

artifactoryIntegration: myArtifactoryIntegration GitRepo: name: myGitRepo gitProvider: myGitIntegration path: myorg/myrepo branches: include: master foo: name: bar Image: name: myDockerImage sourceRepository: mySourceRepo Pipeline: name: myDockerPipeline DockerBuild: name: myDockerBuild dockerFileName: Dockerfile dockerImageName:  DockerPush: targetRepository: docker-local Bash: name: myBashStep

Template Functions List

The pipelinetemplateDefinition.ymlsupports these helm chart style functions:

• String Functions:trim,wrap,randAlpha,plural, and others.

  • String List Functions:splitList,sortAlpha, and others.

  Default Value for String Functions

  If you are using a string function (such astruncorabbrev) that expects a value, then ensure that the template gives it a default value.
  Example:.Values.app | default "" | trunc 6

• Integer Math Functions:add,max,mul, and others.
  • Integer Slice Functions:until,untilStep
• Float Math Functions:addf,maxf,mulf, and others.
• Date Functions:now,date, and others.
• Defaults Functions:default,empty,coalesce,fromJson,toJson,toPrettyJson,toRawJson,ternary
• Encoding Functions:b64enc,b64dec, and others.
• Lists and List Functions:list,first,uniq, and others.
• Dictionaries and Dict Functions:get,set,dict,hasKey,pluck,dig,deepCopy, and others.
• Type Conversion Functions:atoi,int64,toString, and others.
• Path and Filepath Functions:base,dir,ext,clean,isAbs,osBase,osDir,osExt,osClean,osIsAbs
• Flow Control Functions:fail
• Advanced Functions:
  • UUID Functions:uuidv4
  • Version Comparison Functions:semver,semverCompare
  • Reflection:typeOf,kindIs,typeIsLike, and others.
  • Cryptographic and Security Functions:derivePassword,sha256sum,genPrivateKey, and others.
  • Network:getHostByName

For more information about these functions, seeSprig Function DocumentationandTemplate Functions.

Adding System Templates (1.30.0 and lower)

Perform the following steps to add system templates:

1. Ensure thattemplateDefinition.ymlandvalues.ymlfiles are available in the appropriate repository.
2. Add an admin project integration:
   System templates are uploaded to pipelines through an SCM repository. To add the repository, add a SCM admin integration fromAdministration | Pipelines | Integrations. For more information, seeAdministering Integrations.
3. Add a template source:
   Go toPipelines | Extensions & Templatesand click theSourcestab. ClickAdd SourceandTemplatesto add the template source repository.
   
   

4. 选择admin集成、存储库添加name, and branch and clickCreate Sourceto create the template source.
   

   The admin integration should have admin access to the template source repository.

   

Pipelines adds all the templates from the template source and performs a sync,and the newly added or updated templates are available in Pipelines as the latest version. If there is an error during the sync, it fails.

Managing Templates

The templates from the newly uploaded template source is now available for creating pipelines. For information about managing, retiring, and git-tagging and releasing templates, seeManaging Pipelines Templates.

Using System Templates to Create a Pipeline Source

Perform the following steps to use a system template to create a pipeline source:

1. Go toAdministration | Pipelines | Pipeline Sources, and clickAdd Pipeline Source, andFrom Template.
   
   

2. Complete the resultingTemplate Propertiesform:
   
   
   
   
   • Click theSelect Template Namespacefield and select the namespace where the required system template is defined.
   • Click theSelect Template Namefield and select the relevant system template.

   • Click theSelect Template Versionfield and select the relevant version for the template.
     
     

3. ClickNextand complete the resultingSpecify values fileform to add thevalue.ymlfile.
   
   In theValues File Pathfield, provide the path to the values.yml file, which contains the values for the system template. By default, the field is set to take the file from the root directory.
   
   

   For more information about theSpecify values fileform, see the sectionAdding a Pipeline SourceinAdministering Pipeline Sources.

   
   
   
   

4. ClickCreate Sourceto complete adding the Pipeline Source.

The combination of pipeline template name, namespace, version andvalues.ymlis parsed to create the pipeline definition.

After your Pipeline Source syncs successfully, you can view the newly added pipeline by navigating to the My Pipelines on the left navbar and clicking onPipelines→My Pipelines.