GitHub plugin

8 minute readExtensibilityDeveloper productivity

This plugin integrates with the GitHub API and provides support for GitHub webhooks. The following event types are supported:

  • Push events

  • Pull requests

  • Commit status changes

Plugin version 4.5.3.2022101315

Revised on October 24, 2022

Overview

Integration with GitHub REST API to create, manage and manipulate git-repositories.

The difference between Git and other services around Git

Git

Provides the main functionality for managing git-repositories and their data, which can be deployed anywhere.

GitHub

Provides additional GitHub REST API functionality.

Bitbucket

Provides additional Bitbucket REST v2 API functionality.

Supported versions

The plugin has been tested with the following versions:

  • GitHub REST API v3

Plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, complete the following steps:

  1. Navigate to DevOps Essentials  Plugin Management  Plugin configurations.

  2. Select Add plugin configuration to create a new configuration.

  3. In the New Configuration window, specify a Name for the configuration.

  4. Select the Project that the configuration belongs to.

  5. Optionally, add a Description for the configuration.

  6. Select the appropriate Plugin for the configuration.

  7. Configure the parameters per the descriptions below.

Configuration procedure parameters

Parameter Description

If the rate limit is exceeded?

The behavior if the rate limit exceeded; return an exception or sleep until reset.

Configuration name

Required. The unique name for the configuration.

Description

The configuration description.

REST API Endpoint

Endpoint to connect to. By default, this is the GitHub API endpoint.

Auth scheme

The authorization scheme for the third-party connection.

Check Connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Debug level

This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, debug information is displayed. If Trace is selected, all requests and responses are displayed.

Plugin procedures

Approve Pull Request

Approves a pull request for the specified repository.

Approve Pull Request parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

Parameter Description

approvePullRequest

A JSON object that contains pull request data.

Create Pull Request

Creates a pull request for the specified repository.

Create Pull Request parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

Parameter Description

createPullRequest

A JSON object that contains pull request data.

Create Release

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

Create Release parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

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.

Create Repository parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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.

Download Release Asset parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

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

Get Files parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

Parameter Description

getFiles

List of download files in JSON format.

Set Commit Status

Sets the status for a commit using its SHA.

Set Commit Status parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

Upload Files parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

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

Parameter Description

uploadFiles

List of upload files in JSON format.

Webhook Support

The new Trigger model was introduced in the CloudBees CD/RO version 10.1.

EC-Github adds possibility to automate launch of the runtimes CloudBees CD/RO for: - Push events - Pull Requests - Commit status changes

Please refer to the CloudBees CD/RO documentation for the setup tutorial.

Runtime values according to the event type

When the procedure or pipeline is started by a webhook event, additional properties will be available under the /myWebhook property sheet. These properties are parsed from the event payload, which itself is saved under the /my(Job|PipelineRuntime|etc.)/webhookData. The list of parsed properties depends on the event type. In some cases, the event payload may not contain the data for a property, and it will be missing.

Push event

The runtime will contain the following properties:

  • branch

  • repository

  • eventType

  • commitId

  • commitMessage

  • commitAuthorName

  • commitAuthorEmail

  • webhookData/ref

  • webhookData/branch

Pull Request event

The runtime will contain the following properties:

  • branch

  • repository

  • eventType

  • commitId

  • commitAuthorName

  • webhookData/number

  • webhookData/title

  • webhookData/body

  • webhookData/state

  • webhookData/url

Commit Status event

The runtime will contain the following properties:

  • branch

  • repository

  • eventType

  • commitId

  • commitMessage

  • commitAuthorName

  • commitAuthorEmail

  • webhookData/sha

  • webhookData/state

The branch names in the Include Branches and Exclude Branches parameters are patterns, so the value main corresponds to any branch that contains main, e.g. test-main-data. If you want to specify the exact branch you should use the line start and line end symbols ^main$.

Rate limiting

For API requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour. Authenticated requests are associated with the authenticated user, regardless of whether Basic Authentication or an OAuth token was used. This means that all OAuth applications authorized by a user share the same quota of 5,000 requests per hour when they authenticate with different tokens owned by the same user.

More information is on the official site.

If the user exceeds the rate limit, the plugin does not fail - it actually waits for the limits to be renewed. It looks like the job is stuck but in fact, it is waiting for the limits to update, ~1 hour.

Use cases

Pipeline: Clone → Build → Create Release

Pipeline

Step: Clone

Step: Clone

Step: Build

Step: Build

Step: Create Release

Step: Create Release

Pipeline: Clone → Change → Commit + Push → Create PR

Pipeline

Step: Clone

Step: Clone

Step: Change

Step: Change

Step: Commit + Push

Step: Commit + Push
Step: Commit + Push

Step: Create PR

Step: Create PR

Pipeline: Get file → Change → Upload file

Pipeline

Step: Get file

Step: Get file

Step: Change

Step: Change

Step: Upload file

Step: Upload file

Release notes

EC-Github 4.5.3

  • Upgraded Jackson-Databind to v2.14.0-rc1.

EC-Github 4.5.2

  • Improved the documentation for trigger setup.

EC-Github 4.5.1

  • Fixed the repository name in the Create Repository procedure.

EC-Github 4.5.0

  • Added a procedure for approving a pull request.

EC-Github 4.4.3

  • Corrected the documentation for triggers.

EC-Github 4.4.2

  • Upgraded Jackson-Databind to v2.13.2.2.

EC-Github 4.4.1

  • Updated dependencies.

EC-Github 4.4.0

  • Added support for the Download Release Asset procedure.

  • Implemented a rate limit checker.

EC-Github 4.3.4

  • Updated dependencies.

EC-Github 4.3.3

  • Upgraded Jackson-Databind to v2.13.1.

EC-Github 4.3.2

  • Added a new Reviewers parameter to the CreatePullRequest procedure.

  • Added the option to request team reviews to the CreatePullRequest procedure.

EC-Github 4.2.1

  • Updated dependencies.

EC-Github 4.2.0

  • Added support for the Get Files procedure.

  • Added support for the Upload Files procedure.

  • Added support for the Create Pull Request procedure.

  • Added support for the Create Pull Request procedure.

  • Added support for the Set Commit Status procedure.

  • Added support for the Create Release procedure.

  • Improved the documentation to describe the differences between EC-Github, EC-Bitbucket and EC-Git plugins.

EC-Github 4.1.1

  • Fixed the webhook debug script.

EC-Github 4.1.0

  • Added support for the new plugin configurations.

EC-Github 4.0.4

  • Upgraded third-party dependencies.

EC-Github 4.0.3

  • Upgraded third-party dependencies to address certain vulnerabilities.

EC-Github 4.0.2

  • Missing event handling checkbox for triggers are now properly handled.

EC-Github 4.0.1

  • Fixed an issue where the plugin could not process some log levels.

EC-Github 4.0.0

  • The plugin is now supported by CloudBees.

  • Added Webhook event processing support.