GitRepo

JFrog Pipelines Documentation

ft:sourceType
Paligo

A GitRepo 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.

The first version of the resource, used if it is an input to a step that runs before any webhooks are received, will be for the latest commit in the default branch on the source provider at the time the resource is created. Later resource versions can be restricted by the branches, tags, and buildOn options.

Note

To suppress triggering for an individual commit, include the text skipRun in the commit message.

By default theGitReporesource uses ssh protocol with the created deploy key to fetch the source repository content. However, this only provides Pipelines with read-only access to the source repository. Optionally, users can configure a GitRepo resource to use https protocol. In this case Pipelines will have privileges to the source repository according to the credentials used to set up the Git provider integration.

YAML Schema
resources:
  - name:               <string>
    type:               GitRepo
    configuration:
      gitProvider:      <git integration name>
      path:             <string>
      files:
        include:        <regular expression>
        exclude:        <regular expression>
      branches:
        include:        <regular expression>
        exclude:        <regular expression>
      recurseSubmodules:    <Boolean>  
      pullRequestSourceBranches:
        include: <regular expression>
        exclude: <regular expression>
      pullRequestTargetBranches:
        include: <regular expression>
        exclude: <regular expression>
      tags:
        include:        <regular expression>
        exclude:        <regular expression>
      buildOn:
         branchCreate:      <Boolean>
         branchDelete:      <Boolean>
         commit:            <Boolean>
         pullRequestCreate: <Boolean>
         pullRequestClose:      <Boolean>
         releaseCreate:         <Boolean>
         tagCreate:                     <Boolean>
      cancelPendingRunsOn:
         newCommit:         <Boolean>
         pullRequestUpdate: <Boolean>
      shallowDepth:     <Positive Integer>        # used to set the depth at which the repo is (shallow)cloned/fetched
      cloneProtocol:    <ssh|https>               # Optional. Defaults to ssh
      pin:
        versionId:  <number>
        sha:        <string> 
Tags
name

An alphanumeric string (underscores are permitted) that identifies the resource.

type

Must be GitRepo for this resource type.

configuration

Specifies all configuration selections for the resource.

Tag

Description

Required/Optional

gitProvider

The name of the source control integration. Currently supported integration types are:

Required

path

The path of the repository from the integration root.

The path can be hard coded or you can use {{.jfrog-pipelines.sourceRepository}} variable to reference the current pipeline source path.

Example

  - name: myFirstRepo
    type: GitRepo
    configuration:
      gitProvider: myGitHub
      path: {{.jfrog-pipelines.sourceRepository}}

Required

files

  • include -- (optional) Regular expression to include files meeting the pattern from the repo

  • exclude-- (optional) Regular expression to exclude files meeting the pattern from the repo

Note

  • If this tag is not specified, all files are matched by default.

  • This filter only applies to commit events, and not pull requests, tags, or releases.

Optional

branches

  • include -- (optional) Regular expression to include branches from the repo

  • exclude-- (optional) Regular expression to exclude branches from the repo

Supported regex

The branches tag supports the following regex:

^ $ . * & ? @ = ; : +

Examples:

^gitBranch$ (to trigger for that branch)

example.*

example+.&

example+:&@=.*$

^._example+:&.@=+;?.*$

example+.:&@=*;?1661337986460$

Note

If the tag is not specified, the default branch will be triggered.

Optional

recurseSubmodules

Set as true to clone all submodules in the repository. Default value is false.

Optional

pullRequestSourceBranches

  • include -- (optional) Regular expression to include pull requests from branches matching the pattern

  • exclude -- (optional) Regular expression to exclude pull requests from branches matching the pattern

Note

If this tag is not specified, all branches are matched by default.

Optional

pullRequestTargetBranches

  • include -- (optional) Regular expression to include pull requests to branches matching the pattern

  • exclude-- (optional) Regular expression to exclude pull requests to branches matching the pattern

Note

If this tag is not specified, the branches tag setting will apply to the target branch. If neither is specified, all branches are matched by default.

Optional

tags

