This plugin is designed to be the Swiss Army knife for git API operations in Harness pipelines.
- Get pull request details
- Get changed files
- Create a pull request
- Add labels to a pull request
- Merge a pull request
- Create or update a pull request comment
- Add a reaction to a comment
- Get a user's permission on the repository
- Create/update git tag
- Get a git reference
- Set GitHub status check
- Get status checks
- Wait for a status check
- TBD, if you need a new feature added, reach to us in slack #continuous-integration
Plugin takes a list of settings (environment variables):
- common - required for all operations
- variable COMMANDS with list of actions to perform
- command-specific variables
It iterates through commands, performs requested operations and optionally exports data to the 'step output' harness section.
Several commands can be listed in COMMANDS (for example COMMANDS="getPrDetails,getChangedFiles").
They always run in the order the sections below are listed in, not in the order they are written in COMMANDS.
If you need a specific order, use separate steps.
GITHUB_AUTH_TOKEN - The GH PAT used for API calls
REPOSITORY_NAME
REPOSITORY_OWNER (GitHub organization, e.g. datarobot for repository)
COMMANDS - The list of actions the plugin should perform
- step:
type: Plugin
name: CommentOnPr
identifier: CommentOnPr
spec:
connectorRef: <docker registry connector for ghcr.io>
image: ghcr.io/datarobot-oss/harness-github-api-plugin
settings:
GITHUB_AUTH_TOKEN: <+secrets.getValue("github_token")>
REPOSITORY_OWNER: my-org
REPOSITORY_NAME: my-repository
COMMANDS: upsertPrComment
PR_NUMBER: <+trigger.prNumber>
COMMENT_MARKER: deploy-status
COMMENT_BODY: |-
:rocket: Deployment started: [execution](<+pipeline.executionUrl>)Outputs are read from later steps as <+execution.steps.CommentOnPr.output.outputVariables.COMMENT_ID>.
COMMANDS="getPrDetails"
PR_NUMBER=123
Optional settings, to build exactly what merging the pull request would produce (its test merge commit,
refs/pull/<N>/merge):
PR_WAIT_MERGEABLE=true - Wait until GitHub has computed the test merge commit for the current head. GitHub does
this in the background after each push, so right after a push mergeable is null and MERGE_COMMIT_SHA can still
be the merge of an earlier head. The step fails when the pull request is not open, has merge conflicts, or the merge
is not computed within the timeout.
PR_EXPECTED_HEAD_SHA=<sha> - With PR_WAIT_MERGEABLE, fail when the pull request head is another commit (the branch
moved since the caller resolved it).
PR_MERGEABLE_TIMEOUT=120 - With PR_WAIT_MERGEABLE, seconds to wait (default 120; polled every 5 seconds).
Outputs: TITLE, BODY, USER_LOGIN, USER_EMAIL, BASE_BRANCH_NAME, BASE_SHA, HEAD_BRANCH_NAME, HEAD_SHA,
MERGE_COMMIT_SHA, MERGEABLE (true, false, or empty while GitHub computes it), MERGEABLE_STATE, STATE,
URL (API URL of the pull request), CREATED_AT, IS_DRAFT
With PR_WAIT_MERGEABLE, MERGE_COMMIT_SHA is a merge of HEAD_SHA into the base branch. A shallow clone can fetch
it by SHA (git fetch --depth=1 origin <MERGE_COMMIT_SHA>).
COMMANDS="getChangedFiles"
PR_NUMBER=123
Outputs (JSON arrays of file paths): CHANGED_FILES, MODIFIED_FILES, ADDED_FILES, REMOVED_FILES, and CHANGED_FILES_NUMBER
COMMANDS="setTag"
TAG_NAME=latest_green_staging
SHA=<+{path to variable with git sha}>
Creates the tag, or moves it to SHA if it already exists.
COMMANDS="createPullRequest"
PR_SOURCE_BRANCH=author/ticket/feature
PR_TARGET_BRANCH=main
PR_TITLE="[CIIT-321] Update version file"
PR_BODY="Update version to v0.0.3" (optional)
PR_BODY_FILE=pr_body.md (optional, used instead of PR_BODY)
PR_ASSIGNEES="octocat, hubot" (optional)
PR_LABELS="label1, label2" (optional)
If a pull request for the same branches already exists, its title and body are updated instead.
Without PR_BODY and PR_BODY_FILE, the description is empty. Like COMMENT_BODY_FILE, PR_BODY_FILE is
read from the step's workspace, so an earlier Run step in the same stage can write a multiline description to
it (Harness output variables cannot carry multiline values).
Users who cannot be assigned are skipped with a warning.
Outputs: PR_NUMBER, PR_URL, PR_TITLE, PR_HEAD, PR_HEAD_SHA, PR_BASE
COMMANDS="AddPullRequestLabels"
PR_NUMBER=123
PR_LABELS="label1, label2"
COMMANDS="setStatusCheck"
STATUS_CHECK_SHA=<+{path to variable with git sha}>
STATUS_CHECK_CONTEXT=BuildAndPushImages
STATUS_CHECK_STATUS=success (one of pending, success, failure, error)
STATUS_CHECK_URL=<+{pipeline/stage URL}>
STATUS_CHECK_DESCRIPTION="Build and push project images"
COMMANDS="getStatuses"
REF=branch-name-or-sha
Outputs: STATUSES ("<context> <state>, ..."), STATUSES_JSON ([{"context": ..., "status": ...}]), latest state per context
COMMANDS="waitForStatus"
REF=branch-name-or-sha
STATUS_CHECK_CONTEXT=BuildAndPushImages
STATUS_CHECK_WAIT_TIMEOUT=30 (minutes, required)
Polls every 30 seconds until the status is success or failure, and fails the step if it is still pending
or missing when the timeout runs out.
Outputs: RESULT
COMMANDS="mergePr"
PR_NUMBER=123
MERGE_COMMENT="Updating artifact version to 0.1.321"
COMMANDS="getRef"
REF=heads/main (or tags/v1.0.0)
Outputs: REF, SHA, SHORT_SHA (11 characters), URL
COMMANDS="getUserPermission"
USERNAME=octocat
Reports the user's permission on the repository, for example to check that the author of a PR comment
may start a pipeline. A user GitHub does not know is reported as none; the step does not fail.
Outputs: PERMISSION (admin, write, read or none), HAS_WRITE_ACCESS (true for admin and write)
COMMANDS="upsertPrComment"
PR_NUMBER=123
COMMENT_BODY="Deployment finished"
COMMENT_BODY_FILE=report.md (optional, used instead of COMMENT_BODY)
COMMENT_MARKER=deploy-status (optional)
Without COMMENT_MARKER, every run adds a new comment.
With COMMENT_MARKER, the plugin adds a hidden marker (<!-- harness-github-api-plugin:<marker> -->) to the body.
On later runs it edits the most recent comment carrying the same marker instead of adding another one, so a pipeline
can keep one comment per pull request up to date. Only comments written by the owner of GITHUB_AUTH_TOKEN are
considered. Use different markers for comments that should stay separate, for example deploy-eks and deploy-gke.
COMMENT_BODY_FILE is read from the step's workspace, so an earlier Run step in the same stage can write
a long or multiline report to it.
Optional settings set to null (what Harness passes for an expression without a value) are treated as unset.
Outputs: COMMENT_ID, COMMENT_URL, COMMENT_ACTION (created or updated)
COMMANDS="addReaction"
COMMENT_ID=1234567890
REACTION=eyes (one of +1, -1, laugh, confused, heart, hooray, rocket, eyes)
Works for pull request and issue comments, for example to acknowledge the comment that triggered a pipeline
(<+trigger.payload.comment.id>). Adding a reaction that is already there is not an error.
Harness has a number of limitations that are related to plugin functionality:
- It doesn't read multiline output values: a single one makes the step lose all of its outputs. The plugin
therefore writes every value on one line, with newlines escaped as
\n(for exampleBODYofgetPrDetails); Harness turns them back into newlines. - It limits length of output data
If you hit these limitations, you can read the file named outputVariables that is created by the plugin in the current workspace directory.
Within the same pipeline stage run the command source outputVariables. Multiline values hold a literal \n
there; expand them with printf '%b' "$BODY".
Any failed API call fails the step.
Plugin docker image: https://ghcr.io/datarobot-oss/harness-github-api-plugin
Harness documentation for plugins: https://developer.harness.io/docs/category/use-plugins/