The Git plugin supports direct operations on git repositories with the git
task and interactions with git repositories hosted on GitHub with the github
task.
To be able to use the plugin in a Concord flow, it must be added as a dependency:
configuration:
dependencies:
- mvn://com.walmartlabs.concord.plugins:git:1.32.3
This adds the Git plugin to the classpath and allows you to invoke the Git task or the GitHub task.
The git
task allows users to trigger git operations as a step of a flow. The
operations are run via git command usage in the process working directory on the
Concord server.
The git
task uses a number of input parameters that are common for all
operations:
url
: required, the SSH or HTTPS URL of git repository
auth
: Required for HTTPS url
values, details in Basic authenticationprivateKey
: Required for SSH url
values.workingDir
: required, the name of the directory inside the process space on
the Concord server into which the git repository is cloned before any
operation is performed.action
: required, the name of the operation to perform.org
of the privateKey
parameter: Optional - the name of the organization
in Concord org where the secret can be located, if not specified defaults to
Default
.secretName
of the privateKey
parameter: required, the name of the Concord
secret used for the SSH connection to the git
repository on the remote server.ignoreErrors
: instead of throwing exceptions on operation failure, returns
the result object with the error, if set to true
.out
: variable to store the Git task response.Following is an example showing the common parameters with private key based authentication:
flows:
default:
- task: git
in:
action: "actionName"
url: "git@git.example.com:example-org/git-project.git"
workingDir: "git-project"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
The auth
parameter is required when a private git repository is accessed with
HTTPS url
. It must contain a basic
nested element which contains either the
token
element or the username
and password
elements.
Following example shows the common parameters with basic authentication using
username
& password
:
flows:
default:
- task: git
in:
action: "actionName"
url: "https://git.example.com/example-org/git-project.git"
workingDir: "git-project"
auth:
basic:
username: "any_username"
password: "any_password"
Here is an example of using basic authentication with token
:
auth:
basic:
token: base64_encoded_auth_token
The git
task returns a result object with following fields:
ok
: true
if the operation succeeded.status
: NO_CHANGES
if repository is clean, otherwise returns SUCCESS
or
FAILURE
if operation successful or failed respectively.error
: error message if operation failed.changeList
: saves the list of uncommitted changes.The clone
action of the git
task can be used to clone a git repository into
the Concord server process space.
It simply uses the minimal common parameters with the addition of the
baseBranch
parameter:
flows:
default:
- task: git
in:
action: "clone"
url: "git@git.example.com:example-org/git-project.git"
workingDir: "git-project"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
baseBranch: "feature-a"
out: "response"
ignoreErrors: true
- if: "${!response.ok}"
then:
- log: "Clone action failed: ${response.error}"
The baseBranch
parameter is optional and specifies the name of the branch, the
commit SHA identifier or the name of a tag, used to check out after the clone
operation. If not provided, the default branch of the repository is used -
typically called master
.
The pull
action of the git
task can be used to pull changes from another
branch from the remote origin
into the current checked out branch.
It simply uses the minimal common parameters with the addition of the
remoteBranch
parameter:
remoteBranch
: required, name of remote origin/branch
from where the
changes are pulled.Below example is equivalent to git pull origin myRemoteBranch
. In order to use
a pull
action in your concord flow, you have to run a clone
action first so
that a repository clone is available in the workingDir
. The value for the
workingDir
parameter should be same as what was used in clone
action,
otherwise you end up with an repository not found
exception.
flows:
default:
- task: git
in:
action: "pull"
workingDir: "git-project"
remoteBranch: "myRemoteBranch"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
The commit
action of the git
task can be used to commit your changes made on
the cloned repository. You can push the changes to origin by setting
pushChanges
to true
. The commit
action is dependent on a prior clone
action, so make sure clone
action is performed first.
- task: git
in:
action: "commit"
workingDir: "git-project"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
baseBranch: "feature-a"
commitMessage: "my commit message"
commitUsername: "myUserId"
commitEmail: "myEmail"
pushChanges: true
out: "response"
- if: "${response.ok}"
then:
- log: "Commit action completed successfully."
- log: "My changeList: ${response.changeList}."
The baseBranch
parameter is mandatory and specifies the name of the branch to
use to commit the changes. The commitMessage
is a message to add to your
commit operataion. The pushChanges
parameter is optional and defaults to
false
, when omitted. The commitUsername
and commitEmail
are mandatory
parameters to capture committer details.
Users can get the list of uncommitted changes using ${response.changeList}
variable.
The createBranch
action of the git
task allows the creation of a new
branch in the process space. The new branch can be pushed back to the remote
origin. The following parameters are needed in addition to the general
parameters:
baseBranch
: Optional - the name of the branch to use as starting point for
the new branch. If not provided, the default branch of the repository is used -
typically called master
.newBranch
: required, the name of new branch.pushBranch
: Required configuration to determine if the new branch
is pushed to the origin repository - true
or false
.The following example creates a new feature branch called feature-b
off the
master
branch and pushes the new branch back to the remote origin.
flows:
default:
- task: git
in:
action: "createBranch"
url: "git@git.example.com:example-org/git-project.git"
workingDir: "git-project"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
baseBranch: "master"
newBranch: "feature-b"
pushBranch: true
out: "response"
- if: "${response.ok}"
then:
- log: "Create-branch action completed successfully."
The merge
action of the git
task can be used to merge branches using the
following parameters:
sourceBranch
: required, the name of the branch where your changes are
implemented.destinationBranch
: required, the name of the branch into which the branches
have to be merged.The following example merges the changes in the branch feature-a
into the
master
branch.
flows:
default:
- task: git
in:
action: "merge"
url: "git@git.example.com:example-org/git-project.git"
workingDir: "git-project"
privateKey:
org: "myGitHubOrg"
secretName: "mySecret"
sourceBranch: "feature-a"
destinationBranch: "master"
out: "response"
- if: "${response.ok}"
then:
- log: "Merge action completed successfully."
We recommend using the merge action of the GitHub task to merge branches in large repositories, since no local cloning is required and the action is therefore completed faster.
The github
task of the git plugin allows you to trigger git operations on a
git repository hosted on GitHub.com or a GitHub
Enterprise server as a step of a flow.
While the git
mentioned above works on a repository by cloning it to the
Concord server and performing operations locally, the github
task uses the
REST API of GitHub to perform the operations. This avoids the network overhead
of the cloning and other operations and is therefore advantageous for large
repositories.
The apiUrl
configures the GitHub API endpoint. It is best configured globally
as
default process configuration:
with a githubParams
argument:
configuration:
arguments:
githubParam:
apiUrl: "https://github.example.com/api/v3"
The authors of specific projects on the Concord server can then specify the remaining parameters:
accessToken
: required, the GitHub
access token.org
: required, the name of the GitHub organization or user in which the git
repository is located.repo
: required, the name of the git repository.The following example includes a locally defined apiUrl
:
flows:
default:
- task: github
in:
action: "createPr"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
Examples below take advantage of a globally configured apiUrl
.
The createRepo
and deleteRepo
actions of the github
task allow the creation
and deletion of GitHub repositories.
createRepo
action creates an empty repository with the name provided by repo
parameter in the Github organization specified by org
parameter.
Output of createRepo
action is the clone URL of the repository created saved
as a cloneURL
variable.
The example below creates a repository myRepository
in the Github
organization myOrg
.
flows:
default:
- task: github
in:
action: "createRepo"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
org: "myRepository"
repo: "myOrg"
- log: "New repository: ${cloneUrl}"
deleteRepo
action deletes the repository with the name provided by repo
parameter in the Github organization specified by org
parameter.
Github access token specified should have
delete_repo
scope enabled to delete a repository on Github. This can be done in Personal Access Token under Developer Settings for the intended user on Github.
The example below deletes the repository myRepository
from the Github
organization myOrg
.
flows:
default:
- task: github
in:
action: "deleteRepo"
apiUrl: "https://github.example.com/api/v3"
accessToken: "myGitHubToken"
org: "myRepository"
repo: "myOrg"
A few points to consider:
createRepo
and deleteRepo
actions are idempotent.
createRepo
action does not fail if the repository already exists in
an organization, but returns the clone URL of the repository.deleteRepo
action does not fail if the repository does
not exist in the organization.createRepo
action can be supplemented by other git
and github
task
actions to commit code/documentation, and configure the repository.deleteRepo
action is irreversible. The repository, its contents and the
commit history will be deleted, and cannot be recovered.The createPr
and mergePr
actions of the github
task allow the creation and
merging a pull request in GitHub. Executed one after another, the tasks can be
used to create and merge a pull request within one Concord process.
The following parameters are needed by the createPr
action:
prTitle
: required, the title used for the pull request.prBody
: required, the description body for the pull request.prSourceBranch
: required, the name of the branch from where your changes
are implemented.prDestinationBranch
: required, the name of the branch into which the
changes are merged.The example below creates a pull request to merge the changes from branch
feature-a
into the master
branch:
flows:
default:
- task: github
in:
action: "createPr"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prTitle: "Feature A"
prBody: "Feature A implements the requirements from request 12."
prSourceBranch: "feature-a"
prDestinationBranch: "master"
out:
myPrId: "${prId}"
The mergePr
action can be used to merge a pull request. The pull request
identifier has to be known to perform the action. It can be available from a
form value, an external invocation of the process or as output parameter from
the createPr
action. The example below uses the pull request identifier myPrId
,
that was populated with a value in the createPr
action above.
commitMessage
is a string that can be used to post custom merge commit messages.
If omitted, a default message is used.
flows:
default:
- task: github
in:
action: "mergePr"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
commitMessage: "my custom merge commit message"
The commentPR
action can be used to add a comment to a pull request.
The pull request identifier has to be known to perform the action. It can be
available from a form value, an external invocation of the process or as output
parameter from the createPr
action.
The example below uses the pull request identifier myPrId
, that was populated
with a value in the createPr
action above. prComment
is the string that is
posted to the pull request as a comment. The accessToken
used determines the
user adding the comment.
flows:
default:
- task: github
in:
action: "commentPR"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
prComment: "Some pr comment"
The closePR
action can be used to close a pull request. The pull request
identifier has to be known to perform the action. It can be available from a
form value, an external invocation of the process or as output parameter from
the createPr
action. The example below uses the pull request identifier myPrId
,
that was populated with a value in the createPr
action above.
flows:
default:
- task: github
in:
action: "closePR"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
prId: "${myPrId}"
The createTag
action of the github
task can create a tag based on a specific
commit SHA. This commit identifier has to be supplied to the Concord flow -
typically via a parameter from a form or a invocation of the flow from another
application. One example is the usage of the Concord task in the Looper
continuous integration server.
commitSHA
: required, the SHA of the git commit to use for the tag creation.tagVersion
: required, the name of the tag e.g. a version string 1.0.1
.tagMessage
: required, the message associated with the tagging.tagAuthorName
: required, the name of the author of the tag.tagAuthorEmail
: required, the email of the author of the tag.flows:
default:
- task: github
in:
action: "createTag"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
tagVersion: "1.0.0"
tagMessage: "Release 1.0.0"
tagAuthorName: "Jane Doe"
tagAuthorEmail: "jane@example.com"
commitSHA: "${gitHubBranchSHA}"
The deleteTag
action of the github
task can be used to delete an existing
tag
from GitHub repository
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repository where your tag is locatedtagName
: required, name of tag
that you want to delete from your org/repo
flows:
default:
- task: github
in:
action: "deleteTag"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
tagName: "myTagName"
The deleteBranch
action of the github
task can be used to delete an existing
branch
from GitHub repository
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repository where your tag is locatedbranch
: required, name of the branch that you want to deleteflows:
default:
- task: github
in:
action: "deleteBranch"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
branch: myBranchName
The merge
action of the github
task can merge two branches of a repository
on GitHub. Compared to merging branches with the git task, it does not
require a local clone of the repository and is therefore faster in the execution
and requires no local storage on the Concord server.
The parameters identifying the branches to merge have to be supplied to the Concord flow - typically by a parameter from a form or a invocation of the flow from another application. One example is the usage of the Concord task in the Looper continuous integration server.
base
: required, the name of the base branch into which the head is merged.head
: required, the identifier for the head to merge. Head can be specified
by using a branch name or a commit SHA1.commitMessage
: required, - the message to use for the merge commit. If
omitted, a default message is used. Expressions can be used to add process
information.flows:
default:
- task: github
in:
action: "merge"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
base: "master"
head: "${gitHubBranchName}"
commitMessage: "Automated merge performed by Concord flow."
The forkRepo
action can be used to fork a git repository on GitHub. By
default, the repo
is forked into your personal account asscociated with the
accessToken
.
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repository that you want to forktargetOrg
: optional, if a value is specified the repository is forked into
specified organization, otherwise the target is the personal space of the user
specified with the accessToken
flows:
default:
- task: github
in:
action: "forkRepo"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
targetOrg: "myForkToOrg"
The getBranchList
action can be used to get the list of branches of a GitHub
repository. The output of the action is stored in a variable branchList
. It
can used at later point in the flow
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repository for which you want to get the
branch listflows:
default:
- task: github
in:
action: getBranchList
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
The getTagList
action can be used to get the list of tags of a GitHub
repository. The output of the action is stored in a variable tagList
. It can
used at later point in the flow.
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repository for which you want to get the tag
listflows:
default:
- task: github
in:
action: "getTagList"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
The getPRList
action can be used to get the list of PRs from a GitHub
repository. The output of the action is stored in a variable prList
,
which is a list of PullRequest
values. It can
used at later point in the flow.
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization.repo
: required, name of GitHub repository.state
: optional, state of a PR. Defaults to open
. Allowed values are all
, open
, closed
.flows:
default:
- task: github
in:
action: getPRList
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
state: "closed"
- if: ${prList.isEmpty()}
then:
- log: "Got zero PRs"
else:
- log: "PR Numbers : ${prList.stream().map(c -> c.get('number')).toList()}"
- log: "PR Titles: ${prList.stream().map(c -> c.get('title')).toList()}"
The getLatestSHA
action can be used to get the SHA identifier of latest commit
for a given branch. By default, it gets the SHA from the master
branch. The
output of the action is stored in the variable latestCommitSHA
. It can used at
later point in the flow.
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is locatedrepo
: required, name of GitHub repositorybranch
: name of Github branch from which you want to get the latest commit
SHA. Defaults to master
flows:
default:
- task: github
in:
action: "getLatestSHA"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
branch: "myBranch"
The addStatus
action can be used to add status messages to commits.
The following parameters are needed in addition to the general parameters:
org
: required, name of GitHub organization where your repository is located;repo
: required, name of GitHub repository;commitSHA
: ID of the commit which should receive the status update;context
, state
, targetUrl
and description
: attributes of the status
update. See the GitHub API documentation
for details.flows:
default:
- task: github
in:
action: "addStatus"
accessToken: "myGitHubToken"
org: "myGitHubOrg"
repo: "myGitHubRepo"
commitSHA: "dfd5...0262"
context: "myContext"
state: "pending"
targetUrl: "https://concord.example.com/#/process/${txId}"
description: "my status description"