GitHub (jenkins-library 1.4.0 API)

jenkins_shared_library.scm.GitHub

Methods to work with GitHub.

Example:

     def github = new GitHub(this)
     // init github configurations
     github.init(
         repository                 : 'zowe/explorer-jes',
         branch                     : 'master',
         usernamePasswordCredential : 'my-github-credential',
         email                      : 'my-github-user@gmail.com'
     )
     // do some modifications
     // ...
     // commit changes
     github.commit('My work is done')
     // push to remote
     github.push()
     // check if the branch is synced
     if (!github.isSynced()) {
         echo "Branch is not synced with remote."
     }

Field Summary

Fields
Modifiers	Name	Description
`static java.lang.String`	`DEFAULT_BRANCH`	Default branch name.
`static java.lang.String`	`DEFAULT_REMOTE`	Default remote name.
`static java.lang.String`	`GITHUB_API_DOMAIN`	GitHub domain name for api calls.
`static java.lang.String`	`GITHUB_DOMAIN`	GitHub domain name.
`static java.lang.String`	`GITHUB_DOWNLOAD_DOMAIN`	GitHub domain name for downloading user content.

Properties Summary

Properties
Type	Name and description
`java.lang.String`	`branch` Github branch to checkout
`java.lang.String`	`email` github user email
`java.lang.String`	`folder` Folder where the repository is cloned to.
`java.lang.String`	`remote` Remote name
`java.lang.String`	`repository` Github repository in format of `owner/repo`.
`java.lang.Object`	`steps` Reference to the groovy pipeline variable.
`java.lang.String`	`username` github user name
`java.lang.String`	`usernamePasswordCredential` Jenkins credential ID for github username/password

Constructor Summary

Constructors
Constructor and description
`GitHub (java.lang.Object steps)` Constructs the class.

Methods Summary

Methods
Type Params	Return Type	Name and description
	`void`	`checkout(java.util.Map args = [:])` Checkout a new branch
	`void`	`checkout(java.lang.String branch, java.lang.Boolean isNew = false)` Checkout a new branch
	`void`	`cloneRepository(java.util.Map args = [:])` Clone a repository.
	`java.lang.Boolean`	`closePullRequest(java.util.Map args = [:])` Close pull request
	`java.lang.Boolean`	`closePullRequest(java.lang.Integer pr)` Return infomation of a pull request
	`java.lang.String`	`command(java.lang.String command)` Issue git command and get stdout return.
	`void`	`commit(java.util.Map args = [:])` Commit all the changes.
	`void`	`commit(java.lang.String message)` Commit all the changes.
	`void`	`config()` Setup git config of username/email based on properties.
	`java.lang.Integer`	`createPullRequest(java.util.Map args = [:])` Create pull request based on current branch
	`java.lang.Integer`	`createPullRequest(java.lang.String base, java.lang.String title, java.lang.String body = '')` Create pull request based on current branch
	`void`	`deleteRemoteBranch(java.util.Map args = [:])` Delete remote branch.
	`java.util.Map`	`getLastCommit(java.util.List fields = ['hash'])` Get last commit information.
	`java.lang.String`	`getLastCommitHash(java.lang.Boolean returnLong = true)` Get last commit hash.
	`java.util.Map`	`getPullRequest(java.util.Map args = [:])` Return infomation of a pull request
	`java.util.Map`	`getPullRequest(java.lang.Integer pr)` Return infomation of a pull request
	`void`	`init(java.util.Map args = [:])` Initialize github properties
	`void`	`initFromFolder(java.lang.String folder = '')` We can guess repository/branch information from an existing git folder.
	`java.lang.Boolean`	`isClean(java.util.Map args = [:])` Check if current working tree is clean or not.
	`java.lang.Boolean`	`isSynced(java.util.Map args = [:])` Check if current branch is synced with remote.
	`void`	`push(java.util.Map args = [:])` Push all local commits to remote.
	`void`	`reset(java.util.Map args = [:])` Reset current branch to remote.
	`void`	`tag(java.util.Map args = [:])` Tag the branch and push to remote.
	`void`	`tag(java.lang.String tag)` Tag the branch and push to remote.
	`java.lang.Boolean`	`tagExistsLocal(java.lang.String tag)` Validate if a tag exists in local.
	`java.lang.Boolean`	`tagExistsRemote(java.lang.String tag)` Validate if a tag exists in remote.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class java.lang.Object`	`java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- Field Detail
  - public static final java.lang.String DEFAULT_BRANCH
    
    Default branch name.
    Default:
    "master"
  - public static final java.lang.String DEFAULT_REMOTE
    
    Default remote name.
    Default:
    "origin"
  - public static final java.lang.String GITHUB_API_DOMAIN
    
    GitHub domain name for api calls.
    Default:
    "api.github.com"
  - public static final java.lang.String GITHUB_DOMAIN
    
    GitHub domain name.
    Default:
    "github.com"
  - public static final java.lang.String GITHUB_DOWNLOAD_DOMAIN
    
    GitHub domain name for downloading user content.
    Default:
    "raw.githubusercontent.com"
