GitHub

6 minute readExtensibilityDeveloper productivity

This plugin integrates with the GitHub API.

Plugin version 4.2.0.2021100654

Revised on October 05, 2021

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 apply across some or all of the plugin procedures. They reduce repetition of common values, create predefined parameter sets for end users, and securely store credentials where needed. Each configuration is given a unique name that is entered in designated parameters on procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD, do these steps:

  • Go to Administration Plugins to open the Plugin Manager.

  • Find the EC-Github-4.2.0.2021100654 row.

  • Click Configure to open the Configurations page.

  • Click Create Configuration as per the description of parameters below.

Configuration procedure parameters

ParameterDescription

Configuration Name

Unique name for the configuration

Description

Configuration description

REST API Endpoint

Endpoint to connect to. By default the GitHub API endpoint.

Auth Scheme

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 debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

Plugin procedures

<b>IMPORTANT</b> For all parameter descriptions in this section, required parameters are shown in <span class="required">bold italics</span>.<br/>

Create Pull Request

This procedure will create a pull request for the specified repository.

Create Pull Request parameters

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

Repository owner

The name of the user or organization which owns the repository.

Repository name

The name of the GH repository.

Base

The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository.

Head

The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace head with a user like this: username:branch.

Title

The title of the new pull request.

Body

The contents of the pull request.

Assignees

List of usernames to assign this PR to, newline-separated

Result property sheet

The results will be saved into this property/property sheet. JSON object that contains PR data

Output parameters

ParameterDescription

createPullRequest

JSON object that contains PR data

Create Release

This procedure can create a new GitHub release or update an existing one.

Create Release parameters

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

Repository owner

The name of the user or organization which owns the repository.

Repository name

The name of the GH repository.

Update action

Choose update action - what to do if the release already exists. If recreate is chosen, it will try to delete the existing release and optionally the tag, associated with it, and create a new one. The release existence will be checked by the tag name.

Delete old tag?

If checked, the old tag associated with the old release will be deleted. It is recommended to delete old tags in case you are using different commits as a release source.

Release name

The name for the release, e.g. v1.0.0 or Main.

Tag name

Tag name for the release. The commit provided in the "commitish" field will be tagged with this tag. If the commit is not provided, the HEAD commit will be tagged.

Source commit

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

Release body

Description for the release.

Release assets

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

Prerelease?

If checked, the release will be marked as a prerelease.

Result property sheet

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

* releaseId: This is the ID of the created release * releaseLink: This is the link to the HTML page of the created release

Output parameters

ParameterDescription

createRelease

JSON object that contains the release data:

* releaseId: This is the ID of the created release * releaseLink: This is the link to the HTML page of the created release

Get Files

This procedure fetches the content of the specified files and stores it in the filesystem or in the provided property

Get Files parameters

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

Repository owner

The name of the user or organization which owns the repository.

Repository name

The name of the GH repository.

Files

The newline-separated list of paths to the files

Folder to save files

The folder to save retrieved files, absolute or relative path. If not defined then will be use: ${COMMANDER_WORKSPACE}/${repoName}.

Git reference

Reference (branch, commit or tag to download file from)

Result property sheet

The results will be saved into this property/property sheet. List of download files in JSON format.

Output parameters

ParameterDescription

getFiles

List of download files in JSON format.

Set Commit Status

Set status for a commit using its SHA

Set Commit Status parameters

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

Repository owner

The name of the user or organization which owns the repository.

Repository name

The name of the GH repository.

Commit SHA

Commit SHA of the commit to set status to.

State

State for the commit.

Target URL

The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the source of the status.

Mimic runtime status

If selected, the GH status will be posted according to the status of the current CD runtime.

Description

A short description of the status.

Upload Files

This procedure uploads the provided files into the provided repository

Upload Files parameters

ParameterDescription

Configuration Name

Previously defined configuration for the plugin

Repository owner

The name of the user or organization which owns the repository.

Repository name

The name of the GH repository.

Source folder

The folder resembling the repository source. If not provided, the current directory will be used. The relative paths of the files will be used to provide the path in the repository.

Mapping

A mapping in JSON form to provide the path to file in the repository, e.g. {"sourceFile": "repoFile"} where sourceFile is the path to the file relative to the source directory and repoFile is the path in the repository where file should be uploaded.

Files

The newline-separated list of files relative to the source folder.

Branch

A branch name to commit files to. If not master/main, the branch will be created from the master/main branch.

Create pull request?

If checked, a PR will be created for the updated files.

Result property sheet

The results will be saved into this property/property sheet. List of uploaded files in JSON format.

Output parameters

ParameterDescription

uploadFiles

List of upload files in JSON format.

Webhook Support

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

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

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

Runtime values according to the event type

When the procedure/pipeline/etc. is started by a webhook event, additional properties will be available under the '/myWebhook' property sheet. This 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

Notes: The branch names in the "Include Branches" and "Exclude Branches" are patterns, so the value 'master' will correspond to any branch that contains 'master', e.g. 'test-*master*ing-data'. If you want to specify the exact branch you should use the line start and line end symbols '^master$'.

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

Step: Clone

Step: Build

Step: Create Release

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

Step: Clone

Step: Change

Step: Commit + Push

Step: Create PR

Pipeline: Get file → Change → Upload file

Step: Get file

Step: Change

Step: Upload file

Release notes

EC-Github 4.2.0

  • Enabled support for procedure "Get Files".

  • Enabled support for procedure "Upload Files".

  • Enabled support for procedure "Create Pull Request".

EC-Github 4.1.1

  • Fixed 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 Trigger is now treated as disabled.

EC-Github 4.0.1

  • Fixed issue when plugin could not process some log levels.

EC-Github 4.0.0

  • The plugin has been made CloudBees supported.

  • Added Webhook event processing support.