diff --git a/README.md b/README.md index 592a738..567b6ab 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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: + 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` (`" , ..."`), `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 (``) 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/ diff --git a/comments.go b/comments.go new file mode 100644 index 0000000..259643f --- /dev/null +++ b/comments.go @@ -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("", 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 + } + 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"), + } +} diff --git a/helpers.go b/helpers.go index 90cb7a1..f225e04 100644 --- a/helpers.go +++ b/helpers.go @@ -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 +} diff --git a/main.go b/main.go index b5ac69e..cb7f5d7 100644 --- a/main.go +++ b/main.go @@ -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" @@ -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()