Creating GitHub plugin procedures

Approve Pull Request

Approves a pull request for the specified repository.

Input parameters

Table 1. Approve Pull Request input parameters
Parameter	Description
Name	Required. The previously defined configuration for the plugin.
Repository owner	Required. The name of the user or organization that owns the repository.
Repository name	Required. The name of the GitHub repository.
Pull request identifier	Required. The pull request ID.
Body	Required if using `REQUEST_CHANGES` or `COMMENT` for the event parameter. The body text of the pull request review.
Close and merge pull request?	Select to close and merge the pull request after approving it.
Result property sheet	The results are saved into this property/property sheet as a JSON object that contains pull request data.

Output parameters

Table 2. Approve Pull Request output parameters
Parameter	Description
approvePullRequest	A JSON object that contains pull request data.

Create Pull Request

Creates a pull request for the specified repository.

Input parameters

Parameter Description

Name

Required. The previously defined configuration for the plugin.

Repository owner

Required. The name of the user or organization that owns the repository.

Repository name

Required. The name of the GitHub repository.

Base

Required. The name of the branch to pull changes to. This should be an existing branch in the current repository.

You cannot submit a pull request to one repository that requests a merge to a base of another repository.

Head

Required. The name of the branch where your changes are implemented.

For cross-repository pull requests in the same network, use the following format: username:branch.

Title

The title of the new pull request.

Body

The contents of the pull request.

Assignees

A newline-separated list of user names to assign to this PR.

Reviewers

A newline-separated list of user names and team names to requests review for this PR.

Result property sheet

The results are saved into this property/property sheet. It is a JSON object that contains pull request data.

Output parameters

Table 4. Create Pull Request output parameters
Parameter	Description
createPullRequest	A JSON object that contains pull request data.

Create Release

Creates a new GitHub release or updates an existing GitHub release.

Input parameters

Parameter Description

Name

Required. The previously defined configuration for the plugin.

Repository owner

Required. The name of the user or organization that owns the repository.

Repository name

Required. The name of the GitHub repository.

Update action

Required. Select the action to take if a release already exists. If Recreate is selected, the existing release is deleted, the tag associated with the release can optionally be deleted, and a new release is created. The release existence is checked based on the tag name.

Delete old tag?

If selected, the tag associated with the release is deleted.

You should delete old tags if you are using different commits as a release source.

Release name

The name for the release. For example, v1.0.0 or main.

Tag name

Required. The tag name for the release. The tag is applied to the commit specified in the Source commit field. If the Source commit is not specified, the HEAD commit is tagged.

Source commit

The commit to create a tag from. If not provided, the HEAD commit is tagged instead.

Release body

The description for the release.

Release assets

The release assets (files) in the form of {"name": "path/to/file"}. The assets are uploaded to the release. The files should exist in the agent’s filesystem.

Prerelease?

If selected, the release is marked as a prerelease.

Result property sheet

The results are saved into this property/property sheet. The JSON object contains the release data:

releaseId: This is the ID for the created release.
releaseLink: This is the link to the HTML page for the created release.

Output parameters

Table 6. Create Release output parameters
Parameter	Description
createRelease	A JSON object that contains the release data: releaseId: This is the ID for the created release. releaseLink: This is the link to the HTML page for the created release.

Create Repository

Creates a GitHub repository.

Input parameters

Parameter Description

Name

Required. The previously defined configuration for the plugin.

Repository owner

Required. The name of the user or organization that owns the repository.

Repository name

Required. The name of the GitHub repository.

Repository description

The GitHub repository description.

Public?

Select this option to create a public repository.

Teams

Defines the teams to add to the repository. Teams are newline-separated. Before you assign team permissions, create and define the organization’s teams in the GitHub settings. Available permissions are ADMIN, PULL, PUSH, TRIAGE, and MAINTAIN. For example, admins:ADMIN, or test team:PULL.

Teams are available for organization accounts only.

Add license?

Select this option to add a license to the repository.

License file

The path to the license file on the filesystem. If the file does not exist, the procedure results in an error.

Download Release Asset

Downloads the specified release asset from GitHub.

Input parameters

Table 8. Download Release Asset input parameters
Parameter	Description
Name	Required. The previously defined configuration for the plugin.
Repository owner	Required. The name of the user or organization that owns the repository.
Repository name	Required. The name of the GitHub repository.
Tag name	Required. The tag name for the release.
Asset name	Required. The name of the asset for downloading.
Asset path	The path to a destination file for the downloaded asset.
Result property sheet	The results are saved into this property/property sheet. It is the actual path for the downloaded asset.

Output parameters

Table 9. Download Release Asset output parameters
Parameter	Description
releaseAssetPath	Actual path for the downloaded asset.

Get Files

Fetches the content of the specified files and stores it in the filesystem or in the provided property.

Input parameters

Table 10. Get Files input parameters
Parameter	Description
Name	Required. The previously defined configuration for the plugin.
Repository owner	Required. The name of the user or organization that owns the repository.
Repository name	Required. The name of the GitHub repository.
Files	Required. The newline-separated list of paths to the files.
Folder to save files	The folder to save retrieved files, as an absolute or relative path. If not defined, `${COMMANDER_WORKSPACE}/${repoName}` is used.
Git reference	A reference to a Git branch, commit, or tag to download the file from.
Result property sheet	The results are saved into this property/property sheet. It is a list of uploaded files in JSON format.

Output parameters

Table 11. Get Files output parameters
Parameter	Description
getFiles	List of download files in JSON format.

Set Commit Status

Sets the status for a commit using its SHA.

Input parameters

Table 12. Set Commit Status input parameters
Parameter	Description
Name	Required. The previously defined configuration for the plugin.
Repository owner	Required. The name of the user or organization that owns the repository.
Repository name	Required. The name of the GitHub repository.
Commit SHA	Required. The SHA of the commit.
State	The state of the commit.
Target URL	The target URL to associate with this status. This URL is linked from the GitHub UI to allow you to easily view the source of the status.
Mimic runtime status	If selected, the GitHub status is posted according to the status of the current CloudBees CD/RO runtime.
Description	A short description of the status.

Upload Files

Uploads the provided files into the provided repository.

Input parameters

Table 13. Upload Files input parameters
Parameter	Description
Name	Required. The previously defined configuration for the plugin.
Repository owner	Required. The name of the user or organization that owns the repository.
Repository name	Required. The name of the GitHub repository.
Source folder	The folder resembling the repository source. If not provided, the current directory is used. The relative paths of the files are used to provide the path in the repository.
Mapping	A JSON mapping that provides the path to file in the repository. For example, `{"sourceFile": "repoFile"}`, where`sourceFile` is the path to the file, relative to the source directory and `repoFile` is the path in the repository where the file should be uploaded.
Files	The newline-separated list of files relative to the source folder.
Branch	Required. The branch name where the files are committed. If the branch name is not master/main, the branch is created from the master/main branch.
Create pull request?	If selected, a PR is created for the updated files.
Result property sheet	The results are saved into this property/property sheet. It is a list of uploaded files in JSON format.

Output parameters

Table 14. Upload Files output parameters
Parameter	Description
uploadFiles	List of upload files in JSON format.