- Property Detail
  - java.lang.String branch
    
    Github branch to checkout
  - java.lang.String email
    
    github user email
  - java.lang.String folder
    
    Folder where the repository is cloned to.
  - java.lang.String remote
    
    Remote name
  - java.lang.String repository
    
    Github repository in format of owner/repo. The owner can be organization or GitHub user.
    Example:
    - org/repo-name
    
    - user/repo-name
  - java.lang.Object steps
    
    Reference to the groovy pipeline variable.
  - java.lang.String username
    
    github user name
  - java.lang.String usernamePasswordCredential
    
    Jenkins credential ID for github username/password
- Constructor Detail
  - GitHub(java.lang.Object steps)
    
    Constructs the class.
    When invoking from a Jenkins pipeline script, the Pipeline must be passed the current environment of the Jenkinsfile to have access to the steps.
    Example:
    def github = new GitHub(this)
    Parameters:
    steps - The workflow steps object provided by the Jenkins pipeline
- Method Detail
  - void checkout(java.util.Map args = [:])
    
    Checkout a new branch
    Note:
    After checkout, the
    Example:
    github.checkout('feature/test')
    Note:
    Use similar parameters defined in init(Map) method and with these extra parameters:
    oaram:
    isNew if we need to create this new branch
    
    Parameters:
    branch - branch name
  - void checkout(java.lang.String branch, java.lang.Boolean isNew = false)
    
    Checkout a new branch
    See Also:
    checkout(Map)
  - void cloneRepository(java.util.Map args = [:])
    
    Clone a repository.
    Note:
    Ideally this method should be called clone, which is conflicted with java.lang.Object#clone().
    Example:
    github.cloneRepository( branch : 'my-branch', folder : '.tmp-my-branch' )
    Note:
    Use similar parameters defined in init(Map) method and with these extra parameters:
    
    Parameters:
    branch - branch to checkout
    folder - which folder to save the cloned files
  - java.lang.Boolean closePullRequest(java.util.Map args = [:])
    
    Close pull request
    Note:
    Use similar parameters defined in init(Map) method.
    
    Parameters:
    pr - pull request id
    Returns:
    true if succeed
  - java.lang.Boolean closePullRequest(java.lang.Integer pr)
    
    Return infomation of a pull request
    See Also:
    getPullRequest(Map)
  - java.lang.String command(java.lang.String command)
    
    Issue git command and get stdout return.
    Example:
    String result = github.command('git rev-parse HEAD') // result should be a string with latest commit hash
    Parameters:
    command - git command
    Returns:
    stdout log
  - void commit(java.util.Map args = [:])
    
    Commit all the changes.
    Note:
    This method will include all local changes, even though they are not staged.
    Note:
    The commit made by this method has sign-off of the git user.
    Example:
    github.commit('my changes to handle some errors')
    Note:
    Use similar parameters defined in init(Map) method and with these extra parameters:
    
    Parameters:
    message - git commit message
  - void commit(java.lang.String message)
    
    Commit all the changes.
    See Also:
    commit(Map)
  - void config()
    
    Setup git config of username/email based on properties.
  - java.lang.Integer createPullRequest(java.util.Map args = [:])
    
    Create pull request based on current branch
    Note:
    The branch must be synced with remote. Otherwise please push all changes or reset to remote before creating pull request.
    Note:
    Use similar parameters defined in init(Map) method.
    
    Parameters:
    title - pull request title to be created
    base - base branch
    body - pull request body message
    draft - boolean, if this is a draft pull request
    Returns:
    pull request ID if it's successfully
  - java.lang.Integer createPullRequest(java.lang.String base, java.lang.String title, java.lang.String body = '')
    
    Create pull request based on current branch
    See Also:
    createPullRequest(Map)
  - void deleteRemoteBranch(java.util.Map args = [:])
    
    Delete remote branch.
    Note:
    Use similar parameters defined in init(Map) method.
  - java.util.Map getLastCommit(java.util.List fields = ['hash'])
    
    Get last commit information.
    Example:
    def info = github.getLastCommit(['hash', 'subject']) echo "Current commit hash : ${info['hash']}" echo "Current commit subject : ${info['subject']}"
    Parameters:
    fields - List of what information of the commit should be returned. Available fields are:
    
    - hash
    
    - shortHash
    
    - author
    
    - email
    
    - timestamp
    
    - date
    
    - subject
    
    - body
    Returns:
    last commit information map with fields asked for
  - java.lang.String getLastCommitHash(java.lang.Boolean returnLong = true)
    
    Get last commit hash.
    Example:
    def commitHash = github.getLastCommitHash()
    Parameters:
    returnLong - return long or short hash
    Returns:
    last commit hash
  - java.util.Map getPullRequest(java.util.Map args = [:])
    
    Return infomation of a pull request
    See Also:
    https
    Parameters:
    pr - pull request id
    Returns:
    pull request object
  - java.util.Map getPullRequest(java.lang.Integer pr)
    
    Return infomation of a pull request
    See Also:
    getPullRequest(Map)
  - void init(java.util.Map args = [:])
    
    Initialize github properties
    Note:
    The below parameters are supported keys of the args Map.
    
    Parameters:
    repository - repository name
    branch - branch name to work with (like clone, push, etc). Optional, default value is DEFAULT_BRANCH.
    folder - target folder
    usernamePasswordCredential - github username/password credential
    username - github user.name config. Optional, can be extracted from credential
    email - github user.email config
  - void initFromFolder(java.lang.String folder = '')
    
    We can guess repository/branch information from an existing git folder.
    Note:
    This method may update #repository and/or #branch fields.
    
    Parameters:
    folder - which folder to test
  - java.lang.Boolean isClean(java.util.Map args = [:])
    
    Check if current working tree is clean or not.
    Example:
    if (!github.isClean()) { echo "There are changes not committed." }
    Note:
    Use similar parameters defined in init(Map) method.
    
    Returns:
    boolean to tell if it's clean or not
  - java.lang.Boolean isSynced(java.util.Map args = [:])
    
    Check if current branch is synced with remote.
    Example:
    if (!github.isSynced()) { echo "Branch is not synced with remote." }
    Note:
    This method won't throw exceptions if it's not synced.
    Note:
    Use similar parameters defined in init(Map) method.
    
    Returns:
    boolean to tell if it's synced or not
  - void push(java.util.Map args = [:])
    
    Push all local commits to remote.
    Note:
    Use similar parameters defined in init(Map) method.
  - void reset(java.util.Map args = [:])
    
    Reset current branch to remote. This is get rid of all local modifications.
    Note:
    This method will also do a fetch before reset.
    Note:
    Use similar parameters defined in init(Map) method.
  - void tag(java.util.Map args = [:])
    
    Tag the branch and push to remote.
    Note:
    Currently only support lightweighted tag.
    Note:
    Use similar parameters defined in init(Map) method and with these extra parameters:
    
    Parameters:
    tag - tag name to be created
  - void tag(java.lang.String tag)
    
    Tag the branch and push to remote.
    Note:
    Currently only support lightweighted tag.
    
    Parameters:
    tag - tag name to be created
    See Also:
    tag(Map)
  - java.lang.Boolean tagExistsLocal(java.lang.String tag)
    
    Validate if a tag exists in local.
    Example:
    if (github.tagExistsLocal('v1.2.3')) { echo "Tag v1.2.3 already exists in local." }
    Parameters:
    tag - tag name to check
    Returns:
    true/false
  - java.lang.Boolean tagExistsRemote(java.lang.String tag)
    
    Validate if a tag exists in remote.
    Example:
    if (github.tagExistsRemote('v1.2.3')) { echo "Tag v1.2.3 already exists in remote." }
    Parameters:
    tag - tag name to check
    Returns:
    true/false

