Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 125 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,16 @@ This plugin is designed to be the Swiss Army knife for git API operations in Har
- 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

## How the plugin works
Expand All @@ -23,62 +30,162 @@ Plugin takes a list of settings (environment 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.

## Common plugin settings
`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

## Example Harness step

```yaml
- 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 and commands-specific settings
### Get pull request details
`COMMANDS=”getPrDetails”` \
`COMMANDS="getPrDetails"` \
`PR_NUMBER=123`

Outputs: `TITLE`, `BODY`, `USER_LOGIN`, `USER_EMAIL`, `BASE_BRANCH_NAME`, `BASE_SHA`, `HEAD_BRANCH_NAME`, `HEAD_SHA`,
`MERGE_COMMIT_SHA`, `STATE`, `URL` (API URL of the pull request), `CREATED_AT`, `IS_DRAFT`

### Get changed files
`COMMANDS=”getChangedFiles”` \
`COMMANDS="getChangedFiles"` \
`PR_NUMBER=123`

Outputs (JSON arrays of file paths): `CHANGED_FILES`, `MODIFIED_FILES`, `ADDED_FILES`, `REMOVED_FILES`, and `CHANGED_FILES_NUMBER`

### Set tag
`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.

### Create pull request
`COMMANDS=“createPullRequest”` \
`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”`
`PR_TITLE="[CIIT-321] Update version file"` \
`PR_BODY="Update version to v0.0.3"` \
`PR_LABELS="label1, label2"` (optional)

### Merge pull request
`COMMANDS=”mergePr”` \
`PR_NUMBER=123` \
`MERGE_COMMENT="Updating artifact version to 0.1.321"`
If a pull request for the same branches already exists, its title and body are updated instead.

### Set tag
`COMMANDS=“setTag”` \
`TAG_NAME=latest_green_staging` \
`SHA=<+{path to variable with git sha}>`
Outputs: `PR_NUMBER`, `PR_URL`, `PR_TITLE`, `PR_HEAD`, `PR_HEAD_SHA`, `PR_BASE`

### Add pull request labels
`COMMANDS="AddPullRequestLabels"` \
`PR_NUMBER=123` \
`PR_LABELS="label1, label2"`

### Set status check
`COMMANDS="setStatusCheck"` \
`STATUS_CHECK_SHA=<+{path to variable with git sha}>` \
`STATUS_CHECK_CONTEXT=BuildAndPushImages` \
`STATUS_CHECK_STATUS=success` \
`STATUS_CHECK_STATUS=success` (one of `pending`, `success`, `failure`, `error`) \
`STATUS_CHECK_URL=<+{pipeline/stage URL}>` \
`STATUS_CHECK_DESCRIPTION="Build and push project images"`
`STATUS_CHECK_DESCRIPTION="Build and push project images"`

### Get status checks
`COMMANDS="getStatuses"` \
`REF=branch-name-or-sha`

Outputs: `STATUSES` (`"<context> <state>, ..."`), `STATUSES_JSON` (`[{"context": ..., "status": ...}]`), latest state per context

### Wait for status check
`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`

### Merge pull request
`COMMANDS="mergePr"` \
`PR_NUMBER=123` \
`MERGE_COMMENT="Updating artifact version to 0.1.321"`

### Get git reference
`COMMANDS="getRef"` \
`REF=heads/main` (or `tags/v1.0.0`)

Outputs: `REF`, `SHA`, `SHORT_SHA` (11 characters), `URL`

### Get user permission
`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`)

### Create or update pull request comment
`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`)

### Add reaction to a comment
`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.

## Caveats and restrictions
Harness has a number of limitations that are related to plugin functionality:
- It doesn't process multiline output data
- 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.
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`.


Any failed API call fails the step.

## Links

Plugin docker image: https://ghcr.io/datarobot-oss/harness-github-api-plugin \
Harness documentation for plugins: https://developer.harness.io/docs/category/use-plugins/
Harness documentation for plugins: https://developer.harness.io/docs/category/use-plugins/
131 changes: 131 additions & 0 deletions comments.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
package main

import (
"context"
"fmt"
"log"
"os"
"slices"
"strconv"
"strings"

"github.com/google/go-github/v62/github"
)

// Reactions accepted by the GitHub API for issue and pull request comments.
var allowedReactions = []string{"+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes"}

// commentMarkerTag returns the hidden HTML comment used to find a comment again on later runs.
// GitHub does not render it, so it never shows up in the PR conversation.
func commentMarkerTag(marker string) string {
return fmt.Sprintf("<!-- harness-github-api-plugin:%s -->", marker)
}

// resolveCommentBody returns the comment body from COMMENT_BODY, or from the file named by
// COMMENT_BODY_FILE when it is set. A file lets an earlier Run step in the same stage write a long,
// multiline report that would be awkward to pass through a plugin setting.
func resolveCommentBody(body string, bodyFile string) string {
if bodyFile == "" {
return body
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Null optional settings are not ignored

Medium Severity

When COMMENT_BODY_FILE or COMMENT_MARKER is omitted, Harness can still pass the literal string null, which this plugin already treats as unset for PR_LABELS. resolveCommentBody then tries to open a file named null and fails the step, and a null marker is treated as a real upsert key instead of always creating a comment.

suggestion
if bodyFile == "" || bodyFile == "null" {
return body
}

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 93e5866. Configure here.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in the latest commit: a new optionalEnv helper treats null as unset for COMMENT_BODY, COMMENT_BODY_FILE and COMMENT_MARKER. Covering COMMENT_BODY too means a null body now fails with the "needs COMMENT_BODY or COMMENT_BODY_FILE" error instead of posting null as a comment.

content, err := os.ReadFile(bodyFile)
failOnErr(err)
return string(content)
}

// upsertPrComment creates a comment on a pull request. When marker is set, it first looks for a
// comment the token owner posted earlier with the same marker and edits that one instead, so a
// pipeline can keep a single comment per PR up to date across its stages and runs.
func upsertPrComment(client *github.Client, ctx *context.Context, repositoryName string, repositoryOwner string,
prNumberString string, body string, marker string) map[string]string {
prNumber, err := strconv.Atoi(prNumberString)
failOnErr(err)

if marker != "" {
tag := commentMarkerTag(marker)
body = body + "\n\n" + tag

existing := findMarkedComment(client, ctx, repositoryName, repositoryOwner, prNumber, tag)
if existing != nil {
fmt.Printf("Updating comment %d (marker %q)\n", existing.GetID(), marker)
comment, _, err := client.Issues.EditComment(*ctx, repositoryOwner, repositoryName, existing.GetID(),
&github.IssueComment{Body: &body})
failOnErr(err)
return commentFields(comment, "updated")
}
}

fmt.Printf("Creating comment on pull request %d\n", prNumber)
comment, _, err := client.Issues.CreateComment(*ctx, repositoryOwner, repositoryName, prNumber,
&github.IssueComment{Body: &body})
failOnErr(err)
return commentFields(comment, "created")
}

// findMarkedComment returns the most recent comment on the PR that carries tag and was written by the
// token owner, or nil. Comments by other users are ignored: the token usually cannot edit them, and
// someone quoting the bot's comment must not hijack it.
func findMarkedComment(client *github.Client, ctx *context.Context, repositoryName string, repositoryOwner string,
prNumber int, tag string) *github.IssueComment {
me, _, err := client.Users.Get(*ctx, "")
failOnErr(err)

var found *github.IssueComment
opts := &github.IssueListCommentsOptions{ListOptions: github.ListOptions{PerPage: 100}}
for {
comments, resp, err := client.Issues.ListComments(*ctx, repositoryOwner, repositoryName, prNumber, opts)
failOnErr(err)
for _, c := range comments {
if c.GetUser().GetLogin() == me.GetLogin() && strings.Contains(c.GetBody(), tag) {
found = c
}
}
if resp.NextPage == 0 {
break
}
opts.Page = resp.NextPage
}
return found
}

func commentFields(comment *github.IssueComment, action string) map[string]string {
return map[string]string{
"COMMENT_ID": strconv.FormatInt(comment.GetID(), 10),
"COMMENT_URL": comment.GetHTMLURL(),
"COMMENT_ACTION": action,
}
}

// addReaction adds an emoji reaction to an issue or pull request comment, e.g. to acknowledge the
// comment that triggered a pipeline. GitHub returns the existing reaction if it is already there.
func addReaction(client *github.Client, ctx *context.Context, repositoryName string, repositoryOwner string,
commentIdString string, reaction string) {
if !slices.Contains(allowedReactions, reaction) {
log.Fatalf("Unsupported reaction %q, use one of: %s", reaction, strings.Join(allowedReactions, ", "))
}
commentId, err := strconv.ParseInt(commentIdString, 10, 64)
failOnErr(err)
_, _, err = client.Reactions.CreateIssueCommentReaction(*ctx, repositoryOwner, repositoryName, commentId, reaction)
failOnErr(err)
}

// getUserPermission reports a user's permission on the repository, so a pipeline started by a PR
// comment can check that the commenter is allowed to run it. A user GitHub does not know is reported
// as "none" instead of failing the step, so the caller decides what to do.
func getUserPermission(client *github.Client, ctx *context.Context, repositoryName string, repositoryOwner string,
username string) map[string]string {
permission := "none"
level, resp, err := client.Repositories.GetPermissionLevel(*ctx, repositoryOwner, repositoryName, username)
if err != nil {
if resp == nil || resp.StatusCode != 404 {
log.Fatal(err)
}
fmt.Printf("User %s not found, reporting permission none\n", username)
} else {
permission = level.GetPermission()
}
return map[string]string{
"PERMISSION": permission,
"HAS_WRITE_ACCESS": strconv.FormatBool(permission == "admin" || permission == "write"),
}
}
10 changes: 10 additions & 0 deletions helpers.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,13 @@ func failOnErr(err error) {
log.Fatal(err)
}
}

// optionalEnv returns the plugin setting, treating "null" (what Harness passes for an
// unresolved optional expression) the same as unset.
func optionalEnv(name string) string {
v := os.Getenv(name)
if v == "null" {
return ""
}
return v
}
24 changes: 24 additions & 0 deletions main.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"fmt"
"github.com/gofri/go-github-ratelimit/github_ratelimit"
"github.com/google/go-github/v62/github"
"log"
"os"
"os/exec"
"strings"
Expand Down Expand Up @@ -98,6 +99,29 @@ func main() {
fields := getRef(client, &ctx, repositoryName, repositoryOwner, os.Getenv("PLUGIN_REF"))
writeResult(*results, fields)
}
if strings.Contains(commands, "getUserPermission") {
verifyPluginParameters([]string{"PLUGIN_USERNAME"})
fields := getUserPermission(client, &ctx, repositoryName, repositoryOwner, os.Getenv("PLUGIN_USERNAME"))
writeResult(*results, fields)
}
if strings.Contains(commands, "upsertPrComment") {
verifyPluginParameters([]string{"PLUGIN_PR_NUMBER"})
body := resolveCommentBody(optionalEnv("PLUGIN_COMMENT_BODY"), optionalEnv("PLUGIN_COMMENT_BODY_FILE"))
if body == "" {
log.Fatal("upsertPrComment needs COMMENT_BODY or COMMENT_BODY_FILE")
}
fields := upsertPrComment(client, &ctx, repositoryName, repositoryOwner,
os.Getenv("PLUGIN_PR_NUMBER"),
body,
optionalEnv("PLUGIN_COMMENT_MARKER"))
writeResult(*results, fields)
}
if strings.Contains(commands, "addReaction") {
verifyPluginParameters([]string{"PLUGIN_COMMENT_ID", "PLUGIN_REACTION"})
addReaction(client, &ctx, repositoryName, repositoryOwner,
os.Getenv("PLUGIN_COMMENT_ID"),
os.Getenv("PLUGIN_REACTION"))
}
results.Close()

out, err := exec.Command("cp", "-v", outputFile, copyOutputFile).Output()
Expand Down