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 theGitRepo
resource 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 |
---|---|---|
| The name of the source control integration. Currently supported integration types are: | Required |
| The path of the repository from the integration root. The path can be hard coded or you can use Example - name: myFirstRepo type: GitRepo configuration: gitProvider: myGitHub path: {{.jfrog-pipelines.sourceRepository}} | Required |
|
Note
| Optional |
|
Supported regexThe
Examples:
NoteIf the tag is not specified, the default branch will be triggered. | Optional |
| Set as | Optional |
|
NoteIf this tag is not specified, all branches are matched by default. | Optional |
|
NoteIf this tag is not specified, the | Optional |
| Used to specify a collection of tags and releases upon which a new version is created
NoteIf this tag is not specified, all tags are matched by default. | Optional |
| Used to control whether the resource will be updated on specified events
NoteIf this tag is not specified, For more information about using this tag, see Triggering On a Git Repository Change. | Optional |
| Used to control whether previously triggered runs are canceled for new webhooks
NoteAll 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 |
| Uses a positive integer to set the depth at which the repo is (shallow) cloned/fetched NoteIf | Optional |
| Used to select the protocol to be used when cloning the repo. Supported values are | Optional |
| 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:
Or
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 |
res_<resource_name>_isGitTag |
|
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 |
|
res_<resource_name>_isPullRequestClose |
|
res_<resource_name>_isRelease |
|
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 |
|
res_<resource_name>_isBranchDelete |
|
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