Summary:
Field
Property
Constructor
Method

Groovy Documentation

[Groovy] Class GitHub

Field Summary

Properties Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Field Detail

public static final java.lang.String DEFAULT_BRANCH

public static final java.lang.String DEFAULT_REMOTE

public static final java.lang.String GITHUB_API_DOMAIN

public static final java.lang.String GITHUB_DOMAIN

public static final java.lang.String GITHUB_DOWNLOAD_DOMAIN

Property Detail

java.lang.String branch

java.lang.String email

java.lang.String folder

java.lang.String remote

java.lang.String repository

java.lang.Object steps

java.lang.String username

java.lang.String usernamePasswordCredential

Constructor Detail

GitHub(java.lang.Object steps)

Method Detail

void checkout(java.util.Map args = [:])

void checkout(java.lang.String branch, java.lang.Boolean isNew = false)

void cloneRepository(java.util.Map args = [:])

java.lang.Boolean closePullRequest(java.util.Map args = [:])

java.lang.Boolean closePullRequest(java.lang.Integer pr)

java.lang.String command(java.lang.String command)

void commit(java.util.Map args = [:])

void commit(java.lang.String message)

void config()

java.lang.Integer createPullRequest(java.util.Map args = [:])

java.lang.Integer createPullRequest(java.lang.String base, java.lang.String title, java.lang.String body = '')

void deleteRemoteBranch(java.util.Map args = [:])

java.util.Map getLastCommit(java.util.List fields = ['hash'])

java.lang.String getLastCommitHash(java.lang.Boolean returnLong = true)

java.util.Map getPullRequest(java.util.Map args = [:])

java.util.Map getPullRequest(java.lang.Integer pr)

void init(java.util.Map args = [:])

void initFromFolder(java.lang.String folder = '')

java.lang.Boolean isClean(java.util.Map args = [:])

java.lang.Boolean isSynced(java.util.Map args = [:])

void push(java.util.Map args = [:])

void reset(java.util.Map args = [:])

void tag(java.util.Map args = [:])

void tag(java.lang.String tag)

java.lang.Boolean tagExistsLocal(java.lang.String tag)

java.lang.Boolean tagExistsRemote(java.lang.String tag)