From c5fdfb5cc539a7ce4f1d3cd526ec1c1b9dd8bc65 Mon Sep 17 00:00:00 2001
From: Billy Lynch <wlynch@google.com>
Date: Wed, 4 Dec 2019 13:19:08 -0500
Subject: [PATCH] Add read-only copy of pull request object in resource output.

Also fixes minor permission issue (rwx -> rw for most files).

Initial fix to grant users access to the rest of the PR information.
This file is read-only so that we can use the subresources (e.g. labels,
comments, etc.) as the source of truth.

As a follow up, we may want to consider pruning this from the PR output.
I wasn't sure how to do this without forking the scm.PullRequest
resource. I'd like to avoid this in order to make updates to the
upstream scm library as easy as possible. This should be fine for now to
get into for 0.9.1, and we can iterate on this as needed.
---
 cmd/pullrequest-init/disk.go                  | 32 +++++----
 cmd/pullrequest-init/disk_test.go             | 10 +++
 cmd/pullrequest-init/example/base.json        |  1 +
 .../example/comments/505233618.json           |  1 +
 .../example/comments/505476017.json           |  1 +
 .../example/comments/505482755.json           |  1 +
 .../example/comments/505529049.json           |  1 +
 .../example/comments/505616303.json           |  1 +
 .../example/comments/505676294.json           |  1 +
 .../example/comments/505798994.json           |  1 +
 .../example/comments/505890656.json           |  1 +
 .../example/comments/505923534.json           |  1 +
 .../example/comments/506032472.json           |  1 +
 .../example/comments/506082430.json           |  1 +
 .../example/comments/506082465.json           |  1 +
 .../example/comments/507732301.json           |  1 +
 .../example/comments/507763725.json           |  1 +
 .../example/comments/508007084.json           |  1 +
 cmd/pullrequest-init/example/head.json        |  1 +
 cmd/pullrequest-init/example/labels/approved  |  0
 .../example/labels/cla%3A+yes                 |  0
 cmd/pullrequest-init/example/labels/lgtm      |  0
 cmd/pullrequest-init/example/labels/size%2FL  |  0
 cmd/pullrequest-init/example/pr.json          |  1 +
 .../example/status/cla%2Fgoogle.json          |  1 +
 .../pull-tekton-pipeline-build-tests.json     |  1 +
 .../pull-tekton-pipeline-go-coverage.json     |  1 +
 ...ull-tekton-pipeline-integration-tests.json |  1 +
 .../pull-tekton-pipeline-unit-tests.json      |  1 +
 cmd/pullrequest-init/example/status/tide.json |  1 +
 docs/resources.md                             | 66 +++----------------
 31 files changed, 62 insertions(+), 70 deletions(-)
 create mode 100644 cmd/pullrequest-init/example/base.json
 create mode 100644 cmd/pullrequest-init/example/comments/505233618.json
 create mode 100644 cmd/pullrequest-init/example/comments/505476017.json
 create mode 100644 cmd/pullrequest-init/example/comments/505482755.json
 create mode 100644 cmd/pullrequest-init/example/comments/505529049.json
 create mode 100644 cmd/pullrequest-init/example/comments/505616303.json
 create mode 100644 cmd/pullrequest-init/example/comments/505676294.json
 create mode 100644 cmd/pullrequest-init/example/comments/505798994.json
 create mode 100644 cmd/pullrequest-init/example/comments/505890656.json
 create mode 100644 cmd/pullrequest-init/example/comments/505923534.json
 create mode 100644 cmd/pullrequest-init/example/comments/506032472.json
 create mode 100644 cmd/pullrequest-init/example/comments/506082430.json
 create mode 100644 cmd/pullrequest-init/example/comments/506082465.json
 create mode 100644 cmd/pullrequest-init/example/comments/507732301.json
 create mode 100644 cmd/pullrequest-init/example/comments/507763725.json
 create mode 100644 cmd/pullrequest-init/example/comments/508007084.json
 create mode 100644 cmd/pullrequest-init/example/head.json
 create mode 100644 cmd/pullrequest-init/example/labels/approved
 create mode 100644 cmd/pullrequest-init/example/labels/cla%3A+yes
 create mode 100644 cmd/pullrequest-init/example/labels/lgtm
 create mode 100644 cmd/pullrequest-init/example/labels/size%2FL
 create mode 100644 cmd/pullrequest-init/example/pr.json
 create mode 100644 cmd/pullrequest-init/example/status/cla%2Fgoogle.json
 create mode 100644 cmd/pullrequest-init/example/status/pull-tekton-pipeline-build-tests.json
 create mode 100644 cmd/pullrequest-init/example/status/pull-tekton-pipeline-go-coverage.json
 create mode 100644 cmd/pullrequest-init/example/status/pull-tekton-pipeline-integration-tests.json
 create mode 100644 cmd/pullrequest-init/example/status/pull-tekton-pipeline-unit-tests.json
 create mode 100644 cmd/pullrequest-init/example/status/tide.json

