Create Git plugin procedures

Plugin procedures can be used in procedure steps, process steps, and pipeline tasks, allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline.

Depending on your plugin configuration and how you run procedures, the Input parameters Configuration name field may behave differently in the CloudBees CD/RO UI. For more information, refer to Differences in plugin UI behavior.

Clone

Clones a remote repository into a path on the local filesystem.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Destination directory

Indicates the path where the source tree is created. It can be relative to the job’s workspace.

Git repository

Required. A Git repository URL. For example, http://git://server/repo.git.

Clone mirror?

Creates a mirror of the source repository. It allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.

This parameter is only supported with the Git CLI.

Path of the reference repo to use during clone

Specify a folder containing a repository that is used by Git as a reference during clone operations. This option is ignored if the folder is not available on the agent.

This parameter is only supported with the Git CLI.

Remote branch

The name of the Git branch to use. For example, experimental.

Tag

Provide the name of a specific Git tag to check out after the clone command.

Commit hash

The commit hash to update the index.

This creates a checkout with a detached HEAD.

Clone submodules?

After the clone is created, initialize and clone submodules based on the provided Submodules pathspecs. If no Submodules pathspecs are specified, all submodules are initialized and cloned.

Submodules pathspecs

The list of the submodules' pathspecs delimited by newlines.

This parameter is only supported with the Git CLI.

Shallow submodules

All submodules that are cloned are shallow, with a depth of one.

This parameter is only supported with the Git CLI.

Overwrite?

This option deletes the existing, previously cloned, folder with the repository and runs the clone anew.

Depth

Create a shallow clone with a history that is truncated to the specified number of revisions.

This parameter is only supported with the Git CLI.

Remove .git directory?

This option removes the .git directory after the Clone operation has been performed.

Result property sheet

The results are saved into this property or property sheet.

Output parameters

Table 2. Clone output parameters
Parameter	Description
cloneId	The SHA ID of the top cloned commit.
cloneBranches	Branches of the top cloned commit in JSON format.
cloneData	A JSON representation of the cloned data. For example, a commit, commit message, etc.

Commit

Performs a Git commit and optionally pushes changes to the remote repository.

Input parameters

Table 3. Commit input parameters
Parameter	Description
Configuration name	Required. The previously defined configuration for the plugin.
Folder	Required. The folder where files are retrieved from. The folder must be under a Git tree. This means that a .git folder must be present in this folder or in any of its parent folders.
Files	Required. The file pattern (or glob pattern) to use to add files to the commit. One pattern per line. For example, `README\*`.
Commit message	Required. The commit message for the newly created commit. If not provided, the date and CloudBees CD/RO Job ID are used to identify the commit.
Author name	The commit author name. For example, John Wick.
Author email	The email address of the commit author. For example, `sample@gmail.com`.
Committer name	The name of the committer. This can be the name of the project or a schedule. For example, `$[/myProject/name]`.
Committer email	The email address of the committer. For example, `build-user@company.com`.
Remove missing?	If selected, any files that are missing from the repository are removed from the SCM.
Push?	If selected, the commit is pushed to the remote repository.
Remote	If Push? is selected, provide the remote name here. The default is `origin`.
New branch	If Push? is selected, provide a name of a new branch.
Fail on empty commit?	If selected, the procedure fails if there are no changes to commit.
Result property sheet	The results are saved into this property or property sheet.

Output parameters

Table 4. Commit output parameters
Parameter	Description
commitId	SHA ID of the created commit.
commitData	A JSON representation of the cloned data. For example, a commit, commit message, etc..

DeleteBranch

Deletes the existing Git branch.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Folder

The folder where files are retrieved from the remote repository. The folder must be under a Git tree and a .git folder must be present in this folder or parent folders.

Branch to delete

Required. Provide a name of a branch to delete.

Branch to switch

Provide a branch name to switch to, before deleting the branch specified in the Branch to delete parameter.

For the JGit library, if the branch is specified, it should already exist locally.

Remote

Provide the remote name here. The default is origin.

Pull

Fetch changes from the remote repository into the local repository. If the local repository does not exist, it is cloned on the first run.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Git repository

Required. A Git repository URL. For example, http://git://server/repo.git.

Destination directory

The path where the source tree is created. It can be relative to the job’s workspace.

Remote branch

The name of the Git branch to use. For example, experimental. The default is master.

Fetch submodules?

Specifies if new commits of populated submodules should be fetched and if the working trees of active submodules should be updated.

Yes: Unconditionally recurse into all populated submodules. This is the default when this option is selected and no value is specified.
No: It can be used as a boolean option to completely disable recursion.
On demand: Recurse into a populated submodule if the superproject retrieves a commit that updates the submodule’s reference to a commit that is not already present in the local submodule clone.

For JGit, there is no difference between Yes and On demand.

Depth

Limit fetching to the specified number of commits from the tip of each remote branch history.

This parameter only works if the repository has not been previously cloned.
This parameter is only supported with the Git CLI.

Clean the workspace

Cleans the workspace before or after every checkout by deleting all untracked files and directories, including those specified in .gitignore. It also:

Resets all tracked files to their versioned state.
Ensures the workspace is in the same state as if clone and checkout were performed in a new workspace.
Reduces the risk that the current build will be affected by files that were generated by prior builds.
Does not remove files outside the workspace, such as temporary files or cache files.
Does not remove files in the .git repository of the workspace.

Files to clean

The type of files to clean; Untracked only or Changed and untracked.

Metadata property path

The property sheet where the last commit is stored for the Git log report.

If omitted, generate a report for the last commit.
If present, generate a report from the specified commit to the last commit. For example, /myProject/RepoName_branch/lastCommit.

Remove .git directory?

This option removes the .git directory after the Pull operation has been performed.

Result property sheet

The results are saved into this property or property sheet.

Output parameters

Table 7. Pull output parameters
Parameter	Description
pullId	SHA ID of the last pulled commit.
pullBranches	Branches of the top cloned commit in JSON format.
pullData	JSON representation of the cloned data. For example, a commit, commit message, etc.