github.com/argoproj/argo-cd/v2@v2.10.9/docs/operator-manual/applicationset/Generators-Pull-Request.md (about)

     1  # Pull Request Generator
     2  
     3  The Pull Request generator uses the API of an SCMaaS provider (GitHub, Gitea, or Bitbucket Server) to automatically discover open pull requests within a repository. This fits well with the style of building a test environment when you create a pull request.
     4  
     5  ```yaml
     6  apiVersion: argoproj.io/v1alpha1
     7  kind: ApplicationSet
     8  metadata:
     9    name: myapps
    10  spec:
    11    goTemplate: true
    12    goTemplateOptions: ["missingkey=error"]
    13    generators:
    14    - pullRequest:
    15        # When using a Pull Request generator, the ApplicationSet controller polls every `requeueAfterSeconds` interval (defaulting to every 30 minutes) to detect changes.
    16        requeueAfterSeconds: 1800
    17        # See below for provider specific options.
    18        github:
    19          # ...
    20  ```
    21  
    22  !!! note
    23      Know the security implications of PR generators in ApplicationSets.
    24      [Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets) to avoid
    25      leaking Secrets, and [only admins may create PRs](./Security.md#templated-project-field) if the `project` field of
    26      an ApplicationSet with a PR generator is templated, to avoid granting management of out-of-bounds resources.
    27  
    28  ## GitHub
    29  
    30  Specify the repository from which to fetch the GitHub Pull requests.
    31  
    32  ```yaml
    33  apiVersion: argoproj.io/v1alpha1
    34  kind: ApplicationSet
    35  metadata:
    36    name: myapps
    37  spec:
    38    goTemplate: true
    39    goTemplateOptions: ["missingkey=error"]
    40    generators:
    41    - pullRequest:
    42        github:
    43          # The GitHub organization or user.
    44          owner: myorg
    45          # The Github repository
    46          repo: myrepository
    47          # For GitHub Enterprise (optional)
    48          api: https://git.example.com/
    49          # Reference to a Secret containing an access token. (optional)
    50          tokenRef:
    51            secretName: github-token
    52            key: token
    53          # (optional) use a GitHub App to access the API instead of a PAT.
    54          appSecretName: github-app-repo-creds
    55          # Labels is used to filter the PRs that you want to target. (optional)
    56          labels:
    57          - preview
    58        requeueAfterSeconds: 1800
    59    template:
    60    # ...
    61  ```
    62  
    63  * `owner`: Required name of the GitHub organization or user.
    64  * `repo`: Required name of the GitHub repository.
    65  * `api`: If using GitHub Enterprise, the URL to access it. (Optional)
    66  * `tokenRef`: A `Secret` name and key containing the GitHub access token to use for requests. If not specified, will make anonymous requests which have a lower rate limit and can only see public repositories. (Optional)
    67  * `labels`: Filter the PRs to those containing **all** of the labels listed. (Optional)
    68  * `appSecretName`: A `Secret` name containing a GitHub App secret in [repo-creds format][repo-creds].
    69  
    70  [repo-creds]: ../declarative-setup.md#repository-credentials
    71  
    72  ## GitLab
    73  
    74  Specify the project from which to fetch the GitLab merge requests.
    75  
    76  ```yaml
    77  apiVersion: argoproj.io/v1alpha1
    78  kind: ApplicationSet
    79  metadata:
    80    name: myapps
    81  spec:
    82    goTemplate: true
    83    goTemplateOptions: ["missingkey=error"]
    84    generators:
    85    - pullRequest:
    86        gitlab:
    87          # The GitLab project.
    88          project: myproject
    89          # For self-hosted GitLab (optional)
    90          api: https://git.example.com/
    91          # Reference to a Secret containing an access token. (optional)
    92          tokenRef:
    93            secretName: gitlab-token
    94            key: token
    95          # Labels is used to filter the MRs that you want to target. (optional)
    96          labels:
    97          - preview
    98          # MR state is used to filter MRs only with a certain state. (optional)
    99          pullRequestState: opened
   100          # If true, skips validating the SCM provider's TLS certificate - useful for self-signed certificates.
   101          insecure: false
   102        requeueAfterSeconds: 1800
   103    template:
   104    # ...
   105  ```
   106  
   107  * `project`: Required name of the GitLab project.
   108  * `api`: If using self-hosted GitLab, the URL to access it. (Optional)
   109  * `tokenRef`: A `Secret` name and key containing the GitLab access token to use for requests. If not specified, will make anonymous requests which have a lower rate limit and can only see public repositories. (Optional)
   110  * `labels`: Labels is used to filter the MRs that you want to target. (Optional)
   111  * `pullRequestState`: PullRequestState is an additional MRs filter to get only those with a certain state. Default: "" (all states)
   112  * `insecure`: By default (false) - Skip checking the validity of the SCM's certificate - useful for self-signed TLS certificates.
   113  
   114  As a preferable alternative to setting `insecure` to true, you can configure self-signed TLS certificates for Gitlab by [mounting self-signed certificate to the applicationset controller](./Generators-SCM-Provider.md#self-signed-tls-certificates).
   115  
   116  ## Gitea
   117  
   118  Specify the repository from which to fetch the Gitea Pull requests.
   119  
   120  ```yaml
   121  apiVersion: argoproj.io/v1alpha1
   122  kind: ApplicationSet
   123  metadata:
   124    name: myapps
   125  spec:
   126    goTemplate: true
   127    goTemplateOptions: ["missingkey=error"]
   128    generators:
   129    - pullRequest:
   130        gitea:
   131          # The Gitea organization or user.
   132          owner: myorg
   133          # The Gitea repository
   134          repo: myrepository
   135          # The Gitea url to use
   136          api: https://gitea.mydomain.com/
   137          # Reference to a Secret containing an access token. (optional)
   138          tokenRef:
   139            secretName: gitea-token
   140            key: token
   141          # many gitea deployments use TLS, but many are self-hosted and self-signed certificates
   142          insecure: true
   143        requeueAfterSeconds: 1800
   144    template:
   145    # ...
   146  ```
   147  
   148  * `owner`: Required name of the Gitea organization or user.
   149  * `repo`: Required name of the Gitea repository.
   150  * `api`: The url of the Gitea instance.
   151  * `tokenRef`: A `Secret` name and key containing the Gitea access token to use for requests. If not specified, will make anonymous requests which have a lower rate limit and can only see public repositories. (Optional)
   152  * `insecure`: `Allow for self-signed certificates, primarily for testing.`
   153  
   154  ## Bitbucket Server
   155  
   156  Fetch pull requests from a repo hosted on a Bitbucket Server (not the same as Bitbucket Cloud).
   157  
   158  ```yaml
   159  apiVersion: argoproj.io/v1alpha1
   160  kind: ApplicationSet
   161  metadata:
   162    name: myapps
   163  spec:
   164    goTemplate: true
   165    goTemplateOptions: ["missingkey=error"]
   166    generators:
   167    - pullRequest:
   168        bitbucketServer:
   169          project: myproject
   170          repo: myrepository
   171          # URL of the Bitbucket Server. Required.
   172          api: https://mycompany.bitbucket.org
   173          # Credentials for Basic authentication. Required for private repositories.
   174          basicAuth:
   175            # The username to authenticate with
   176            username: myuser
   177            # Reference to a Secret containing the password or personal access token.
   178            passwordRef:
   179              secretName: mypassword
   180              key: password
   181        # Labels are not supported by Bitbucket Server, so filtering by label is not possible.
   182        # Filter PRs using the source branch name. (optional)
   183        filters:
   184        - branchMatch: ".*-argocd"
   185    template:
   186    # ...
   187  ```
   188  
   189  * `project`: Required name of the Bitbucket project
   190  * `repo`: Required name of the Bitbucket repository.
   191  * `api`: Required URL to access the Bitbucket REST API. For the example above, an API request would be made to `https://mycompany.bitbucket.org/rest/api/1.0/projects/myproject/repos/myrepository/pull-requests`
   192  * `branchMatch`: Optional regexp filter which should match the source branch name. This is an alternative to labels which are not supported by Bitbucket server.
   193  
   194  If you want to access a private repository, you must also provide the credentials for Basic auth (this is the only auth supported currently):
   195  * `username`: The username to authenticate with. It only needs read access to the relevant repo.
   196  * `passwordRef`: A `Secret` name and key containing the password or personal access token to use for requests.
   197  
   198  ## Bitbucket Cloud
   199  
   200  Fetch pull requests from a repo hosted on a Bitbucket Cloud.
   201  
   202  ```yaml
   203  apiVersion: argoproj.io/v1alpha1
   204  kind: ApplicationSet
   205  metadata:
   206    name: myapps
   207  spec:
   208    goTemplate: true
   209    goTemplateOptions: ["missingkey=error"]
   210    generators:
   211      - pullRequest:
   212          bitbucket:
   213            # Workspace name where the repoistory is stored under. Required.
   214            owner: myproject
   215            # Repository slug. Required.
   216            repo: myrepository
   217            # URL of the Bitbucket Server. (optional) Will default to 'https://api.bitbucket.org/2.0'.
   218            api: https://api.bitbucket.org/2.0
   219            # Credentials for Basic authentication (App Password). Either basicAuth or bearerToken
   220            # authentication is required to access private repositories
   221            basicAuth:
   222              # The username to authenticate with
   223              username: myuser
   224              # Reference to a Secret containing the password or personal access token.
   225              passwordRef:
   226                secretName: mypassword
   227                key: password
   228            # Credentials for Bearer Token (App Token) authentication. Either basicAuth or bearerToken
   229            # authentication is required to access private repositories
   230            bearerToken:
   231              tokenRef:
   232                secretName: repotoken
   233                key: token
   234          # Labels are not supported by Bitbucket Cloud, so filtering by label is not possible.
   235          # Filter PRs using the source branch name. (optional)
   236          filters:
   237            - branchMatch: ".*-argocd"
   238    template:
   239    # ...
   240  ```
   241  
   242  - `owner`: Required name of the Bitbucket workspace
   243  - `repo`: Required name of the Bitbucket repository.
   244  - `api`: Optional URL to access the Bitbucket REST API. For the example above, an API request would be made to `https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/pullrequests`. If not set, defaults to `https://api.bitbucket.org/2.0`
   245  - `branchMatch`: Optional regexp filter which should match the source branch name. This is an alternative to labels which are not supported by Bitbucket server.
   246  
   247  If you want to access a private repository, Argo CD will need credentials to access repository in Bitbucket Cloud. You can use Bitbucket App Password (generated per user, with access to whole workspace), or Bitbucket App Token (generated per repository, with access limited to repository scope only). If both App Password and App Token are defined, App Token will be used.
   248  
   249  To use Bitbucket App Password, use `basicAuth` section.
   250  - `username`: The username to authenticate with. It only needs read access to the relevant repo.
   251  - `passwordRef`: A `Secret` name and key containing the password or personal access token to use for requests.
   252  
   253  In case of Bitbucket App Token, go with `bearerToken` section.
   254  - `tokenRef`: A `Secret` name and key containing the app token to use for requests.
   255  
   256  ## Azure DevOps
   257  
   258  Specify the organization, project and repository from which you want to fetch pull requests.
   259  
   260  ```yaml
   261  apiVersion: argoproj.io/v1alpha1
   262  kind: ApplicationSet
   263  metadata:
   264    name: myapps
   265  spec:
   266    goTemplate: true
   267    goTemplateOptions: ["missingkey=error"]
   268    generators:
   269    - pullRequest:
   270        azuredevops:
   271          # Azure DevOps org to scan. Required.
   272          organization: myorg
   273          # Azure DevOps project name to scan. Required.
   274          project: myproject
   275          # Azure DevOps repo name to scan. Required.
   276          repo: myrepository
   277          # The Azure DevOps API URL to talk to. If blank, use https://dev.azure.com/.
   278          api: https://dev.azure.com/
   279          # Reference to a Secret containing an access token. (optional)
   280          tokenRef:
   281            secretName: azure-devops-token
   282            key: token
   283          # Labels is used to filter the PRs that you want to target. (optional)
   284          labels:
   285          - preview
   286        requeueAfterSeconds: 1800
   287    template:
   288    # ...
   289  ```
   290  
   291  * `organization`: Required name of the Azure DevOps organization.
   292  * `project`: Required name of the Azure DevOps project.
   293  * `repo`: Required name of the Azure DevOps repository.
   294  * `api`: If using self-hosted Azure DevOps Repos, the URL to access it. (Optional)
   295  * `tokenRef`: A `Secret` name and key containing the Azure DevOps access token to use for requests. If not specified, will make anonymous requests which have a lower rate limit and can only see public repositories. (Optional)
   296  * `labels`: Filter the PRs to those containing **all** of the labels listed. (Optional)
   297  
   298  ## Filters
   299  
   300  Filters allow selecting which pull requests to generate for. Each filter can declare one or more conditions, all of which must pass. If multiple filters are present, any can match for a repository to be included. If no filters are specified, all pull requests will be processed.
   301  Currently, only a subset of filters is available when comparing with [SCM provider](Generators-SCM-Provider.md) filters.
   302  
   303  ```yaml
   304  apiVersion: argoproj.io/v1alpha1
   305  kind: ApplicationSet
   306  metadata:
   307    name: myapps
   308  spec:
   309    goTemplate: true
   310    goTemplateOptions: ["missingkey=error"]
   311    generators:
   312    - pullRequest:
   313        # ...
   314        # Include any pull request ending with "argocd". (optional)
   315        filters:
   316        - branchMatch: ".*-argocd"
   317    template:
   318    # ...
   319  ```
   320  
   321  * `branchMatch`: A regexp matched against source branch names.
   322  * `targetBranchMatch`: A regexp matched against target branch names.
   323  
   324  [GitHub](#github) and [GitLab](#gitlab) also support a `labels` filter.
   325  
   326  ## Template
   327  
   328  As with all generators, several keys are available for replacement in the generated application.
   329  
   330  The following is a comprehensive Helm Application example;
   331  
   332  ```yaml
   333  apiVersion: argoproj.io/v1alpha1
   334  kind: ApplicationSet
   335  metadata:
   336    name: myapps
   337  spec:
   338    goTemplate: true
   339    goTemplateOptions: ["missingkey=error"]
   340    generators:
   341    - pullRequest:
   342      # ...
   343    template:
   344      metadata:
   345        name: 'myapp-{{.branch}}-{{.number}}'
   346      spec:
   347        source:
   348          repoURL: 'https://github.com/myorg/myrepo.git'
   349          targetRevision: '{{.head_sha}}'
   350          path: kubernetes/
   351          helm:
   352            parameters:
   353            - name: "image.tag"
   354              value: "pull-{{.head_sha}}"
   355        project: "my-project"
   356        destination:
   357          server: https://kubernetes.default.svc
   358          namespace: default
   359  ```
   360  
   361  And, here is a robust Kustomize example;
   362  
   363  ```yaml
   364  apiVersion: argoproj.io/v1alpha1
   365  kind: ApplicationSet
   366  metadata:
   367    name: myapps
   368  spec:
   369    goTemplate: true
   370    goTemplateOptions: ["missingkey=error"]
   371    generators:
   372    - pullRequest:
   373      # ...
   374    template:
   375      metadata:
   376        name: 'myapp-{{.branch}}-{{.number}}'
   377      spec:
   378        source:
   379          repoURL: 'https://github.com/myorg/myrepo.git'
   380          targetRevision: '{{.head_sha}}'
   381          path: kubernetes/
   382          kustomize:
   383            nameSuffix: '{{.branch}}'
   384            commonLabels:
   385              app.kubernetes.io/instance: '{{.branch}}-{{.number}}'
   386            images:
   387            - 'ghcr.io/myorg/myrepo:{{.head_sha}}'
   388        project: "my-project"
   389        destination:
   390          server: https://kubernetes.default.svc
   391          namespace: default
   392  ```
   393  
   394  * `number`: The ID number of the pull request.
   395  * `branch`: The name of the branch of the pull request head.
   396  * `branch_slug`: The branch name will be cleaned to be conform to the DNS label standard as defined in [RFC 1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names), and truncated to 50 characters to give room to append/suffix-ing it with 13 more characters.
   397  * `target_branch`: The name of the target branch of the pull request.
   398  * `target_branch_slug`: The target branch name will be cleaned to be conform to the DNS label standard as defined in [RFC 1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names), and truncated to 50 characters to give room to append/suffix-ing it with 13 more characters.
   399  * `head_sha`: This is the SHA of the head of the pull request.
   400  * `head_short_sha`: This is the short SHA of the head of the pull request (8 characters long or the length of the head SHA if it's shorter).
   401  * `head_short_sha_7`: This is the short SHA of the head of the pull request (7 characters long or the length of the head SHA if it's shorter).
   402  * `labels`: The array of pull request labels. (Supported only for Go Template ApplicationSet manifests.)
   403  
   404  ## Webhook Configuration
   405  
   406  When using a Pull Request generator, the ApplicationSet controller polls every `requeueAfterSeconds` interval (defaulting to every 30 minutes) to detect changes. To eliminate this delay from polling, the ApplicationSet webhook server can be configured to receive webhook events, which will trigger Application generation by the Pull Request generator.
   407  
   408  The configuration is almost the same as the one described [in the Git generator](Generators-Git.md), but there is one difference: if you want to use the Pull Request Generator as well, additionally configure the following settings.
   409  
   410  !!! note
   411      The ApplicationSet controller webhook does not use the same webhook as the API server as defined [here](../webhook.md). ApplicationSet exposes a webhook server as a service of type ClusterIP. An ApplicationSet specific Ingress resource needs to be created to expose this service to the webhook source.
   412  
   413  ### Github webhook configuration
   414  
   415  In section 1, _"Create the webhook in the Git provider"_, add an event so that a webhook request will be sent when a pull request is created, closed, or label changed.
   416  
   417  Add Webhook URL with uri `/api/webhook` and select content-type as json
   418  ![Add Webhook URL](../../assets/applicationset/webhook-config-pullrequest-generator.png "Add Webhook URL")
   419  
   420  Select `Let me select individual events` and enable the checkbox for `Pull requests`.
   421  
   422  ![Add Webhook](../../assets/applicationset/webhook-config-pull-request.png "Add Webhook Pull Request")
   423  
   424  The Pull Request Generator will requeue when the next action occurs.
   425  
   426  - `opened`
   427  - `closed`
   428  - `reopened`
   429  - `labeled`
   430  - `unlabeled`
   431  - `synchronized`
   432  
   433  For more information about each event, please refer to the [official documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads).
   434  
   435  ### Gitlab webhook configuration
   436  
   437  Enable checkbox for "Merge request events" in triggers list.
   438  
   439  ![Add Gitlab Webhook](../../assets/applicationset/webhook-config-merge-request-gitlab.png "Add Gitlab Merge request Webhook")
   440  
   441  The Pull Request Generator will requeue when the next action occurs.
   442  
   443  - `open`
   444  - `close`
   445  - `reopen`
   446  - `update`
   447  - `merge`
   448  
   449  For more information about each event, please refer to the [official documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events).
   450  
   451  ## Lifecycle
   452  
   453  An Application will be generated when a Pull Request is discovered when the configured criteria is met - i.e. for GitHub when a Pull Request matches the specified `labels` and/or `pullRequestState`. Application will be removed when a Pull Request no longer meets the specified criteria.