{"action":"created","comment":{"url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/comments/186609973","pull_request_review_id":118219744,"id":186609973,"diff_hunk":"@@ -0,0 +1,161 @@\n+---\n+title: .taskcluster.yml version 1\n+order: 20\n+---\n+\n+Your main interface to Taskcluster-Github is via `.taskcluster.yml` in the root\n+of your project. This is a YAML file that specifies the tasks to run and when.\n+\n+The format of the file is:\n+\n+```yaml\n+version: 1\n+policy:\n+  pullRequests: ..\n+tasks:\n+  - (task definition)\n+  - ...\n+```\n+\n+The core of Taskcluster-Github's operation is this: when an event occurs on Github, such as a push or a pull request, it loads `.taskcluster.yml` from the commit specified in the event, renders it with JSON-e, and then calls `Queue.createTask` for each of the specified tasks.\n+\n+# Policies\n+\n+The `policy` property defines policies for what is allowed on the repository. Policies are always read from the default branch (generally `master`) of the repository. This prevents a malicious contributor from changing the policy applied to a pull request in the pull request itself.\n+\n+Policies are not rendered as a part of a task.\n+\n+##### Pull Requests\n+\n+Most projects prefer to run tasks for each pull request, so that the review process can take into account the task results. But if your project requires some secret data or uses some expensive service to test a pull request, then you probably do not want to run tasks for pull requests written by arbitrary contributors, but would still like to run tasks for PRs by project collaborators.\n+\n+The `pullRequests` policy controls this behavior:\n+\n+* `public` -- tasks are created for all pull requests.\n+\n+* `collaborators` (the default) -- tasks are created if the user who made the pull request is a collaborator on the repository.\n+Github [defines\n+  collaborators](https://developer.github.com/v3/repos/collaborators/#list-collaborators) as \"outside collaborators, organization members with access through team memberships, organization members with access through default organization permissions, and organization owners.\"\n+\n+Example:\n+```yaml\n+policy:\n+  pullRequests: public\n+tasks: ...\n+```\n+\n+# JSON-e Rendering\n+\n+The tasks defined in the YAML file are rendered using\n+[JSON-e](https://github.com/taskcluster/json-e). You can view it as a `template`. The following `context` variables are provided:\n+\n+* `tasks_for` - defines the type of event, one of `github-push`,\n+  `github-pull-request` or `github-release`.\n+\n+* `event` - the raw Github event; see\n+  * [PushEvent](https://developer.github.com/v3/activity/events/types/#pushevent)\n+  * [PullRequestEvent](https://developer.github.com/v3/activity/events/types/#pullrequestevent)\n+  * [ReleaseEvent](https://developer.github.com/v3/activity/events/types/#releaseevent)\n+\n+* `now` - the current time, as a string; this is useful for reproducible `$fromNow` invocations (see JSON-e documentation)\n+\n+* `as_slugid` - a function which, given a label, will generate a slugid. Multiple calls with the same label for the same event will generate the same slugid, but different slugids in different events.  Use this to generate taskIds, etc.\n+\n+## Task definition\n+ \n+### Github Events\n+\n+You can put a task definition inside an `${if}, then` statement so that it will only run for specific Github events:","path":"docs/taskcluster-yml-v1.md","position":68,"original_position":68,"commit_id":"bd4864f8a1c1cbe8a147df6e67de67a28005fed7","original_commit_id":"bd4864f8a1c1cbe8a147df6e67de67a28005fed7","user":{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false},"body":"`{$if, then}` (brace before $)","created_at":"2018-05-08T03:43:35Z","updated_at":"2018-05-08T03:46:18Z","html_url":"https://github.com/taskcluster/taskcluster-github/pull/206#discussion_r186609973","pull_request_url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/comments/186609973"},"html":{"href":"https://github.com/taskcluster/taskcluster-github/pull/206#discussion_r186609973"},"pull_request":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206"}}},"pull_request":{"url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206","id":131851081,"html_url":"https://github.com/taskcluster/taskcluster-github/pull/206","diff_url":"https://github.com/taskcluster/taskcluster-github/pull/206.diff","patch_url":"https://github.com/taskcluster/taskcluster-github/pull/206.patch","issue_url":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/206","number":206,"state":"open","locked":false,"title":"[100% review] Document .taskcluster.yml version 1","user":{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false},"body":"Thoughts on this documentation?\r\n\r\nAs written, I feel like it's kind of dumping users in the deep end: write a YAML file that takes this obscure Github JSON object and finagles it into this obscure Taskcluster Task JSON object.  Good luck!\r\n\r\nBut, I don't like what happened with the env vars, where they seemed to proliferate and weren't especially well-defined, and meant different things for different events.\r\n\r\nAny thoughts on an elegant way to make users' lives easier without just creating an endless pit of utility functions?","created_at":"2017-07-21T20:19:33Z","updated_at":"2018-05-08T03:46:18Z","closed_at":null,"merged_at":null,"merge_commit_sha":"d3de08725ebf65e966b7c8aa3a16ce8bc5b33faf","assignee":{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false},"assignees":[{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false}],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206/commits","review_comments_url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206/comments","review_comment_url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/comments{/number}","comments_url":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/206/comments","statuses_url":"https://api.github.com/repos/taskcluster/taskcluster-github/statuses/bd4864f8a1c1cbe8a147df6e67de67a28005fed7","head":{"label":"djmitche:use-json-e","ref":"use-json-e","sha":"bd4864f8a1c1cbe8a147df6e67de67a28005fed7","user":{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false},"repo":{"id":45416018,"name":"taskcluster-github","full_name":"djmitche/taskcluster-github","owner":{"login":"djmitche","id":28673,"avatar_url":"https://avatars3.githubusercontent.com/u/28673?v=4","gravatar_id":"","url":"https://api.github.com/users/djmitche","html_url":"https://github.com/djmitche","followers_url":"https://api.github.com/users/djmitche/followers","following_url":"https://api.github.com/users/djmitche/following{/other_user}","gists_url":"https://api.github.com/users/djmitche/gists{/gist_id}","starred_url":"https://api.github.com/users/djmitche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/djmitche/subscriptions","organizations_url":"https://api.github.com/users/djmitche/orgs","repos_url":"https://api.github.com/users/djmitche/repos","events_url":"https://api.github.com/users/djmitche/events{/privacy}","received_events_url":"https://api.github.com/users/djmitche/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/djmitche/taskcluster-github","description":"Services for integrating TaskCluster with GitHub.","fork":true,"url":"https://api.github.com/repos/djmitche/taskcluster-github","forks_url":"https://api.github.com/repos/djmitche/taskcluster-github/forks","keys_url":"https://api.github.com/repos/djmitche/taskcluster-github/keys{/key_id}","collaborators_url":"https://api.github.com/repos/djmitche/taskcluster-github/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/djmitche/taskcluster-github/teams","hooks_url":"https://api.github.com/repos/djmitche/taskcluster-github/hooks","issue_events_url":"https://api.github.com/repos/djmitche/taskcluster-github/issues/events{/number}","events_url":"https://api.github.com/repos/djmitche/taskcluster-github/events","assignees_url":"https://api.github.com/repos/djmitche/taskcluster-github/assignees{/user}","branches_url":"https://api.github.com/repos/djmitche/taskcluster-github/branches{/branch}","tags_url":"https://api.github.com/repos/djmitche/taskcluster-github/tags","blobs_url":"https://api.github.com/repos/djmitche/taskcluster-github/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/djmitche/taskcluster-github/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/djmitche/taskcluster-github/git/refs{/sha}","trees_url":"https://api.github.com/repos/djmitche/taskcluster-github/git/trees{/sha}","statuses_url":"https://api.github.com/repos/djmitche/taskcluster-github/statuses/{sha}","languages_url":"https://api.github.com/repos/djmitche/taskcluster-github/languages","stargazers_url":"https://api.github.com/repos/djmitche/taskcluster-github/stargazers","contributors_url":"https://api.github.com/repos/djmitche/taskcluster-github/contributors","subscribers_url":"https://api.github.com/repos/djmitche/taskcluster-github/subscribers","subscription_url":"https://api.github.com/repos/djmitche/taskcluster-github/subscription","commits_url":"https://api.github.com/repos/djmitche/taskcluster-github/commits{/sha}","git_commits_url":"https://api.github.com/repos/djmitche/taskcluster-github/git/commits{/sha}","comments_url":"https://api.github.com/repos/djmitche/taskcluster-github/comments{/number}","issue_comment_url":"https://api.github.com/repos/djmitche/taskcluster-github/issues/comments{/number}","contents_url":"https://api.github.com/repos/djmitche/taskcluster-github/contents/{+path}","compare_url":"https://api.github.com/repos/djmitche/taskcluster-github/compare/{base}...{head}","merges_url":"https://api.github.com/repos/djmitche/taskcluster-github/merges","archive_url":"https://api.github.com/repos/djmitche/taskcluster-github/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/djmitche/taskcluster-github/downloads","issues_url":"https://api.github.com/repos/djmitche/taskcluster-github/issues{/number}","pulls_url":"https://api.github.com/repos/djmitche/taskcluster-github/pulls{/number}","milestones_url":"https://api.github.com/repos/djmitche/taskcluster-github/milestones{/number}","notifications_url":"https://api.github.com/repos/djmitche/taskcluster-github/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/djmitche/taskcluster-github/labels{/name}","releases_url":"https://api.github.com/repos/djmitche/taskcluster-github/releases{/id}","deployments_url":"https://api.github.com/repos/djmitche/taskcluster-github/deployments","created_at":"2015-11-02T19:13:57Z","updated_at":"2017-02-10T19:49:48Z","pushed_at":"2018-05-08T03:29:47Z","git_url":"git://github.com/djmitche/taskcluster-github.git","ssh_url":"git@github.com:djmitche/taskcluster-github.git","clone_url":"https://github.com/djmitche/taskcluster-github.git","svn_url":"https://github.com/djmitche/taskcluster-github","homepage":null,"size":845,"stargazers_count":0,"watchers_count":0,"language":"JavaScript","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"mpl-2.0","name":"Mozilla Public License 2.0","spdx_id":"MPL-2.0","url":"https://api.github.com/licenses/mpl-2.0"},"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"taskcluster:master","ref":"master","sha":"282f934a418049a5df08b13cf1d955677235db04","user":{"login":"taskcluster","id":6257436,"avatar_url":"https://avatars2.githubusercontent.com/u/6257436?v=4","gravatar_id":"","url":"https://api.github.com/users/taskcluster","html_url":"https://github.com/taskcluster","followers_url":"https://api.github.com/users/taskcluster/followers","following_url":"https://api.github.com/users/taskcluster/following{/other_user}","gists_url":"https://api.github.com/users/taskcluster/gists{/gist_id}","starred_url":"https://api.github.com/users/taskcluster/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/taskcluster/subscriptions","organizations_url":"https://api.github.com/users/taskcluster/orgs","repos_url":"https://api.github.com/users/taskcluster/repos","events_url":"https://api.github.com/users/taskcluster/events{/privacy}","received_events_url":"https://api.github.com/users/taskcluster/received_events","type":"Organization","site_admin":false},"repo":{"id":39215345,"name":"taskcluster-github","full_name":"taskcluster/taskcluster-github","owner":{"login":"taskcluster","id":6257436,"avatar_url":"https://avatars2.githubusercontent.com/u/6257436?v=4","gravatar_id":"","url":"https://api.github.com/users/taskcluster","html_url":"https://github.com/taskcluster","followers_url":"https://api.github.com/users/taskcluster/followers","following_url":"https://api.github.com/users/taskcluster/following{/other_user}","gists_url":"https://api.github.com/users/taskcluster/gists{/gist_id}","starred_url":"https://api.github.com/users/taskcluster/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/taskcluster/subscriptions","organizations_url":"https://api.github.com/users/taskcluster/orgs","repos_url":"https://api.github.com/users/taskcluster/repos","events_url":"https://api.github.com/users/taskcluster/events{/privacy}","received_events_url":"https://api.github.com/users/taskcluster/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/taskcluster/taskcluster-github","description":"Integrate Taskcluster with Github.","fork":false,"url":"https://api.github.com/repos/taskcluster/taskcluster-github","forks_url":"https://api.github.com/repos/taskcluster/taskcluster-github/forks","keys_url":"https://api.github.com/repos/taskcluster/taskcluster-github/keys{/key_id}","collaborators_url":"https://api.github.com/repos/taskcluster/taskcluster-github/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/taskcluster/taskcluster-github/teams","hooks_url":"https://api.github.com/repos/taskcluster/taskcluster-github/hooks","issue_events_url":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/events{/number}","events_url":"https://api.github.com/repos/taskcluster/taskcluster-github/events","assignees_url":"https://api.github.com/repos/taskcluster/taskcluster-github/assignees{/user}","branches_url":"https://api.github.com/repos/taskcluster/taskcluster-github/branches{/branch}","tags_url":"https://api.github.com/repos/taskcluster/taskcluster-github/tags","blobs_url":"https://api.github.com/repos/taskcluster/taskcluster-github/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/taskcluster/taskcluster-github/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/taskcluster/taskcluster-github/git/refs{/sha}","trees_url":"https://api.github.com/repos/taskcluster/taskcluster-github/git/trees{/sha}","statuses_url":"https://api.github.com/repos/taskcluster/taskcluster-github/statuses/{sha}","languages_url":"https://api.github.com/repos/taskcluster/taskcluster-github/languages","stargazers_url":"https://api.github.com/repos/taskcluster/taskcluster-github/stargazers","contributors_url":"https://api.github.com/repos/taskcluster/taskcluster-github/contributors","subscribers_url":"https://api.github.com/repos/taskcluster/taskcluster-github/subscribers","subscription_url":"https://api.github.com/repos/taskcluster/taskcluster-github/subscription","commits_url":"https://api.github.com/repos/taskcluster/taskcluster-github/commits{/sha}","git_commits_url":"https://api.github.com/repos/taskcluster/taskcluster-github/git/commits{/sha}","comments_url":"https://api.github.com/repos/taskcluster/taskcluster-github/comments{/number}","issue_comment_url":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/comments{/number}","contents_url":"https://api.github.com/repos/taskcluster/taskcluster-github/contents/{+path}","compare_url":"https://api.github.com/repos/taskcluster/taskcluster-github/compare/{base}...{head}","merges_url":"https://api.github.com/repos/taskcluster/taskcluster-github/merges","archive_url":"https://api.github.com/repos/taskcluster/taskcluster-github/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/taskcluster/taskcluster-github/downloads","issues_url":"https://api.github.com/repos/taskcluster/taskcluster-github/issues{/number}","pulls_url":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls{/number}","milestones_url":"https://api.github.com/repos/taskcluster/taskcluster-github/milestones{/number}","notifications_url":"https://api.github.com/repos/taskcluster/taskcluster-github/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/taskcluster/taskcluster-github/labels{/name}","releases_url":"https://api.github.com/repos/taskcluster/taskcluster-github/releases{/id}","deployments_url":"https://api.github.com/repos/taskcluster/taskcluster-github/deployments","created_at":"2015-07-16T19:10:45Z","updated_at":"2018-05-02T14:22:06Z","pushed_at":"2018-05-08T03:29:48Z","git_url":"git://github.com/taskcluster/taskcluster-github.git","ssh_url":"git@github.com:taskcluster/taskcluster-github.git","clone_url":"https://github.com/taskcluster/taskcluster-github.git","svn_url":"https://github.com/taskcluster/taskcluster-github","homepage":"https://github.com/apps/taskcluster","size":851,"stargazers_count":11,"watchers_count":11,"language":"JavaScript","has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":24,"mirror_url":null,"archived":false,"open_issues_count":13,"license":{"key":"mpl-2.0","name":"Mozilla Public License 2.0","spdx_id":"MPL-2.0","url":"https://api.github.com/licenses/mpl-2.0"},"forks":24,"open_issues":13,"watchers":11,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206"},"html":{"href":"https://github.com/taskcluster/taskcluster-github/pull/206"},"issue":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/206"},"comments":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/issues/206/comments"},"review_comments":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206/comments"},"review_comment":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/pulls/206/commits"},"statuses":{"href":"https://api.github.com/repos/taskcluster/taskcluster-github/statuses/bd4864f8a1c1cbe8a147df6e67de67a28005fed7"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"djmitche"}}