Used to specify a collection of tags and releases upon which a new version is created

  • include -- (optional) Regular expression to include tags meeting the pattern from the repo

  • exclude-- (optional) Regular expression to exclude tags meeting the pattern from the repo

Note

If this tag is not specified, all tags are matched by default.

Optional

buildOn

Used to control whether the resource will be updated on specified events

  • branchCreate -- (default is false) used to control whether the resource will be updated when a branch is created. Note that when this is set as false, the resource is not updated and the resource version is not created.

  • branchDelete -- (default is false) used to control whether the resource will be updated when a branch is deleted. Note that when this is set as false, the resource is not updated and the resource version is not created.

  • commit-- (default is true) used to control whether the resource will be updated for commit webhooks. Note that when this is set as false, the resource is not updated and the resource version is not created.

  • pullRequestCreate -- (default is false) used to control whether the resource will be updated for pull request webhooks

  • pullRequestClose -- (default is false) used to control whether the resource will be updated for closing a pull request webhook

  • releaseCreate -- (default is false) used to control whether the resource will be updated for release webhooks

  • tagCreate -- (default is false) used to control whether the resource will be updated for tag webhooks

    Note

    In a multi-branch pipeline, when tagCreate is set as true and when you perform a commit or Git release with a specific tag, buildOn.commit will trigger only those branches that have the associated Git tag.

    This is applicable for GitHub only.

Note

If this tag is not specified, commit: true is the default setting.

For more information about using this tag, see Triggering On a Git Repository Change.

Optional

cancelPendingRunsOn

Used to control whether previously triggered runs are canceled for new webhooks

  • newCommit-- (default is false) Cancels previous processing or waiting runs for the same branch for commits, same tag name for tags, and same release name for releases.

  • pullRequestUpdate -- (default is false) Cancels previous processing or waiting runs for the same pull request number when a webhook is received for a pull request.

Note

All values for this tag are false by default.

For more information about using this tag, see Cancelling Previous Runs On a Git Repository Change.

Optional

shallowDepth

Uses a positive integer to set the depth at which the repo is (shallow) cloned/fetched

Note

If shallowDepth is not specified, no shallow clone options are passed to git. The full repo is cloned in its entirety.

Optional

cloneProtocol

Used to select the protocol to be used when cloning the repo. Supported values are ssh or https. Defaults to ssh.

Optional

pin

This configuration can be used to pin the resource to a specific version. The pinned resource version will be used by the steps that reference this resource as an input and newer versions will be ignored.

Users have two configuration options when selecting the GitRepo resource version to be pinned:

  • versionId -- Resource version Id (can be obtained through the UI)

Or

  • sha -- The commit sha to be pinned

Steps that use the resource as an output can still produce new versions. New versions will be visible for steps using the resource as an input as long as they are part of the same run of the step that created the version.

When creating a new run, manual custom trigger can still be used to override the pinned version to a different one.

Optional

Using include and exclude Patterns

When both include and exclude patterns are used, the following rules apply on the list of all the files in the commit change list :

  • All files that do not match the include pattern are removed

  • All files that do match the exclude pattern are removed

  • If any files are left, the resource is updated

Environment Variables

Whenever GitRepo is used in a step, a set of environment variables is automatically made available that you can use in your step.

Environment Variable

Description

res_<resource_name>_path

Relative path of the resource

res_<resource_name>_branchName

Name of branch on which the commit occurred. If it was created for a pull request, this is the base branch.

This environment variable is useful for getting the name of the branch.

res_<resource_name>_commitMessage

Commit message of the version being used

res_<resource_name>_commitSha

SHA of the commit of the version being used

res_<resource_name>_commitUrl

URL to the commit

res_<resource_name>_committerLogin

Name of the committer for the SHA being used

res_<resource_name>_gitProvider_name

Git integration name

res_<resource_name>_gitProvider_url

URL of the Git Provider integration

res_<resource_name>_gitRepoFullName

Name of the Git repo

res_<resource_name>_gitRepoRepositoryHttpsUrl

HTTPS URL for the Git repository