diff --git a/cmd/pullrequest-init/disk.go b/cmd/pullrequest-init/disk.go
index bc6cfab766d..6bef194f25a 100644
--- a/cmd/pullrequest-init/disk.go
+++ b/cmd/pullrequest-init/disk.go
@@ -33,6 +33,7 @@ import (
 
 // /workspace/
 // /workspace/<resource>/
+// /workspace/<resource>/pr.json
 // /workspace/<resource>/labels/
 // /workspace/<resource>/labels/<label>
 // /workspace/<resource>/status/
@@ -72,12 +73,16 @@ func ToDisk(r *Resource, path string) error {
 		}
 	}
 
-	// Start with comments
+	// Make PR read-only. Users should use corresponding subresources if they
+	// want to interact with the PR.
+	if err := toDisk(filepath.Join(path, "pr.json"), r.PR, 0400); err != nil {
+		return err
+	}
+
 	if err := commentsToDisk(commentsPath, r.Comments); err != nil {
 		return err
 	}
 
-	// Now labels
 	if err := labelsToDisk(labelsPath, r.PR.Labels); err != nil {
 		return err
 	}
@@ -85,7 +90,6 @@ func ToDisk(r *Resource, path string) error {
 	// Now status
 	if err := statusToDisk(statusesPath, r.Status.Statuses); err != nil {
 		log.Print(err)
-
 		return err
 	}
 
@@ -105,11 +109,7 @@ func commentsToDisk(path string, comments []*scm.Comment) error {
 	for _, c := range comments {
 		id := strconv.Itoa(c.ID)
 		commentPath := filepath.Join(path, id+".json")
-		b, err := json.Marshal(c)
-		if err != nil {
-			return err
-		}
-		if err := ioutil.WriteFile(commentPath, b, 0600); err != nil {
+		if err := toDisk(commentPath, c, 0600); err != nil {
 			return err
 		}
 		manifest[id] = true
@@ -139,11 +139,7 @@ func statusToDisk(path string, statuses []*scm.Status) error {
 	for _, s := range statuses {
 		statusName := url.QueryEscape(s.Label) + ".json"
 		statusPath := filepath.Join(path, statusName)
-		b, err := json.Marshal(s)
-		if err != nil {
-			return err
-		}
-		if err := ioutil.WriteFile(statusPath, b, 0700); err != nil {
+		if err := toDisk(statusPath, s, 0600); err != nil {
 			return err
 		}
 	}
@@ -155,7 +151,15 @@ func refToDisk(name, path string, r scm.PullRequestBranch) error {
 	if err != nil {
 		return err
 	}
-	return ioutil.WriteFile(filepath.Join(path, name+".json"), b, 0700)
+	return ioutil.WriteFile(filepath.Join(path, name+".json"), b, 0600)
+}
+
+func toDisk(path string, r interface{}, perm os.FileMode) error {
+	b, err := json.Marshal(r)
+	if err != nil {
+		return err
+	}
+	return ioutil.WriteFile(path, b, perm)
 }
 
 // FromDisk outputs a PullRequest object from an on-disk representation at the specified path.
diff --git a/cmd/pullrequest-init/disk_test.go b/cmd/pullrequest-init/disk_test.go
index 697ba28b202..a3ceed29c8d 100644
--- a/cmd/pullrequest-init/disk_test.go
+++ b/cmd/pullrequest-init/disk_test.go
@@ -84,6 +84,16 @@ func TestToDisk(t *testing.T) {
 		t.Error(err)
 	}
 
+	// Base PR
+	pr := &scm.PullRequest{}
+	readAndUnmarshal(t, filepath.Join(d, "pr.json"), pr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if diff := cmp.Diff(pr, rsrc.PR); diff != "" {
+		t.Errorf("PullRequest: -want +got: %s", diff)
+	}
+
 	// Check the refs
 	checkRef := func(name string, r scm.PullRequestBranch) {
 		actualRef := scm.PullRequestBranch{}
diff --git a/cmd/pullrequest-init/example/base.json b/cmd/pullrequest-init/example/base.json
new file mode 100644
index 00000000000..ac474255828
--- /dev/null
+++ b/cmd/pullrequest-init/example/base.json
@@ -0,0 +1 @@
+{"Ref":"master","Sha":"723b9a9d560bdf4dc8fc6f697d53f662d3454ac8","Repo":{"ID":"146641150","Namespace":"tektoncd","Name":"pipeline","FullName":"tektoncd/pipeline","Perm":{"Pull":false,"Push":false,"Admin":false},"Branch":"master","Private":false,"Clone":"https://github.com/tektoncd/pipeline.git","CloneSSH":"git@github.com:tektoncd/pipeline.git","Link":"https://github.com/tektoncd/pipeline","Created":"2018-08-29T18:21:55Z","Updated":"2019-12-04T17:26:42Z"}}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505233618.json b/cmd/pullrequest-init/example/comments/505233618.json
new file mode 100644
index 00000000000..b044d67cb21
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505233618.json
@@ -0,0 +1 @@
+{"ID":505233618,"Body":"/retest","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505233618","Created":"2019-06-25T00:48:38Z","Updated":"2019-06-25T00:48:38Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505476017.json b/cmd/pullrequest-init/example/comments/505476017.json
new file mode 100644
index 00000000000..08b0acca597
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505476017.json
@@ -0,0 +1 @@
+{"ID":505476017,"Body":"\u003e Looks good to me, question though : right now it's up to the user to write github status or not right (with this PR) ? Do we envision some \"automation\" around that ?\r\n\r\nYup! Great question, I'd love to source more ideas around this. The straight-forward answer would be to provide a runner binary that would wrap test execution and transform status codes and stdout/stderr to the pull request object.\r\n\r\nIs there any work being done around passing state between TaskRuns (e.g. for conditional execution or something similar)?","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505476017","Created":"2019-06-25T14:40:57Z","Updated":"2019-06-25T14:40:57Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505482755.json b/cmd/pullrequest-init/example/comments/505482755.json
new file mode 100644
index 00000000000..0c383d5e42f
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505482755.json
@@ -0,0 +1 @@
+{"ID":505482755,"Body":"@wlynch yeah we need to think about that, as I think I remember talking about notification as a first-class citizen in Tekton maybe ? (and most likely write on a design docs).\r\n\r\n\u003e Is there any work being done around passing state between TaskRuns (e.g. for conditional execution or something similar)?\r\n\r\n@dibyom ^^ :angel: ","Author":{"Login":"vdemeester","Name":"","Email":"","Avatar":"https://avatars0.githubusercontent.com/u/6508?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505482755","Created":"2019-06-25T14:56:09Z","Updated":"2019-06-25T14:56:09Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505529049.json b/cmd/pullrequest-init/example/comments/505529049.json
new file mode 100644
index 00000000000..0652eb26ed7
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505529049.json
@@ -0,0 +1 @@
+{"ID":505529049,"Body":"@wlynch yes, the condition container will have access to some read only metadata. Right now, this is just the pipeline run including the status fields. We could expose this to task runs as well? Or do you need to write additional metadata that needs to be exposed?","Author":{"Login":"dibyom","Name":"","Email":"","Avatar":"https://avatars2.githubusercontent.com/u/3316877?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505529049","Created":"2019-06-25T16:50:26Z","Updated":"2019-06-25T16:50:26Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505616303.json b/cmd/pullrequest-init/example/comments/505616303.json
new file mode 100644
index 00000000000..7059b610c31
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505616303.json
@@ -0,0 +1 @@
+{"ID":505616303,"Body":"@dibyom Don't need to write more data, but it would be useful to expose it to TaskRuns to have a binary look for this information and automatically prep PR output as a response. Can you link me to that data and how TaskRuns can access it?","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505616303","Created":"2019-06-25T20:47:32Z","Updated":"2019-06-25T20:47:32Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505676294.json b/cmd/pullrequest-init/example/comments/505676294.json
new file mode 100644
index 00000000000..160b3f214ad
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505676294.json
@@ -0,0 +1 @@
+{"ID":505676294,"Body":"\u003e @wlynch yeah we need to think about that, as I think I remember talking about notification as a first-class citizen in Tekton maybe ? (and most likely write on a design docs).\r\n\u003e \r\n\u003e \u003e\r\n\r\nYeah, I think the automated use-cases for this would fit into something around either \"notification\" or \"conditional execution\".\r\n\r\nWith the conditional execution approach, a pipeline would have a Task that runs on either success or failure and writes the status to Github/Gitlab.","Author":{"Login":"dlorenc","Name":"","Email":"","Avatar":"https://avatars1.githubusercontent.com/u/1714486?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505676294","Created":"2019-06-26T01:02:26Z","Updated":"2019-06-26T01:02:26Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505798994.json b/cmd/pullrequest-init/example/comments/505798994.json
new file mode 100644
index 00000000000..9df1cd194cd
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505798994.json
@@ -0,0 +1 @@
+{"ID":505798994,"Body":"\u003e Yeah, I think the automated use-cases for this would fit into something around either \"notification\" or \"conditional execution\".\r\n\r\nThis could be implemented with the CloudEventPipelineResource as well. \r\nThe setup would be:\r\n- each task that needs to publish test results to the PR has an output resource of type cloudevent, which is sent to a dedicated tekton listener. The TaskRun, including status, is sent as body of the cloudevent.\r\n- an event binding is defined that accepts TaskRun completion events, and triggers a GitHub PR update Task(Run)\r\n- The GitHub PR update taskrun uses the PullRequest resource as input and output, and the metadata in the TaskRun (passed as parameter to the Task) to update GitHub\r\n\r\nThe advantages of using a separate Task/TaskRun are:\r\n- The status of the original Task is not affected by the outcome of the PR update\r\n- It doesn't require conditional execution\r\n- The Task that updates GitHub PRs can be as isolated as we want from the Task that runs the tests, which should make it easier to avoid leaking the GitHub token in logs.","Author":{"Login":"afrittoli","Name":"","Email":"","Avatar":"https://avatars0.githubusercontent.com/u/2205608?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505798994","Created":"2019-06-26T09:33:55Z","Updated":"2019-06-26T09:33:55Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505890656.json b/cmd/pullrequest-init/example/comments/505890656.json
new file mode 100644
index 00000000000..ca87d21b6a9
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505890656.json
@@ -0,0 +1 @@
+{"ID":505890656,"Body":"/retest","Author":{"Login":"afrittoli","Name":"","Email":"","Avatar":"https://avatars0.githubusercontent.com/u/2205608?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505890656","Created":"2019-06-26T14:06:11Z","Updated":"2019-06-26T14:06:11Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/505923534.json b/cmd/pullrequest-init/example/comments/505923534.json
new file mode 100644
index 00000000000..a70a14faf47
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/505923534.json
@@ -0,0 +1 @@
+{"ID":505923534,"Body":"\u003e @dibyom Don't need to write more data, but it would be useful to expose it to TaskRuns to have a binary look for this information and automatically prep PR output as a response. Can you link me to that data and how TaskRuns can access it?\r\n\r\nWIP but its a file (`pr-metadata.json`) in `/workspace` for condition containers ([sample](https://gist.github.com/dibyom/95031ac458455ca2b0c25206b7420f24))\r\n\r\nIts exposed to conditional pods at the moment and not regular taskruns. I opened https://github.com/tektoncd/pipeline/issues/1016 to track that.","Author":{"Login":"dibyom","Name":"","Email":"","Avatar":"https://avatars2.githubusercontent.com/u/3316877?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-505923534","Created":"2019-06-26T15:22:42Z","Updated":"2019-06-26T15:22:42Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/506032472.json b/cmd/pullrequest-init/example/comments/506032472.json
new file mode 100644
index 00000000000..11404c54525
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/506032472.json
@@ -0,0 +1 @@
+{"ID":506032472,"Body":"/assign @imjasonh","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-506032472","Created":"2019-06-26T20:28:38Z","Updated":"2019-06-26T20:28:38Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/506082430.json b/cmd/pullrequest-init/example/comments/506082430.json
new file mode 100644
index 00000000000..4e754b86c38
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/506082430.json
@@ -0,0 +1 @@
+{"ID":506082430,"Body":"/lgtm","Author":{"Login":"dlorenc","Name":"","Email":"","Avatar":"https://avatars1.githubusercontent.com/u/1714486?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-506082430","Created":"2019-06-26T23:36:10Z","Updated":"2019-06-26T23:36:10Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/506082465.json b/cmd/pullrequest-init/example/comments/506082465.json
new file mode 100644
index 00000000000..11dd113ed79
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/506082465.json
@@ -0,0 +1 @@
+{"ID":506082465,"Body":"/approve","Author":{"Login":"dlorenc","Name":"","Email":"","Avatar":"https://avatars1.githubusercontent.com/u/1714486?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-506082465","Created":"2019-06-26T23:36:18Z","Updated":"2019-06-26T23:36:18Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/507732301.json b/cmd/pullrequest-init/example/comments/507732301.json
new file mode 100644
index 00000000000..4692567c5c0
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/507732301.json
@@ -0,0 +1 @@
+{"ID":507732301,"Body":"/retest","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-507732301","Created":"2019-07-02T15:40:32Z","Updated":"2019-07-02T15:40:32Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/507763725.json b/cmd/pullrequest-init/example/comments/507763725.json
new file mode 100644
index 00000000000..1833c816844
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/507763725.json
@@ -0,0 +1 @@
+{"ID":507763725,"Body":"\u003e There is a binary checked in `cmd/pullrequest-init/pullrequest-init`. Is that intentional?\r\n\r\nGood catch! Removed.","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-507763725","Created":"2019-07-02T17:03:47Z","Updated":"2019-07-02T17:03:47Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/comments/508007084.json b/cmd/pullrequest-init/example/comments/508007084.json
new file mode 100644
index 00000000000..a939d24c1f3
--- /dev/null
+++ b/cmd/pullrequest-init/example/comments/508007084.json
@@ -0,0 +1 @@
+{"ID":508007084,"Body":"[APPROVALNOTIFIER] This PR is **APPROVED**\n\nThis pull-request has been approved by: *\u003ca href=\"https://github.com/tektoncd/pipeline/pull/995#pullrequestreview-254634050\" title=\"Approved\"\u003eafrittoli\u003c/a\u003e*, *\u003ca href=\"https://github.com/tektoncd/pipeline/pull/995#issuecomment-506082465\" title=\"Approved\"\u003edlorenc\u003c/a\u003e*, *\u003ca href=\"https://github.com/tektoncd/pipeline/pull/995#pullrequestreview-257350830\" title=\"LGTM\"\u003evdemeester\u003c/a\u003e*, *\u003ca href=\"https://github.com/tektoncd/pipeline/pull/995#\" title=\"Author self-approved\"\u003ewlynch\u003c/a\u003e*\n\nThe full list of commands accepted by this bot can be found [here](https://go.k8s.io/bot-commands).\n\nThe pull request process is described [here](https://git.k8s.io/community/contributors/guide/owners.md#the-code-review-process)\n\n\u003cdetails \u003e\nNeeds approval from an approver in each of these files:\n\n- ~~[OWNERS](https://github.com/tektoncd/pipeline/blob/master/OWNERS)~~ [dlorenc,vdemeester]\n\nApprovers can indicate their approval by writing `/approve` in a comment\nApprovers can cancel approval by writing `/approve cancel` in a comment\n\u003c/details\u003e\n\u003c!-- META={\"approvers\":[]} --\u003e","Author":{"Login":"tekton-robot","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/48335577?v=4","Link":"","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Link":"https://github.com/tektoncd/pipeline/pull/995#issuecomment-508007084","Created":"2019-07-03T09:01:16Z","Updated":"2019-07-03T09:01:16Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/head.json b/cmd/pullrequest-init/example/head.json
new file mode 100644
index 00000000000..3da63da7116
--- /dev/null
+++ b/cmd/pullrequest-init/example/head.json
@@ -0,0 +1 @@
+{"Ref":"pr","Sha":"2a8ec1793553186cf2a027a89ae58a2e690509f3","Repo":{"ID":"184178909","Namespace":"wlynch","Name":"pipeline","FullName":"wlynch/pipeline","Perm":{"Pull":false,"Push":false,"Admin":false},"Branch":"master","Private":false,"Clone":"https://github.com/wlynch/pipeline.git","CloneSSH":"git@github.com:wlynch/pipeline.git","Link":"https://github.com/wlynch/pipeline","Created":"2019-04-30T02:40:49Z","Updated":"2019-11-22T18:44:26Z"}}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/labels/approved b/cmd/pullrequest-init/example/labels/approved
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/cmd/pullrequest-init/example/labels/cla%3A+yes b/cmd/pullrequest-init/example/labels/cla%3A+yes
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/cmd/pullrequest-init/example/labels/lgtm b/cmd/pullrequest-init/example/labels/lgtm
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/cmd/pullrequest-init/example/labels/size%2FL b/cmd/pullrequest-init/example/labels/size%2FL
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/cmd/pullrequest-init/example/pr.json b/cmd/pullrequest-init/example/pr.json
new file mode 100644
index 00000000000..00ae853f2d1
--- /dev/null
+++ b/cmd/pullrequest-init/example/pr.json
@@ -0,0 +1 @@
+{"Number":995,"Title":"Add GitHub status updates to Pull Request CRD.","Body":"This adds support for the GitHub Status API\r\n(https://developer.github.com/v3/repos/statuses/).\r\n\r\nThis accompanies #778 and #895 to complete initial Pull Request support\r\nsupport for GitHub OAuth.\r\n\r\n\u003c!-- 🎉🎉🎉 Thank you for the PR!!! 🎉🎉🎉 --\u003e\r\n\r\n# Changes\r\n\r\nAdds GitHub status fetching and updates to Pull Request CRD.\r\n\r\n# Submitter Checklist\r\n\r\nThese are the criteria that every PR should meet, please check them off as you\r\nreview them:\r\n\r\n- [x] Includes [tests](https://github.com/tektoncd/community/blob/master/standards.md#principles) (if functionality changed/added)\r\n- [x] Includes [docs](https://github.com/tektoncd/community/blob/master/standards.md#principles) (if user facing)\r\n- [x] Commit messages follow [commit message best practices](https://github.com/tektoncd/community/blob/master/standards.md#commit-messages)\r\n\r\n_See [the contribution guide](https://github.com/tektoncd/pipeline/blob/master/CONTRIBUTING.md)\r\nfor more details._\r\n\r\n# Release Notes\r\n\r\n\u003c!--\r\nDoes your PR contain User facing changes?\r\n\r\nIf so, briefly describe them here so we can include this description in the\r\nrelease notes for the next release!\r\n--\u003e\r\n\r\n```\r\nAdds GitHub status fetching and updates to Pull Request CRD.\r\n```\r\n","Labels":[{"ID":0,"URL":"https://api.github.com/repos/tektoncd/pipeline/labels/approved","Name":"approved","Description":"Indicates a PR has been approved by an approver from all required OWNERS files.","Color":"abea59"},{"ID":0,"URL":"https://api.github.com/repos/tektoncd/pipeline/labels/cla:%20yes","Name":"cla: yes","Description":"Trying to make the CLA bot happy with ppl from different companies work on one commit","Color":"0c6a89"},{"ID":0,"URL":"https://api.github.com/repos/tektoncd/pipeline/labels/lgtm","Name":"lgtm","Description":"Indicates that a PR is ready to be merged.","Color":"6aed75"},{"ID":0,"URL":"https://api.github.com/repos/tektoncd/pipeline/labels/size/L","Name":"size/L","Description":"Denotes a PR that changes 100-499 lines, ignoring generated files.","Color":"ee9900"}],"Sha":"2a8ec1793553186cf2a027a89ae58a2e690509f3","Ref":"refs/pull/995/head","Source":"pr","Target":"master","Base":{"Ref":"master","Sha":"723b9a9d560bdf4dc8fc6f697d53f662d3454ac8","Repo":{"ID":"146641150","Namespace":"tektoncd","Name":"pipeline","FullName":"tektoncd/pipeline","Perm":{"Pull":false,"Push":false,"Admin":false},"Branch":"master","Private":false,"Clone":"https://github.com/tektoncd/pipeline.git","CloneSSH":"git@github.com:tektoncd/pipeline.git","Link":"https://github.com/tektoncd/pipeline","Created":"2018-08-29T18:21:55Z","Updated":"2019-12-04T17:26:42Z"}},"Head":{"Ref":"pr","Sha":"2a8ec1793553186cf2a027a89ae58a2e690509f3","Repo":{"ID":"184178909","Namespace":"wlynch","Name":"pipeline","FullName":"wlynch/pipeline","Perm":{"Pull":false,"Push":false,"Admin":false},"Branch":"master","Private":false,"Clone":"https://github.com/wlynch/pipeline.git","CloneSSH":"git@github.com:wlynch/pipeline.git","Link":"https://github.com/wlynch/pipeline","Created":"2019-04-30T02:40:49Z","Updated":"2019-11-22T18:44:26Z"}},"Fork":"wlynch/pipeline","Link":"https://github.com/tektoncd/pipeline/pull/995.diff","State":"closed","Closed":true,"Draft":false,"Merged":true,"Mergeable":false,"Rebaseable":false,"MergeableState":"","MergeSha":"260c2277fe8ec80b4adc54ccbbfce9bb135f2499","Author":{"Login":"wlynch","Name":"","Email":"","Avatar":"https://avatars3.githubusercontent.com/u/1844673?v=4","Link":"https://github.com/wlynch","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},"Assignees":[{"Login":"vdemeester","Name":"","Email":"","Avatar":"https://avatars0.githubusercontent.com/u/6508?v=4","Link":"https://github.com/vdemeester","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},{"Login":"ImJasonH","Name":"","Email":"","Avatar":"https://avatars1.githubusercontent.com/u/210737?v=4","Link":"https://github.com/ImJasonH","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"},{"Login":"dlorenc","Name":"","Email":"","Avatar":"https://avatars1.githubusercontent.com/u/1714486?v=4","Link":"https://github.com/dlorenc","Created":"0001-01-01T00:00:00Z","Updated":"0001-01-01T00:00:00Z"}],"Milestone":{"Number":0,"ID":0,"Title":"","Description":"","Link":"","State":""},"Created":"2019-06-20T15:42:17Z","Updated":"2019-07-03T09:02:49Z"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/cla%2Fgoogle.json b/cmd/pullrequest-init/example/status/cla%2Fgoogle.json
new file mode 100644
index 00000000000..cf8f778080b
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/cla%2Fgoogle.json
@@ -0,0 +1 @@
+{"State":"success","Label":"cla/google","Desc":"All necessary CLAs are signed","Target":""}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/pull-tekton-pipeline-build-tests.json b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-build-tests.json
new file mode 100644
index 00000000000..4db6ce4fbc9
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-build-tests.json
@@ -0,0 +1 @@
+{"State":"pending","Label":"pull-tekton-pipeline-build-tests","Desc":"Job triggered.","Target":"https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-build-tests/1146102490727452672/"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/pull-tekton-pipeline-go-coverage.json b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-go-coverage.json
new file mode 100644
index 00000000000..8afe0c4315c
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-go-coverage.json
@@ -0,0 +1 @@
+{"State":"pending","Label":"pull-tekton-pipeline-go-coverage","Desc":"Job triggered.","Target":"https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-go-coverage/1146102490727452675/"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/pull-tekton-pipeline-integration-tests.json b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-integration-tests.json
new file mode 100644
index 00000000000..cec556ec52c
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-integration-tests.json
@@ -0,0 +1 @@
+{"State":"pending","Label":"pull-tekton-pipeline-integration-tests","Desc":"Job triggered.","Target":"https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-integration-tests/1146102490727452674/"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/pull-tekton-pipeline-unit-tests.json b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-unit-tests.json
new file mode 100644
index 00000000000..09477c2721d
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/pull-tekton-pipeline-unit-tests.json
@@ -0,0 +1 @@
+{"State":"pending","Label":"pull-tekton-pipeline-unit-tests","Desc":"Job triggered.","Target":"https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-unit-tests/1146102490727452673/"}
\ No newline at end of file
diff --git a/cmd/pullrequest-init/example/status/tide.json b/cmd/pullrequest-init/example/status/tide.json
new file mode 100644
index 00000000000..7a0d371c2bc
--- /dev/null
+++ b/cmd/pullrequest-init/example/status/tide.json
@@ -0,0 +1 @@
+{"State":"pending","Label":"tide","Desc":"Not mergeable. Needs lgtm label.","Target":"https://prow.tekton.dev/tide"}
\ No newline at end of file
diff --git a/docs/resources.md b/docs/resources.md
index 03e1b8d4355..720ddc5f177 100644
--- a/docs/resources.md
+++ b/docs/resources.md
@@ -340,6 +340,7 @@ Example file structure:
 /workspace/<resource>/comments/<comment>
 /workspace/<resource>/head.json
 /workspace/<resource>/base.json
+/workspace/<resource>/pr.json
 ```
 
 More details:
@@ -347,66 +348,19 @@ More details:
 Labels are empty files, named after the desired label string.
 
 Statuses describe pull request statuses. It is represented as a set of json
-files, structured like this:
-
-```json
-{
-    "Desc": "Job succeeded.",
-    "Label": "pull-tekton-pipeline-build-tests",
-    "State": "success",
-    "Target": "https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-build-tests/1146102490727452672/"
-}
-```
+files.
 
 References (head and base) describe Git references. They are represented as a
-set of json files, structured like this:
-
-```json
-{
-    "Ref": "master",
-    "Repo": {
-        "Branch": "master",
-        "Clone": "https://github.com/tektoncd/pipeline.git",
-        "CloneSSH": "git@github.com:tektoncd/pipeline.git",
-        "Created": "2018-08-29T18:21:55Z",
-        "FullName": "tektoncd/pipeline",
-        "ID": "146641150",
-        "Link": "https://github.com/tektoncd/pipeline",
-        "Name": "pipeline",
-        "Namespace": "tektoncd",
-        "Perm": {
-            "Admin": false,
-            "Pull": false,
-            "Push": false
-        },
-        "Private": false,
-        "Updated": "2019-11-04T18:54:10Z"
-    },
-    "Sha": "723b9a9d560bdf4dc8fc6f697d53f662d3454ac8"
-}
-```
+set of json files.
 
 Comments describe a pull request comment. They are represented as a set of json
-files, structured like this:
-
-```json
-{
-    "Author": {
-        "Avatar": "https://avatars3.githubusercontent.com/u/1844673?v=4",
-        "Created": "0001-01-01T00:00:00Z",
-        "Email": "",
-        "Link": "",
-        "Login": "wlynch",
-        "Name": "",
-        "Updated": "0001-01-01T00:00:00Z"
-    },
-    "Body": "/retest",
-    "Created": "2019-06-25T00:48:38Z",
-    "ID": 505233618,
-    "Link": "https://github.com/tektoncd/pipeline/pull/995#issuecomment-505233618",
-    "Updated": "2019-06-25T00:48:38Z"
-}
-```
+files.
+
+Other pull request information can be found in `pr.json`. This is a read-only
+resource. Users should use other subresources (labels, comments, etc)
+to interact with the PR.
+
+For an example of the output this resource provides, see [`example`](../cmd/pullrequest-init/example).
 
 To create a pull request resource using the `PipelineResource` CRD: