github.com/munnerz/test-infra@v0.0.0-20190108210205-ce3d181dc989/prow/cmd/tide/config.md (about)

     1  # Configuring Tide
     2  
     3  Configuration of Tide is located under the [prow/config.yaml](/prow/config.yaml) file. All configuration for merge behavior and criteria belongs in the `tide` yaml struct, but it may be necessary to also configure presubmits for Tide to run against PRs (see ['Configuring Presubmit Jobs'](#configuring-presubmit-jobs) below).
     4  
     5  This document will describe the fields of the `tide` configuration and how to populate them, but you can also check out the [GoDocs](https://godoc.org/github.com/kubernetes/test-infra/prow/config#Tide) for the most up to date configuration specification.
     6  
     7  To deploy Tide for your organization or repository, please see [how to get started with prow](/prow/getting_started.md).
     8  
     9  ### General configuration
    10  
    11  The following configuration fields are available:
    12  
    13  * `sync_period`: The field specifies how often Tide will sync jobs with GitHub. Defaults to 1m.
    14  * `status_update_period`: The field specifies how often Tide will update GitHub status contexts.
    15     Defaults to the value of `sync_period`.
    16  * `queries`: List of queries (described below).
    17  * `merge_method`: A key/value pair of an `org/repo` as the key and merge method to override
    18     the default method of merge as value. Valid options are `squash`, `rebase`, and `merge`.
    19     Defaults to `merge`.
    20  * `target_url`: URL for tide status contexts.
    21  * `pr_status_base_url`: The base URL for the PR status page. If specified, this URL is used to construct
    22     a link that will be used for the tide status context. It is mutually exclusive with the `target_url` field.
    23  * `max_goroutines`: The maximum number of goroutines spawned inside the component to
    24     handle org/repo:branch pools. Defaults to 20. Needs to be a positive number.
    25  
    26  ### Queries
    27  
    28  The `queries` field specifies a list of queries.
    29  Each query corresponds to a set of **open** PRs as candidates for merging.
    30  It can consist of the following dictionary of fields:
    31  
    32  * `orgs`: List of queried organizations.
    33  * `repos`: List of queried repositories.
    34  * `labels`: List of labels any given PR must posses.
    35  * `missingLabels`: List of labels any given PR must not posses.
    36  * `excludedBranches`: List of branches that get excluded when querying the `repos`.
    37  * `includedBranches`: List of branches that get included when querying the `repos`.
    38  * `reviewApprovedRequired`: If set, each PR in the query must have at
    39    least one [approved GitHub pull request
    40    review](https://help.github.com/articles/about-pull-request-reviews/)
    41    present for merge. Defaults to `false`.
    42  
    43  Under the hood, a query constructed from the fields follows rules described in
    44  https://help.github.com/articles/searching-issues-and-pull-requests/.
    45  Therefore every query is just a structured definition of a standard GitHub
    46  search query which can be used to list mergeable PRs.
    47  The field to search token correspondence is based on the following mapping:
    48  
    49  * `orgs` -> `org:kubernetes`
    50  * `repos` -> `repo:kubernetes/test-infra`
    51  * `labels` -> `label:lgtm`
    52  * `missingLabels` -> `-label:do-not-merge`
    53  * `excludedBranches` -> `-branch:dev`
    54  * `includedBranches` -> `branch:master`
    55  * `reviewApprovedRequired` -> `review:approved`
    56  
    57  **Important**: Each query must return a different set of PRs. No two queries are allowed to contain the same PR.
    58  
    59  Every PR that needs to be rebased or is failing required statuses is filtered from the pool before processing
    60  
    61  
    62  ### Context Policy Options
    63  
    64  A PR will be merged when all checks are passing. With this option you can customize
    65  which contexts are required or optional.
    66  
    67  By default, required and optional contexts will be derived from Prow Job Config.
    68  This allows to find if required checks are missing from the GitHub combined status.
    69  
    70  If `branch-protection` config is defined, it can be used to know which test needs
    71  be passing to merge a PR.
    72  
    73  When branch protection is not used, required and optional contexts can be defined
    74  globally, or at the org, repo or branch level.
    75  
    76  If we want to skip unknown checks (ie checks that are not defined in Prow Config), we can set
    77  `skip-unknown-contexts` to true. This option can be set globally or per org,
    78  repo and branch.
    79  
    80  **Important**: If this option is not set and no prow jobs are defined tide will trust the GitHub
    81  combined status and will assume that all checks are required (except for it's own `tide` status).
    82  
    83  
    84  ### Example
    85  
    86  ```yaml
    87  tide:
    88    merge_method:
    89      kubeflow/community: squash
    90  
    91    target_url: https://prow.k8s.io/tide.html
    92  
    93    queries:
    94    - repos:
    95      - kubeflow/community
    96      - kubeflow/examples
    97      labels:
    98      - lgtm
    99      - approved
   100      missingLabels:
   101      - do-not-merge
   102      - do-not-merge/hold
   103      - do-not-merge/work-in-progress
   104      - needs-ok-to-test
   105      - needs-rebase
   106  
   107    context_options:
   108      # Use branch protection options to define required and optional contexts
   109      from-branch-protection: true
   110      # Treat unknown contexts as optional
   111      skip-unknown-contexts: true
   112      orgs:
   113        org:
   114          required-contexts:
   115          - "check-required-for-all-repos"
   116          repos:
   117            repo:
   118              required-contexts:
   119               - "check-required-for-all-branches"
   120              branches:
   121                branch:
   122                  from-branch-protection: false
   123                  required-contexts:
   124                  - "required_test"
   125                  optional-contexts:
   126                  - "optional_test"
   127  ```
   128  
   129  **Explanation**: The component starts periodically querying all PRs in `github.com/kubeflow/community` and
   130  `github.com/kubeflow/examples` repositories that have `lgtm` and `approved` labels set
   131  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.
   132  All PRs that conform to the criteria are processed and merged.
   133  The processing itself can include running jobs (e.g. tests) to verify the PRs are good to go.
   134  All commits in PRs from `github.com/kubeflow/community` repository are squashed before merging.
   135  
   136  # Configuring Presubmit Jobs
   137  
   138  Before a PR is merged, Tide ensures that all jobs configured as required in the `presubmits` part of the `config.yaml` file are passing against the latest base branch commit, rerunning the jobs if necessary. **No job is required to be configured** in which case it's enough if a PR meets all GitHub search criteria.
   139  
   140  Semantic of individual fields of the `presubmits` is described in [prow/README.md#how-to-add-new-jobs](/prow/README.md#how-to-add-new-jobs).