res_<resource_name>_gitRepoRepositorySshUrl

SSH URL for the Git repository.

res_<resource_name>_gitRepoRepositoryUrl

URL for the Git repository

res_<resource_name>_gitRepoSourceDefaultBranch

Default branch of the Git repository

res_<resource_name>_gitTagName

If a tag name was present in the current version, this will be the tag name

res_<resource_name>_integrationName

The name string of the integration used by the GitRepo

res_<resource_name>_isGitTag

True if the version is a git tag based build

res_<resource_name>_isPrerelease

True if the version is a git release based build. Supported only if the integration is GitHub

res_<resource_name>_isPullRequest

True if the version is a git open pull request based build

res_<resource_name>_isPullRequestClose

True, if the version is a git closed pull request based step. Supported only if the integration is GitHub or Bitbucket or Gitlab.

res_<resource_name>_isRelease

True if the version is a git release based build. Supported only if the integration is GitHub

res_<resource_name>_pullRequestNumber

The ID number of the pull request

res_<resource_name>_pullRequestBaseBranch

Name of the base branch into which the pull request changes will be merged

res_<resource_name>_pullRequestSourceUrl

Source URL of the pull request

res_<resource_name>_pullRequestSourceHttpsUrl

Source HTTPS URL of the pull request

res_<resource_name>_pullRequestSourceSshUrl

Source SSH URL of the pull request

res_<resource_name>_resourcePath

Full path of the resource folder on the node

res_<resource_name>_operation

Input or output resource

res_<resource_name>_shaData

JSON object containing the details of the SHA

res_<resource_name>_beforeCommitSha

SHA before the commit was made

res_<resource_name>_baseCommitRef

The commit SHA of base branch in a PR

res_<resource_name>_headCommitRef

The source branch name in a PR

res_<resource_name>_compareUrl

Compare URL for the commit

res_<resource_name>_gitTagMessage

If a git tag is created, this holds the message if it is present

res_<resource_name>_releaseName

If a release is created, this holds the name of the release

res_<resource_name>_releaseBody

If a release is created, this holds the description of the release

res_<resource_name>_releasedAt

If a release is created, this holds the date of the release

res_<resource_name>_lastAuthorLogin

Details of when the last author logged in

res_<resource_name>_lastAuthorEmail

Email of the author

res_<resource_name>_isBranchCreate

True if a branch was created

res_<resource_name>_isBranchDelete

True if a branch was deleted

Examples

Example 1

GitRepo resource listening to the master branch

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      branches:
        include: master

Example 2

GitRepo resource listening to all branches except master and release

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      branches:
        exclude: ^(master|release)$

Example 3

The following example may be useful to reference a single directory in a source repository that contains source code for a single microservice within a larger project.

GitRepo resource listening only to certain files in a directory

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      branches:
        include: master
      files:
        include: ^folder1\/package\/docker\/micro1\/.+

Example 4

By default, a GitRepo triggers on a commit, but this can be changed in the buildOn attributes. For more information about triggering, see Triggering Pipelines and Steps.

GitRepo triggers only for a pull request and not for commit

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      branches:
        include: master
      buildOn:
        commit: false
        pullRequestCreate: true

Example 5

The following example pipeline triggers the first step on the GitRepo resource. The step uses the environment variables exposed by the GitRepo resource to navigate to the path where the Git repository is cloned on the build node, and to execute a script in that directory.

Usage in a Pipeline

pipelines:
  - name: java_pipeline
    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_app_repo
        execution:
          onExecute:
            - pushd $res_my_app_repo_resourcePath
            - ./execute.sh
            - popd

Example 6

GitRepo resource using HTTPS protocol during repo clone

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      branches:
        include: master
      cloneProtocol: https

Example 7

In this example, the GitRepo is only updated for pull requests to master.

GitRepo triggers only for a pull requests to master

resources:
  - name: my_app_repo
    type: GitRepo
    configuration:
      gitProvider: my_github
      path: myuser/repo-name
      pullRequestTargetBranches:
        include: ^master$
      buildOn:
        commit: false
        pullRequestCreate: true