This plugin integrates with the GitHub API.
Plugin version 4.5.1.2022062106
Revised on June 23, 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.
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 to open the Plugin Manager.
-
Find the EC-Github-4.5.1.2022062106 row.
-
Click Configure to open the Configurations page.
-
Click Create Configuration as per the description of parameters below.
Configuration procedure parameters
| Parameter | Description |
|---|---|
If the rate limit is exceeded? | The behavior if the rate limit exceeded: throw exception or sleep until reset. |
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/>
Approve Pull Request
This procedure will approve a pull request for the specified repository.
Approve Pull Request parameters
| Parameter | Description |
|---|---|
Configuration Name | The previously-defined plugin configuration name. |
Repository owner | The name of the user or organization that owns the repository. |
Repository name | The name of the GitHub repository. |
Pull request identifier | The ID of the pull request. |
Body | The body text of the pull request review. Required when using REQUEST_CHANGES or COMMENT for the event parameter. |
Close and Merge Pull request? | Select this option to close and merge the pull request after approval. |
Result property sheet | JSON object that contains the pull request data. The results are saved in this property/property sheet. |
Create Pull Request
This procedure will create a pull request for the specified repository.
Create Pull Request parameters
| Parameter | Description |
|---|---|
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 |
Reviewers | List of usernames and team names to requests review for this PR from, newline-separated |
Result property sheet | The results will be saved into this property/property sheet. JSON object that contains PR data |
Create Release
This procedure can create a new GitHub release or update an existing one.
Create Release parameters
| Parameter | Description |
|---|---|
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 |
Create Repository
Creates a GitHub repository
Create Repository parameters
| Parameter | Description |
|---|---|
Configuration Name | The previously-defined plugin configuration name. |
Repository owner | The name of the user or organization that owns the repository. |
Repository name | The name of the GitHub repository. |
Repository Description | The repository description. |
Public? | Select this option to create a public repository. |
Teams | Teams are available for organization accounts only. Define the teams to add to the repository, for example, |
Add License? | Select this option to add a license to the repository. |
License File | 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 | The previously-defined plugin configuration name. |
Repository owner | The name of the user or organization that owns the repository. |
Repository name | The name of the GitHub repository. |
Tag name | The tag name for the release. |
Asset name | Asset name for the downloading. |
Asset path | Path to a destination file for the downloaded asset. |
Result property sheet | The results will be saved into this property/property sheet. Actual path for the downloaded asset. |
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
| Parameter | Description |
|---|---|
Configuration Name | The previously-defined plugin configuration name. |
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. |
Set Commit Status
Set status for a commit using its SHA
Set Commit Status parameters
| Parameter | Description |
|---|---|
Configuration Name | The previously-defined plugin configuration name. |
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
| Parameter | Description |
|---|---|
Configuration Name | The previously-defined plugin configuration name. |
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. |
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
Release notes
EC-Github 4.4.0
-
Enabled support for procedure "Download Release Asset"
-
Implemented rate limit checker
EC-Github 4.3.2
-
Added new parameter "reviewers" in "CreatePullRequest" procedure
-
Added possibility to request team reviews in "CreatePullRequest" procedure
EC-Github 4.2.0
-
Enabled support for procedure "Get Files".
-
Enabled support for procedure "Upload Files".
-
Enabled support for procedure "Create Pull Request".
-
Enabled support for procedure "Create Pull Request"
-
Enabled support for procedure "Set Commit Status"
-
Enabled support for procedure "Create Release"
-
[Improved the documentation:The difference between EC-Github, EC-Bitbucket and EC-Git]