github.com/abayer/test-infra@v0.0.5/prow/cmd/tide/README.md (about) 1 # Tide 2 3 Tide is a [Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md) 4 component for managing a pool of PRs that match a given set of criteria. 5 It will automatically retest and merge PRs in the pool if they pass tests 6 against the latest base branch commit. 7 8 Configuration of Tide is located under 9 [prow/config.yaml](https://github.com/kubernetes/test-infra/blob/master/prow/config.yaml) 10 file. It consists of two parts: 11 12 * **Specification of PR pools/criteria**: 13 A set of all PRs Tide keeps track of. 14 The PRs are periodically checked if they are ready to be merged. 15 Configured under `tide` key of the configuration file. 16 17 * **Specification of PR tests**: 18 A set of jobs that are run over each PR before it gets merged. 19 No job is required to be provided in which case it's enough if a PR has all 20 relevant labels set. If a set of jobs is specified, 21 all must succeed (unless a job is configured with `skip_report: true`). 22 Configured under `presubmits` key of the configuration file. 23 24 ## PR pools 25 26 The set of criteria is specified through the following collection of items: 27 28 ```yaml 29 tide: 30 queries: // List of queries 31 - repo: // org/repo 32 labels: // List of must have labels 33 missingLabels: // List of can't have labels 34 excludedBranches: // Ignore branches 35 includedBranches: // Include-only branches 36 reviewApprovedRequired: // Github Review approval required 37 sync_period: // Sync jobs period 38 status_update_period: // PR status update period 39 merge_method: // Set to squash, rebase or just merge PR 40 target_url: // URL linked to from the details link on the Github status context 41 pr_status_base_url: // PR status page 42 max_goroutines: // Per-pool parallelism 43 ``` 44 45 Depending on your criteria, some of the items may by omitted. 46 47 See [https://godoc.org/github.com/kubernetes/test-infra/prow/config#Tide](https://godoc.org/github.com/kubernetes/test-infra/prow/config#Tide) for more detail. 48 49 ### General configuration 50 51 The following configuration fields are available: 52 53 * `sync_period`: The field specifies how often Tide will sync jobs with Github. Defaults to 1m. 54 * `status_update_period`: The field specifies how often Tide will update Github status contexts. 55 Defaults to the value of `sync_period`. 56 * `queries`: List of queries (described below). 57 * `merge_method`: A key/value pair of an `org/repo` as the key and merge method to override 58 the default method of merge as value. Valid options are `squash`, `rebase`, and `merge`. 59 Defaults to `merge`. 60 * `target_url`: URL for tide status contexts. 61 * `pr_status_base_url`: The base URL for the PR status page. If specified, this URL is used to construct 62 a link that will be used for the tide status context. It is mutually exclusive with the `target_url` field. 63 * `max_goroutines`: The maximum number of goroutines spawned inside the component to 64 handle org/repo:branch pools. Defaults to 20. Needs to be a positive number. 65 66 ### Queries 67 68 The `queries` field specifies a list of queries. 69 Each query corresponds to a set of **open** PRs as candidates for merging. 70 It can consist of the following dictionary of fields: 71 72 * `repos`: List of queried repositories. 73 * `labels`: List of labels any given PR must posses. 74 * `missingLabels`: List of labels any given PR must not posses. 75 * `excludedBranches`: List of branches that get excluded when querying the `repos`. 76 * `includedBranches`: List of branches that get included when querying the `repos`. 77 * `reviewApprovedRequired`: If set, each PR in the query must have at 78 least one [approved github pull request 79 review](https://help.github.com/articles/about-pull-request-reviews/) 80 present for merge. Defaults to `false`. 81 82 Under the hood, a query constructed from the fields follows rules described in 83 https://help.github.com/articles/searching-issues-and-pull-requests/. 84 Therefore every query is just a structured definition of a standard GitHub 85 search query which can be used to list mergeable PRs. 86 The field to search token correspondence is based on the following mapping: 87 88 * `repos` -> `repo:org/repo` 89 * `labels` -> `label:lgtm` 90 * `missingLabels` -> `-label:do-not-merge` 91 * `excludedBranches` -> `-branch:dev` 92 * `includedBranches` -> `branch:master` 93 * `reviewApprovedRequired` -> `review:approved` 94 95 **Important**: Each query must return a different set of PRs. No two queries are allowed to contain the same PR. 96 97 Every PR that need to be rebased is filtered from the pool before processing 98 99 100 ### Context Policy Options 101 102 A PR will be merged when all checks are passing. With this option you can customize 103 which contexts are required or optional. 104 105 By default, required and optional contexts will be derived from Prow Job Config. 106 This allows to find if required checks are missing from the github combined status. 107 108 If `branch-protection` config is defined, it can be used to know which test needs 109 be passing to merge a PR. 110 111 When branch protection is not used, required and optional contexts can be defined 112 globally, or at the org, repo or branch level. 113 114 If we want to skip unknown checks (ie checks that are not defined in Prow Config), we can set 115 `skip-unknown-contexts` to true. This option can be set globally or per org, 116 repo and branch. 117 118 **Important**: If this option is not set and no prow jobs are defined tide will trust the github 119 combined status and will assume that all checks are required (except tide). 120 121 122 ### Example 123 124 ```yaml 125 tide: 126 merge_method: 127 kubeflow/community: squash 128 129 target_url: https://prow.k8s.io/tide.html 130 131 queries: 132 - repos: 133 - kubeflow/community 134 - kubeflow/examples 135 labels: 136 - lgtm 137 - approved 138 missingLabels: 139 - do-not-merge 140 - do-not-merge/hold 141 - do-not-merge/work-in-progress 142 - needs-ok-to-test 143 - needs-rebase 144 145 context_options: 146 # Use branch protection options to define required and optional contexts 147 from-branch-protection: true 148 # Treat unknown contexts as optional 149 skip-unknown-contexts: true 150 orgs: 151 org: 152 required-contexts: 153 - "check-required-for-all-repos" 154 repos: 155 repo: 156 required-contexts: 157 - "check-required-for-all-branches" 158 branches: 159 branch: 160 from-branch-protection: false 161 required-contexts: 162 - "required_test" 163 optional-contexts: 164 - "optional_test" 165 166 ``` 167 168 **Explanation**: The component starts periodically querying all PRs in `github.com/kubeflow/community` and 169 `github.com/kubeflow/examples` repositories that have `lgtm` and `approved` labels set 170 and do not have `do-not-merge`, `do-not-merge/hold`, `do-not-merge/work-in-progress`, `needs-ok-to-test` and `needs-rebase` labels set. 171 All PRs that conform to the criteria are processed and merged. 172 The processing itself can include running jobs (e.g. tests) to verify the PRs are good to go. 173 At the same time all commits in PRs from `github.com/kubeflow/community` repository are squashed before merging. 174 175 ## Presubmits 176 177 Before a PR is merged, Tide ensures that all jobs configured as required (with `skip_report: false`) in the `presubmits` part of the `config.yaml` file 178 are passing against the latest base branch commit, rerunning the jobs if necessary. 179 180 Semantic of individual fields of the `presubmits` is described in [prow/README.md#how-to-add-new-jobs](https://github.com/kubernetes/test-infra/blob/master/prow/README.md#how-to-add-new-jobs).