argocd kind ApplicationSet apiVersion argoproj io v1alpha1 Pull Request Generator spec metadata yaml 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 name myapps

Answer:
# Pull Request Generator

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.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      # When using a Pull Request generator, the ApplicationSet controller polls every `requeueAfterSeconds` interval (defaulting to every 30 minutes) to detect changes.
      requeueAfterSeconds: 1800
      # See below for provider specific options.
      github:
        # ...
```

!!! note
    Know the security implications of PR generators in ApplicationSets.
    [Only admins may create ApplicationSets](./Security.md#only-admins-may-createupdatedelete-applicationsets) to avoid
    leaking Secrets, and [only admins may create PRs](./Security.md#templated-project-field) if the `project` field of
    an ApplicationSet with a PR generator is templated, to avoid granting management of out-of-bounds resources.

## GitHub

Specify the repository from which to fetch the GitHub Pull requests.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      github:
        # The GitHub organization or user.
        owner: myorg
        # The Github repository
        repo: myrepository
        # For GitHub Enterprise (optional)
        api: https://git.example.com/
        # Reference to a Secret containing an access token. (optional)
        tokenRef:
          secretName: github-token
          key: token
        # (optional) use a GitHub App to access the API instead of a PAT.
        appSecretName: github-app-repo-creds
        # Labels is used to filter the PRs that you want to target. (optional)
        labels:
        - preview
      requeueAfterSeconds: 1800
  template:
  # ...
```

* `owner`: Required name of the GitHub organization or user.
* `repo`: Required name of the GitHub repository.
* `api`: If using GitHub Enterprise, the URL to access it. (Optional)
* `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)
* `labels`: Filter the PRs to those containing **all** of the labels listed. (Optional)
* `appSecretName`: A `Secret` name containing a GitHub App secret in [repo-creds format][repo-creds].

[repo-creds]: ../declarative-setup.md#repository-credentials

## GitLab

Specify the project from which to fetch the GitLab merge requests.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      gitlab:
        # The GitLab project ID.
        project: "12341234"
        # For self-hosted GitLab (optional)
        api: https://git.example.com/
        # Reference to a Secret containing an access token. (optional)
        tokenRef:
          secretName: gitlab-token
          key: token
        # Labels is used to filter the MRs that you want to target. (optional)
        labels:
        - preview
        # MR state is used to filter MRs only with a certain state. (optional)
        pullRequestState: opened
        # If true, skips validating the SCM provider's TLS certificate - useful for self-signed certificates.
        insecure: false
        # Reference to a ConfigMap containing trusted CA certs - useful for self-signed certificates. (optional)
        caRef:
          configMapName: argocd-tls-certs-cm
          key: gitlab-ca
      requeueAfterSeconds: 1800
  template:
  # ...
```

* `project`: Required project ID of the GitLab project.
* `api`: If using self-hosted GitLab, the URL to access it. (Optional)
* `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)
* `labels`: Labels is used to filter the MRs that you want to target. (Optional)
* `pullRequestState`: PullRequestState is an additional MRs filter to get only those with a certain state. Default: "" (all states)
* `insecure`: By default (false) - Skip checking the validity of the SCM's certificate - useful for self-signed TLS certificates.
* `caRef`: Optional `ConfigMap` name and key containing the GitLab certificates to trust - useful for self-signed TLS certificates. Possibly reference the ArgoCD CM holding the trusted certs.

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).

## Gitea

Specify the repository from which to fetch the Gitea Pull requests.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      gitea:
        # The Gitea organization or user.
        owner: myorg
        # The Gitea repository
        repo: myrepository
        # The Gitea url to use
        api: https://gitea.mydomain.com/
        # Reference to a Secret containing an access token. (optional)
        tokenRef:
          secretName: gitea-token
          key: token
        # many gitea deployments use TLS, but many are self-hosted and self-signed certificates
        insecure: true
      requeueAfterSeconds: 1800
  template:
  # ...
```

* `owner`: Required name of the Gitea organization or user.
* `repo`: Required name of the Gitea repository.
* `api`: The url of the Gitea instance.
* `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)
* `insecure`: `Allow for self-signed certificates, primarily for testing.`

## Bitbucket Server

Fetch pull requests from a repo hosted on a Bitbucket Server (not the same as Bitbucket Cloud).

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      bitbucketServer:
        project: myproject
        repo: myrepository
        # URL of the Bitbucket Server. Required.
        api: https://mycompany.bitbucket.org
        # Credentials for Basic authentication (App Password). Either basicAuth or bearerToken
        # authentication is required to access private repositories
        basicAuth:
          # The username to authenticate with
          username: myuser
          # Reference to a Secret containing the password or personal access token.
          passwordRef:
            secretName: mypassword
            key: password
        # Credentials for Bearer Token (App Token) authentication. Either basicAuth or bearerToken
        # authentication is required to access private repositories
        bearerToken:
          # Reference to a Secret containing the bearer token.
          tokenRef:
            secretName: repotoken
            key: token
        # If true, skips validating the SCM provider's TLS certificate - useful for self-signed certificates.
        insecure: true
        # Reference to a ConfigMap containing trusted CA certs - useful for self-signed certificates. (optional)
        caRef:
          configMapName: argocd-tls-certs-cm
          key: bitbucket-ca
      # Labels are not supported by Bitbucket Server, so filtering by label is not possible.
      # Filter PRs using the source branch name. (optional)
      filters:
      - branchMatch: ".*-argocd"
  template:
  # ...
```

* `project`: Required name of the Bitbucket project
* `repo`: Required name of the Bitbucket repository.
* `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`
* `branchMatch`: Optional regexp filter which should match the source branch name. This is an alternative to labels which are not supported by Bitbucket server.

If you want to access a private repository, you must also provide the credentials for Basic auth (this is the only auth supported currently):
* `username`: The username to authenticate with. It only needs read access to the relevant repo.
* `passwordRef`: A `Secret` name and key containing the password or personal access token to use for requests.

In case of Bitbucket App Token, go with `bearerToken` section.
* `tokenRef`: A `Secret` name and key containing the app token to use for requests.

In case self-signed BitBucket Server certificates, the following options can be usefully:
* `insecure`: By default (false) - Skip checking the validity of the SCM's certificate - useful for self-signed TLS certificates.
* `caRef`: Optional `ConfigMap` name and key containing the BitBucket server certificates to trust - useful for self-signed TLS certificates. Possibly reference the ArgoCD CM holding the trusted certs.

## Bitbucket Cloud

Fetch pull requests from a repo hosted on a Bitbucket Cloud.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - pullRequest:
        bitbucket:
          # Workspace name where the repoistory is stored under. Required.
          owner: myproject
          # Repository slug. Required.
          repo: myrepository
          # URL of the Bitbucket Server. (optional) Will default to 'https://api.bitbucket.org/2.0'.
          api: https://api.bitbucket.org/2.0
          # Credentials for Basic authentication (App Password). Either basicAuth or bearerToken
          # authentication is required to access private repositories
          basicAuth:
            # The username to authenticate with
            username: myuser
            # Reference to a Secret containing the password or personal access token.
            passwordRef:
              secretName: mypassword
              key: password
          # Credentials for Bearer Token (App Token) authentication. Either basicAuth or bearerToken
          # authentication is required to access private repositories
          bearerToken:
            # Reference to a Secret containing the bearer token.
            tokenRef:
              secretName: repotoken
              key: token
        # Labels are not supported by Bitbucket Cloud, so filtering by label is not possible.
        # Filter PRs using the source branch name. (optional)
        filters:
          - branchMatch: ".*-argocd"
  template:
  # ...
```

- `owner`: Required name of the Bitbucket workspace
- `repo`: Required name of the Bitbucket repository.
- `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`
- `branchMatch`: Optional regexp filter which should match the source branch name. This is an alternative to labels which are not supported by Bitbucket server.

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.

To use Bitbucket App Password, use `basicAuth` section.
- `username`: The username to authenticate with. It only needs read access to the relevant repo.
- `passwordRef`: A `Secret` name and key containing the password or personal access token to use for requests.

In case of Bitbucket App Token, go with `bearerToken` section.
- `tokenRef`: A `Secret` name and key containing the app token to use for requests.

## Azure DevOps

Specify the organization, project and repository from which you want to fetch pull requests.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      azuredevops:
        # Azure DevOps org to scan. Required.
        organization: myorg
        # Azure DevOps project name to scan. Required.
        project: myproject
        # Azure DevOps repo name to scan. Required.
        repo: myrepository
        # The Azure DevOps API URL to talk to. If blank, use https://dev.azure.com/.
        api: https://dev.azure.com/
        # Reference to a Secret containing an access token. (optional)
        tokenRef:
          secretName: azure-devops-token
          key: token
        # Labels is used to filter the PRs that you want to target. (optional)
        labels:
        - preview
      requeueAfterSeconds: 1800
  template:
  # ...
```

* `organization`: Required name of the Azure DevOps organization.
* `project`: Required name of the Azure DevOps project.
* `repo`: Required name of the Azure DevOps repository.
* `api`: If using self-hosted Azure DevOps Repos, the URL to access it. (Optional)
* `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)
* `labels`: Filter the PRs to those containing **all** of the labels listed. (Optional)

## Filters

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.
Currently, only a subset of filters is available when comparing with [SCM provider](Generators-SCM-Provider.md) filters.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
      # ...
      # Include any pull request ending with "argocd". (optional)
      filters:
      - branchMatch: ".*-argocd"
  template:
  # ...
```

* `branchMatch`: A regexp matched against source branch names.
* `targetBranchMatch`: A regexp matched against target branch names.

[GitHub](#github) and [GitLab](#gitlab) also support a `labels` filter.

## Template

As with all generators, several keys are available for replacement in the generated application.

The following is a comprehensive Helm Application example;

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
    # ...
  template:
    metadata:
      name: 'myapp--'
    spec:
      source:
        repoURL: 'https://github.com/myorg/myrepo.git'
        targetRevision: ''
        path: kubernetes/
        helm:
          parameters:
          - name: "image.tag"
            value: "pull--"
      project: "my-project"
      destination:
        server: https://kubernetes.default.svc
        namespace: default
```

And, here is a robust Kustomize example;

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - pullRequest:
    # ...
  template:
    metadata:
      name: 'myapp--'
    spec:
      source:
        repoURL: 'https://github.com/myorg/myrepo.git'
        targetRevision: ''
        path: kubernetes/
        kustomize:
          nameSuffix: ''
          commonLabels:
            app.kubernetes.io/instance: '-'
          images:
          - 'ghcr.io/myorg/myrepo:-'
      project: "my-project"
      destination:
        server: https://kubernetes.default.svc
        namespace: default
```

* `number`: The ID number of the pull request.
* `title`: The title of the pull request.
* `branch`: The name of the branch of the pull request head.
* `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.
* `target_branch`: The name of the target branch of the pull request.
* `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.
* `head_sha`: This is the SHA of the head of the pull request.
* `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).
* `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).
* `labels`: The array of pull request labels. (Supported only for Go Template ApplicationSet manifests.)
* `author`: The author/creator of the pull request.

## Webhook Configuration

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.

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.

!!! note
    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.

### Github webhook configuration

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.

Add Webhook URL with uri `/api/webhook` and select content-type as json
![Add Webhook URL](../../assets/applicationset/webhook-config-pullrequest-generator.png "Add Webhook URL")

Select `Let me select individual events` and enable the checkbox for `Pull requests`.

![Add Webhook](../../assets/applicationset/webhook-config-pull-request.png "Add Webhook Pull Request")

The Pull Request Generator will requeue when the next action occurs.

- `opened`
- `closed`
- `reopened`
- `labeled`
- `unlabeled`
- `synchronized`

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).

### Gitlab webhook configuration

Enable checkbox for "Merge request events" in triggers list.

![Add Gitlab Webhook](../../assets/applicationset/webhook-config-merge-request-gitlab.png "Add Gitlab Merge request Webhook")

The Pull Request Generator will requeue when the next action occurs.

- `open`
- `close`
- `reopen`
- `update`
- `merge`

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).

## Lifecycle

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.

Pull Request Generator  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      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest          When using a Pull Request generator  the ApplicationSet controller polls every  requeueAfterSeconds  interval  defaulting to every 30 minutes  to detect changes        requeueAfterSeconds  1800         See below for provider specific options        github                         note     Know the security implications of PR generators in ApplicationSets       Only admins may create ApplicationSets    Security md only admins may createupdatedelete applicationsets  to avoid     leaking Secrets  and  only admins may create PRs    Security md templated project field  if the  project  field of     an ApplicationSet with a PR generator is templated  to avoid granting management of out of bounds resources      GitHub  Specify the repository from which to fetch the GitHub Pull requests      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest        github            The GitHub organization or user          owner  myorg           The Github repository         repo  myrepository           For GitHub Enterprise  optional          api  https   git example com            Reference to a Secret containing an access token   optional          tokenRef            secretName  github token           key  token            optional  use a GitHub App to access the API instead of a PAT          appSecretName  github app repo creds           Labels is used to filter the PRs that you want to target   optional          labels            preview       requeueAfterSeconds  1800   template                  owner   Required name of the GitHub organization or user     repo   Required name of the GitHub repository     api   If using GitHub Enterprise  the URL to access it   Optional     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     labels   Filter the PRs to those containing   all   of the labels listed   Optional     appSecretName   A  Secret  name containing a GitHub App secret in  repo creds format  repo creds     repo creds      declarative setup md repository credentials     GitLab  Specify the project from which to fetch the GitLab merge requests      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest        gitlab            The GitLab project ID          project   12341234            For self hosted GitLab  optional          api  https   git example com            Reference to a Secret containing an access token   optional          tokenRef            secretName  gitlab token           key  token           Labels is used to filter the MRs that you want to target   optional          labels            preview           MR state is used to filter MRs only with a certain state   optional          pullRequestState  opened           If true  skips validating the SCM provider s TLS certificate   useful for self signed certificates          insecure  false           Reference to a ConfigMap containing trusted CA certs   useful for self signed certificates   optional          caRef            configMapName  argocd tls certs cm           key  gitlab ca       requeueAfterSeconds  1800   template                  project   Required project ID of the GitLab project     api   If using self hosted GitLab  the URL to access it   Optional     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     labels   Labels is used to filter the MRs that you want to target   Optional     pullRequestState   PullRequestState is an additional MRs filter to get only those with a certain state  Default      all states     insecure   By default  false    Skip checking the validity of the SCM s certificate   useful for self signed TLS certificates     caRef   Optional  ConfigMap  name and key containing the GitLab certificates to trust   useful for self signed TLS certificates  Possibly reference the ArgoCD CM holding the trusted certs   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       Gitea  Specify the repository from which to fetch the Gitea Pull requests      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest        gitea            The Gitea organization or user          owner  myorg           The Gitea repository         repo  myrepository           The Gitea url to use         api  https   gitea mydomain com            Reference to a Secret containing an access token   optional          tokenRef            secretName  gitea token           key  token           many gitea deployments use TLS  but many are self hosted and self signed certificates         insecure  true       requeueAfterSeconds  1800   template                  owner   Required name of the Gitea organization or user     repo   Required name of the Gitea repository     api   The url of the Gitea instance     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     insecure    Allow for self signed certificates  primarily for testing       Bitbucket Server  Fetch pull requests from a repo hosted on a Bitbucket Server  not the same as Bitbucket Cloud       yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest        bitbucketServer          project  myproject         repo  myrepository           URL of the Bitbucket Server  Required          api  https   mycompany bitbucket org           Credentials for Basic authentication  App Password   Either basicAuth or bearerToken           authentication is required to access private repositories         basicAuth              The username to authenticate with           username  myuser             Reference to a Secret containing the password or personal access token            passwordRef              secretName  mypassword             key  password           Credentials for Bearer Token  App Token  authentication  Either basicAuth or bearerToken           authentication is required to access private repositories         bearerToken              Reference to a Secret containing the bearer token            tokenRef              secretName  repotoken             key  token           If true  skips validating the SCM provider s TLS certificate   useful for self signed certificates          insecure  true           Reference to a ConfigMap containing trusted CA certs   useful for self signed certificates   optional          caRef            configMapName  argocd tls certs cm           key  bitbucket ca         Labels are not supported by Bitbucket Server  so filtering by label is not possible          Filter PRs using the source branch name   optional        filters          branchMatch      argocd    template                  project   Required name of the Bitbucket project    repo   Required name of the Bitbucket repository     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     branchMatch   Optional regexp filter which should match the source branch name  This is an alternative to labels which are not supported by Bitbucket server   If you want to access a private repository  you must also provide the credentials for Basic auth  this is the only auth supported currently      username   The username to authenticate with  It only needs read access to the relevant repo     passwordRef   A  Secret  name and key containing the password or personal access token to use for requests   In case of Bitbucket App Token  go with  bearerToken  section     tokenRef   A  Secret  name and key containing the app token to use for requests   In case self signed BitBucket Server certificates  the following options can be usefully     insecure   By default  false    Skip checking the validity of the SCM s certificate   useful for self signed TLS certificates     caRef   Optional  ConfigMap  name and key containing the BitBucket server certificates to trust   useful for self signed TLS certificates  Possibly reference the ArgoCD CM holding the trusted certs      Bitbucket Cloud  Fetch pull requests from a repo hosted on a Bitbucket Cloud      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators        pullRequest          bitbucket              Workspace name where the repoistory is stored under  Required            owner  myproject             Repository slug  Required            repo  myrepository             URL of the Bitbucket Server   optional  Will default to  https   api bitbucket org 2 0             api  https   api bitbucket org 2 0             Credentials for Basic authentication  App Password   Either basicAuth or bearerToken             authentication is required to access private repositories           basicAuth                The username to authenticate with             username  myuser               Reference to a Secret containing the password or personal access token              passwordRef                secretName  mypassword               key  password             Credentials for Bearer Token  App Token  authentication  Either basicAuth or bearerToken             authentication is required to access private repositories           bearerToken                Reference to a Secret containing the bearer token              tokenRef                secretName  repotoken               key  token           Labels are not supported by Bitbucket Cloud  so filtering by label is not possible            Filter PRs using the source branch name   optional          filters              branchMatch      argocd    template                  owner   Required name of the Bitbucket workspace    repo   Required name of the Bitbucket repository     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     branchMatch   Optional regexp filter which should match the source branch name  This is an alternative to labels which are not supported by Bitbucket server   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   To use Bitbucket App Password  use  basicAuth  section     username   The username to authenticate with  It only needs read access to the relevant repo     passwordRef   A  Secret  name and key containing the password or personal access token to use for requests   In case of Bitbucket App Token  go with  bearerToken  section     tokenRef   A  Secret  name and key containing the app token to use for requests      Azure DevOps  Specify the organization  project and repository from which you want to fetch pull requests      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest        azuredevops            Azure DevOps org to scan  Required          organization  myorg           Azure DevOps project name to scan  Required          project  myproject           Azure DevOps repo name to scan  Required          repo  myrepository           The Azure DevOps API URL to talk to  If blank  use https   dev azure com           api  https   dev azure com            Reference to a Secret containing an access token   optional          tokenRef            secretName  azure devops token           key  token           Labels is used to filter the PRs that you want to target   optional          labels            preview       requeueAfterSeconds  1800   template                  organization   Required name of the Azure DevOps organization     project   Required name of the Azure DevOps project     repo   Required name of the Azure DevOps repository     api   If using self hosted Azure DevOps Repos  the URL to access it   Optional     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     labels   Filter the PRs to those containing   all   of the labels listed   Optional      Filters  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  Currently  only a subset of filters is available when comparing with  SCM provider  Generators SCM Provider md  filters      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest                      Include any pull request ending with  argocd    optional        filters          branchMatch      argocd    template                  branchMatch   A regexp matched against source branch names     targetBranchMatch   A regexp matched against target branch names    GitHub   github  and  GitLab   gitlab  also support a  labels  filter      Template  As with all generators  several keys are available for replacement in the generated application   The following is a comprehensive Helm Application example      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest              template      metadata        name   myapp        spec        source          repoURL   https   github com myorg myrepo git          targetRevision             path  kubernetes          helm            parameters              name   image tag              value   pull          project   my project        destination          server  https   kubernetes default svc         namespace  default      And  here is a robust Kustomize example      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    name  myapps spec    goTemplate  true   goTemplateOptions    missingkey error     generators      pullRequest              template      metadata        name   myapp        spec        source          repoURL   https   github com myorg myrepo git          targetRevision             path  kubernetes          kustomize            nameSuffix               commonLabels              app kubernetes io instance                images               ghcr io myorg myrepo          project   my project        destination          server  https   kubernetes default svc         namespace  default         number   The ID number of the pull request     title   The title of the pull request     branch   The name of the branch of the pull request head     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     target branch   The name of the target branch of the pull request     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     head sha   This is the SHA of the head of the pull request     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      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      labels   The array of pull request labels   Supported only for Go Template ApplicationSet manifests      author   The author creator of the pull request      Webhook Configuration  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   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       note     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       Github webhook configuration  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   Add Webhook URL with uri   api webhook  and select content type as json   Add Webhook URL        assets applicationset webhook config pullrequest generator png  Add Webhook URL    Select  Let me select individual events  and enable the checkbox for  Pull requests      Add Webhook        assets applicationset webhook config pull request png  Add Webhook Pull Request    The Pull Request Generator will requeue when the next action occurs      opened     closed     reopened     labeled     unlabeled     synchronized   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        Gitlab webhook configuration  Enable checkbox for  Merge request events  in triggers list     Add Gitlab Webhook        assets applicationset webhook config merge request gitlab png  Add Gitlab Merge request Webhook    The Pull Request Generator will requeue when the next action occurs      open     close     reopen     update     merge   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       Lifecycle  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


argocd The ApplicationSet controller supports a number of settings that limit the ability of the controller to make changes to generated Applications for example preventing the controller from deleting child Applications Dry run prevent ApplicationSet from creating modifying or deleting all Applications These settings allow you to exert control over when and how changes are made to your Applications and to their corresponding cluster resources etc Here are some of the controller settings that may be modified to alter the ApplicationSet controller s resource handling behaviour Controlling if when the ApplicationSet controller modifies resources

Answer:
# Controlling if/when the ApplicationSet controller modifies `Application` resources

The ApplicationSet controller supports a number of settings that limit the ability of the controller to make changes to generated Applications, for example, preventing the controller from deleting child Applications.

These settings allow you to exert control over when, and how, changes are made to your Applications, and to their corresponding cluster resources (`Deployments`, `Services`, etc).

Here are some of the controller settings that may be modified to alter the ApplicationSet controller's resource-handling behaviour.

## Dry run: prevent ApplicationSet from creating, modifying, or deleting all Applications

To prevent the ApplicationSet controller from creating, modifying, or deleting any `Application` resources, you may enable `dry-run` mode. This essentially switches the controller into a "read only" mode, where the controller Reconcile loop will run, but no resources will be modified.

To enable dry-run, add `--dryrun true` to the ApplicationSet Deployment's container launch parameters.

See 'How to modify ApplicationSet container parameters' below for detailed steps on how to add this parameter to the controller.

## Managed Applications modification Policies

The ApplicationSet controller supports a parameter `--policy`, which is specified on launch (within the controller Deployment container), and which restricts what types of modifications will be made to managed Argo CD `Application` resources.

The `--policy` parameter takes four values: `sync`, `create-only`, `create-delete`, and `create-update`. (`sync` is the default, which is used if the `--policy` parameter is not specified; the other policies are described below).

It is also possible to set this policy per ApplicationSet.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  # (...)
  syncPolicy:
    applicationsSync: create-only # create-update, create-delete sync

```

- Policy `create-only`: Prevents ApplicationSet controller from modifying or deleting Applications. **WARNING**: It doesn't prevent Application controller from deleting Applications according to [ownerReferences](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) when deleting ApplicationSet.
- Policy `create-update`: Prevents ApplicationSet controller from deleting Applications. Update is allowed. **WARNING**: It doesn't prevent Application controller from deleting Applications according to [ownerReferences](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) when deleting ApplicationSet.
- Policy `create-delete`: Prevents ApplicationSet controller from modifying Applications. Delete is allowed.
- Policy `sync`: Update and Delete are allowed.

If the controller parameter `--policy` is set, it takes precedence on the field `applicationsSync`. It is possible to allow per ApplicationSet sync policy by setting variable `ARGOCD_APPLICATIONSET_CONTROLLER_ENABLE_POLICY_OVERRIDE` to argocd-cmd-params-cm `applicationsetcontroller.enable.policy.override` or directly with controller parameter `--enable-policy-override` (default to `false`).

### Policy - `create-only`: Prevent ApplicationSet controller from modifying and deleting Applications

To allow the ApplicationSet controller to *create* `Application` resources, but prevent any further modification, such as *deletion*, or modification of Application fields, add this parameter in the ApplicationSet controller:

**WARNING**: "*deletion*" indicates the case as the result of comparing generated Application between before and after, there are Applications which no longer exist. It doesn't indicate the case Applications are deleted according to ownerReferences to ApplicationSet. See [How to prevent Application controller from deleting Applications when deleting ApplicationSet](#how-to-prevent-application-controller-from-deleting-applications-when-deleting-applicationset)

```
--policy create-only
```

At ApplicationSet level

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  # (...)
  syncPolicy:
    applicationsSync: create-only
```

### Policy - `create-update`: Prevent ApplicationSet controller from deleting Applications

To allow the ApplicationSet controller to create or modify `Application` resources, but prevent Applications from being deleted, add the following parameter to the ApplicationSet controller `Deployment`:

**WARNING**: "*deletion*" indicates the case as the result of comparing generated Application between before and after, there are Applications which no longer exist. It doesn't indicate the case Applications are deleted according to ownerReferences to ApplicationSet. See [How to prevent Application controller from deleting Applications when deleting ApplicationSet](#how-to-prevent-application-controller-from-deleting-applications-when-deleting-applicationset)

```
--policy create-update
```

This may be useful to users looking for additional protection against deletion of the Applications generated by the controller.

At ApplicationSet level

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  # (...)
  syncPolicy:
    applicationsSync: create-update
```

### How to prevent Application controller from deleting Applications when deleting ApplicationSet

By default, `create-only` and `create-update` policy isn't effective against preventing deletion of Applications when deleting ApplicationSet.
You must set the finalizer to ApplicationSet to prevent deletion in such case, and use background cascading deletion.
If you use foreground cascading deletion, there's no guarantee to preserve applications.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  # (...)
```

## Ignore certain changes to Applications

The ApplicationSet spec includes an `ignoreApplicationDifferences` field, which allows you to specify which fields of
the ApplicationSet should be ignored when comparing Applications.

The field supports multiple ignore rules. Each ignore rule may specify a list of either `jsonPointers` or
`jqPathExpressions` to ignore.

You may optionally also specify a `name` to apply the ignore rule to a specific Application, or omit the `name` to apply
the ignore rule to all Applications.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  ignoreApplicationDifferences:
    - jsonPointers:
        - /spec/source/targetRevision
    - name: some-app
      jqPathExpressions:
        - .spec.source.helm.values
```

### Allow temporarily toggling auto-sync

One of the most common use cases for ignoring differences is to allow temporarily toggling auto-sync for an Application.

For example, if you have an ApplicationSet that is configured to automatically sync Applications, you may want to temporarily
disable auto-sync for a specific Application. You can do this by adding an ignore rule for the `spec.syncPolicy.automated` field.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  ignoreApplicationDifferences:
    - jsonPointers:
        - /spec/syncPolicy
```

### Limitations of `ignoreApplicationDifferences`

When an ApplicationSet is reconciled, the controller will compare the ApplicationSet spec with the spec of each Application
that it manages. If there are any differences, the controller will generate a patch to update the Application to match the
ApplicationSet spec.

The generated patch is a MergePatch. According to the MergePatch documentation, "existing lists will be completely
replaced by new lists" when there is a change to the list.

This limits the effectiveness of `ignoreApplicationDifferences` when the ignored field is in a list. For example, if you
have an application with multiple sources, and you want to ignore changes to the `targetRevision` of one of the sources,
changes in other fields or in other sources will cause the entire `sources` list to be replaced, and the `targetRevision`
field will be reset to the value defined in the ApplicationSet.

For example, consider this ApplicationSet:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  ignoreApplicationDifferences:
    - jqPathExpressions:
        - .spec.sources[] | select(.repoURL == "https://git.example.com/org/repo1").targetRevision
  template:
    spec:
      sources:
      - repoURL: https://git.example.com/org/repo1
        targetRevision: main
      - repoURL: https://git.example.com/org/repo2
        targetRevision: main
```

You can freely change the `targetRevision` of the `repo1` source, and the ApplicationSet controller will not overwrite
your change.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  sources:
  - repoURL: https://git.example.com/org/repo1
    targetRevision: fix/bug-123
  - repoURL: https://git.example.com/org/repo2
    targetRevision: main
```

However, if you change the `targetRevision` of the `repo2` source, the ApplicationSet controller will overwrite the entire
`sources` field.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  sources:
  - repoURL: https://git.example.com/org/repo1
    targetRevision: main
  - repoURL: https://git.example.com/org/repo2
    targetRevision: main
```

!!! note
    [Future improvements](https://github.com/argoproj/argo-cd/issues/15975) to the ApplicationSet controller may
    eliminate this problem. For example, the `ref` field might be made a merge key, allowing the ApplicationSet
    controller to generate and use a StrategicMergePatch instead of a MergePatch. You could then target a specific
    source by `ref`, ignore changes to a field in that source, and changes to other sources would not cause the ignored
    field to be overwritten.

## Prevent an `Application`'s child resources from being deleted, when the parent Application is deleted

By default, when an `Application` resource is deleted by the ApplicationSet controller, all of the child resources of the Application will be deleted as well (such as, all of the Application's `Deployments`, `Services`, etc).

To prevent an Application's child resources from being deleted when the parent Application is deleted, add the `preserveResourcesOnDeletion: true` field to the `syncPolicy` of the ApplicationSet:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  # (...)
  syncPolicy:
    preserveResourcesOnDeletion: true
```

More information on the specific behaviour of `preserveResourcesOnDeletion`, and deletion in ApplicationSet controller and Argo CD in general, can be found on the [Application Deletion](Application-Deletion.md) page.

## Prevent an Application's child resources from being modified

Changes made to the ApplicationSet will propagate to the Applications managed by the ApplicationSet, and then Argo CD will propagate the Application changes to the underlying cluster resources (as per [Argo CD Integration](Argo-CD-Integration.md)).

The propagation of Application changes to the cluster is managed by the [automated sync settings](../../user-guide/auto_sync.md), which are referenced in the ApplicationSet `template` field:

- `spec.template.syncPolicy.automated`: If enabled, changes to Applications will automatically propagate to the cluster resources of the cluster.
    - Unset this within the ApplicationSet template to 'pause' updates to cluster resources managed by the `Application` resource.
- `spec.template.syncPolicy.automated.prune`: By default, Automated sync will not delete resources when Argo CD detects the resource is no longer defined in Git.
    - For extra safety, set this to false to prevent unexpected changes to the backing Git repository from affecting cluster resources.

## How to modify ApplicationSet container launch parameters

There are a couple of ways to modify the ApplicationSet container parameters, so as to enable the above settings.

### A) Use `kubectl edit` to modify the deployment on the cluster

Edit the applicationset-controller `Deployment` resource on the cluster:
```
kubectl edit deployment/argocd-applicationset-controller -n argocd
```

Locate the `.spec.template.spec.containers[0].command` field, and add the required parameter(s):
```yaml
spec:
    # (...)
  template:
    # (...)
    spec:
      containers:
      - command:
        - entrypoint.sh
        - argocd-applicationset-controller
        # Insert new parameters here, for example:
        # --policy create-only
    # (...)
```

Save and exit the editor. Wait for a new `Pod` to start containing the updated parameters.

### Or, B) Edit the `install.yaml` manifest for the ApplicationSet installation

Rather than directly editing the cluster resource, you may instead choose to modify the installation YAML that is used to install the ApplicationSet controller:

Applicable for applicationset versions less than 0.4.0.
```bash
# Clone the repository

git clone https://github.com/argoproj/applicationset

# Checkout the version that corresponds to the one you have installed.
git checkout "(version of applicationset)"
# example: git checkout "0.1.0"

cd applicationset/manifests

# open 'install.yaml' in a text editor, make the same modifications to Deployment
# as described in the previous section.

# Apply the change to the cluster
kubectl apply -n argocd -f install.yaml
```

## Preserving changes made to an Applications annotations and labels

!!! note
    The same behavior can be achieved on a per-app basis using the [`ignoreApplicationDifferences`](#ignore-certain-changes-to-applications)
    feature described above. However, preserved fields may be configured globally, a feature that is not yet available
    for `ignoreApplicationDifferences`.

It is common practice in Kubernetes to store state in annotations, operators will often make use of this. To allow for this, it is possible to configure a list of annotations that the ApplicationSet should preserve when reconciling.

For example, imagine that we have an Application created from an ApplicationSet, but a custom annotation and label has since been added (to the Application) that does not exist in the `ApplicationSet` resource:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  # This annotation and label exists only on this Application, and not in
  # the parent ApplicationSet template:
  annotations:
    my-custom-annotation: some-value
  labels:
    my-custom-label: some-value
spec:
  # (...)
```

To preserve this annotation and label we can use the `preservedFields` property of the `ApplicationSet` like so:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  # (...)
  preservedFields:
    annotations: ["my-custom-annotation"]
    labels: ["my-custom-label"]
```

The ApplicationSet controller will leave this annotation and label as-is when reconciling, even though it is not defined in the metadata of the ApplicationSet itself.

By default, the Argo CD notifications and the Argo CD refresh type annotations are also preserved.

!!!note
  One can also set global preserved fields for the controller by passing a comma separated list of annotations and labels to
  `ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_ANNOTATIONS` and `ARGOCD_APPLICATIONSET_CONTROLLER_GLOBAL_PRESERVED_LABELS` respectively.

## Debugging unexpected changes to Applications

When the ApplicationSet controller makes a change to an application, it logs the patch at the debug level. To see these
logs, set the log level to debug in the `argocd-cmd-params-cm` ConfigMap in the `argocd` namespace:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
  namespace: argocd
data:
  applicationsetcontroller.log.level: debug
```

## Previewing changes

To preview changes that the ApplicationSet controller would make to Applications, you can create the AppSet in dry-run
mode. This works whether the AppSet already exists or not.

```shell
argocd appset create --dry-run ./appset.yaml -o json | jq -r '.status.resources[].name'
```

The dry-run will populate the returned ApplicationSet's status with the Applications which would be managed with the
given config. You can compare to the existing Applications to see what would change.

Controlling if when the ApplicationSet controller modifies  Application  resources  The ApplicationSet controller supports a number of settings that limit the ability of the controller to make changes to generated Applications  for example  preventing the controller from deleting child Applications   These settings allow you to exert control over when  and how  changes are made to your Applications  and to their corresponding cluster resources   Deployments    Services   etc    Here are some of the controller settings that may be modified to alter the ApplicationSet controller s resource handling behaviour      Dry run  prevent ApplicationSet from creating  modifying  or deleting all Applications  To prevent the ApplicationSet controller from creating  modifying  or deleting any  Application  resources  you may enable  dry run  mode  This essentially switches the controller into a  read only  mode  where the controller Reconcile loop will run  but no resources will be modified   To enable dry run  add    dryrun true  to the ApplicationSet Deployment s container launch parameters   See  How to modify ApplicationSet container parameters  below for detailed steps on how to add this parameter to the controller      Managed Applications modification Policies  The ApplicationSet controller supports a parameter    policy   which is specified on launch  within the controller Deployment container   and which restricts what types of modifications will be made to managed Argo CD  Application  resources   The    policy  parameter takes four values   sync    create only    create delete   and  create update     sync  is the default  which is used if the    policy  parameter is not specified  the other policies are described below    It is also possible to set this policy per ApplicationSet      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec              syncPolicy      applicationsSync  create only   create update  create delete sync         Policy  create only   Prevents ApplicationSet controller from modifying or deleting Applications    WARNING    It doesn t prevent Application controller from deleting Applications according to  ownerReferences  https   kubernetes io docs concepts overview working with objects owners dependents   when deleting ApplicationSet    Policy  create update   Prevents ApplicationSet controller from deleting Applications  Update is allowed    WARNING    It doesn t prevent Application controller from deleting Applications according to  ownerReferences  https   kubernetes io docs concepts overview working with objects owners dependents   when deleting ApplicationSet    Policy  create delete   Prevents ApplicationSet controller from modifying Applications  Delete is allowed    Policy  sync   Update and Delete are allowed   If the controller parameter    policy  is set  it takes precedence on the field  applicationsSync   It is possible to allow per ApplicationSet sync policy by setting variable  ARGOCD APPLICATIONSET CONTROLLER ENABLE POLICY OVERRIDE  to argocd cmd params cm  applicationsetcontroller enable policy override  or directly with controller parameter    enable policy override   default to  false         Policy    create only   Prevent ApplicationSet controller from modifying and deleting Applications  To allow the ApplicationSet controller to  create   Application  resources  but prevent any further modification  such as  deletion   or modification of Application fields  add this parameter in the ApplicationSet controller     WARNING      deletion   indicates the case as the result of comparing generated Application between before and after  there are Applications which no longer exist  It doesn t indicate the case Applications are deleted according to ownerReferences to ApplicationSet  See  How to prevent Application controller from deleting Applications when deleting ApplicationSet   how to prevent application controller from deleting applications when deleting applicationset         policy create only      At ApplicationSet level     yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec              syncPolicy      applicationsSync  create only          Policy    create update   Prevent ApplicationSet controller from deleting Applications  To allow the ApplicationSet controller to create or modify  Application  resources  but prevent Applications from being deleted  add the following parameter to the ApplicationSet controller  Deployment      WARNING      deletion   indicates the case as the result of comparing generated Application between before and after  there are Applications which no longer exist  It doesn t indicate the case Applications are deleted according to ownerReferences to ApplicationSet  See  How to prevent Application controller from deleting Applications when deleting ApplicationSet   how to prevent application controller from deleting applications when deleting applicationset         policy create update      This may be useful to users looking for additional protection against deletion of the Applications generated by the controller   At ApplicationSet level     yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec              syncPolicy      applicationsSync  create update          How to prevent Application controller from deleting Applications when deleting ApplicationSet  By default   create only  and  create update  policy isn t effective against preventing deletion of Applications when deleting ApplicationSet  You must set the finalizer to ApplicationSet to prevent deletion in such case  and use background cascading deletion  If you use foreground cascading deletion  there s no guarantee to preserve applications      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet metadata    finalizers      resources finalizer argocd argoproj io spec                    Ignore certain changes to Applications  The ApplicationSet spec includes an  ignoreApplicationDifferences  field  which allows you to specify which fields of  the ApplicationSet should be ignored when comparing Applications   The field supports multiple ignore rules  Each ignore rule may specify a list of either  jsonPointers  or   jqPathExpressions  to ignore   You may optionally also specify a  name  to apply the ignore rule to a specific Application  or omit the  name  to apply the ignore rule to all Applications      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec    ignoreApplicationDifferences        jsonPointers             spec source targetRevision       name  some app       jqPathExpressions             spec source helm values          Allow temporarily toggling auto sync  One of the most common use cases for ignoring differences is to allow temporarily toggling auto sync for an Application   For example  if you have an ApplicationSet that is configured to automatically sync Applications  you may want to temporarily disable auto sync for a specific Application  You can do this by adding an ignore rule for the  spec syncPolicy automated  field      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec    ignoreApplicationDifferences        jsonPointers             spec syncPolicy          Limitations of  ignoreApplicationDifferences   When an ApplicationSet is reconciled  the controller will compare the ApplicationSet spec with the spec of each Application that it manages  If there are any differences  the controller will generate a patch to update the Application to match the ApplicationSet spec   The generated patch is a MergePatch  According to the MergePatch documentation   existing lists will be completely  replaced by new lists  when there is a change to the list   This limits the effectiveness of  ignoreApplicationDifferences  when the ignored field is in a list  For example  if you have an application with multiple sources  and you want to ignore changes to the  targetRevision  of one of the sources  changes in other fields or in other sources will cause the entire  sources  list to be replaced  and the  targetRevision  field will be reset to the value defined in the ApplicationSet   For example  consider this ApplicationSet      yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec    ignoreApplicationDifferences        jqPathExpressions             spec sources     select  repoURL     https   git example com org repo1   targetRevision   template      spec        sources          repoURL  https   git example com org repo1         targetRevision  main         repoURL  https   git example com org repo2         targetRevision  main      You can freely change the  targetRevision  of the  repo1  source  and the ApplicationSet controller will not overwrite your change      yaml apiVersion  argoproj io v1alpha1 kind  Application spec    sources      repoURL  https   git example com org repo1     targetRevision  fix bug 123     repoURL  https   git example com org repo2     targetRevision  main      However  if you change the  targetRevision  of the  repo2  source  the ApplicationSet controller will overwrite the entire  sources  field      yaml apiVersion  argoproj io v1alpha1 kind  Application spec    sources      repoURL  https   git example com org repo1     targetRevision  main     repoURL  https   git example com org repo2     targetRevision  main          note      Future improvements  https   github com argoproj argo cd issues 15975  to the ApplicationSet controller may      eliminate this problem  For example  the  ref  field might be made a merge key  allowing the ApplicationSet      controller to generate and use a StrategicMergePatch instead of a MergePatch  You could then target a specific      source by  ref   ignore changes to a field in that source  and changes to other sources would not cause the ignored      field to be overwritten      Prevent an  Application  s child resources from being deleted  when the parent Application is deleted  By default  when an  Application  resource is deleted by the ApplicationSet controller  all of the child resources of the Application will be deleted as well  such as  all of the Application s  Deployments    Services   etc    To prevent an Application s child resources from being deleted when the parent Application is deleted  add the  preserveResourcesOnDeletion  true  field to the  syncPolicy  of the ApplicationSet     yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec              syncPolicy      preserveResourcesOnDeletion  true      More information on the specific behaviour of  preserveResourcesOnDeletion   and deletion in ApplicationSet controller and Argo CD in general  can be found on the  Application Deletion  Application Deletion md  page       Prevent an Application s child resources from being modified  Changes made to the ApplicationSet will propagate to the Applications managed by the ApplicationSet  and then Argo CD will propagate the Application changes to the underlying cluster resources  as per  Argo CD Integration  Argo CD Integration md     The propagation of Application changes to the cluster is managed by the  automated sync settings        user guide auto sync md   which are referenced in the ApplicationSet  template  field      spec template syncPolicy automated   If enabled  changes to Applications will automatically propagate to the cluster resources of the cluster         Unset this within the ApplicationSet template to  pause  updates to cluster resources managed by the  Application  resource     spec template syncPolicy automated prune   By default  Automated sync will not delete resources when Argo CD detects the resource is no longer defined in Git        For extra safety  set this to false to prevent unexpected changes to the backing Git repository from affecting cluster resources       How to modify ApplicationSet container launch parameters  There are a couple of ways to modify the ApplicationSet container parameters  so as to enable the above settings       A  Use  kubectl edit  to modify the deployment on the cluster  Edit the applicationset controller  Deployment  resource on the cluster      kubectl edit deployment argocd applicationset controller  n argocd      Locate the   spec template spec containers 0  command  field  and add the required parameter s      yaml spec                template                  spec        containers          command            entrypoint sh           argocd applicationset controller           Insert new parameters here  for example              policy create only                  Save and exit the editor  Wait for a new  Pod  to start containing the updated parameters       Or  B  Edit the  install yaml  manifest for the ApplicationSet installation  Rather than directly editing the cluster resource  you may instead choose to modify the installation YAML that is used to install the ApplicationSet controller   Applicable for applicationset versions less than 0 4 0      bash   Clone the repository  git clone https   github com argoproj applicationset    Checkout the version that corresponds to the one you have installed  git checkout   version of applicationset     example  git checkout  0 1 0   cd applicationset manifests    open  install yaml  in a text editor  make the same modifications to Deployment    as described in the previous section     Apply the change to the cluster kubectl apply  n argocd  f install yaml         Preserving changes made to an Applications annotations and labels      note     The same behavior can be achieved on a per app basis using the   ignoreApplicationDifferences    ignore certain changes to applications       feature described above  However  preserved fields may be configured globally  a feature that is not yet available     for  ignoreApplicationDifferences    It is common practice in Kubernetes to store state in annotations  operators will often make use of this  To allow for this  it is possible to configure a list of annotations that the ApplicationSet should preserve when reconciling   For example  imagine that we have an Application created from an ApplicationSet  but a custom annotation and label has since been added  to the Application  that does not exist in the  ApplicationSet  resource     yaml apiVersion  argoproj io v1alpha1 kind  Application metadata      This annotation and label exists only on this Application  and not in      the parent ApplicationSet template    annotations       my custom annotation  some value   labels      my custom label  some value spec                 To preserve this annotation and label we can use the  preservedFields  property of the  ApplicationSet  like so     yaml apiVersion  argoproj io v1alpha1 kind  ApplicationSet spec              preservedFields      annotations    my custom annotation       labels    my custom label        The ApplicationSet controller will leave this annotation and label as is when reconciling  even though it is not defined in the metadata of the ApplicationSet itself   By default  the Argo CD notifications and the Argo CD refresh type annotations are also preserved      note   One can also set global preserved fields for the controller by passing a comma separated list of annotations and labels to     ARGOCD APPLICATIONSET CONTROLLER GLOBAL PRESERVED ANNOTATIONS  and  ARGOCD APPLICATIONSET CONTROLLER GLOBAL PRESERVED LABELS  respectively      Debugging unexpected changes to Applications  When the ApplicationSet controller makes a change to an application  it logs the patch at the debug level  To see these logs  set the log level to debug in the  argocd cmd params cm  ConfigMap in the  argocd  namespace      yaml apiVersion  v1 kind  ConfigMap metadata    name  argocd cmd params cm   namespace  argocd data    applicationsetcontroller log level  debug         Previewing changes  To preview changes that the ApplicationSet controller would make to Applications  you can create the AppSet in dry run  mode  This works whether the AppSet already exists or not      shell argocd appset create   dry run   appset yaml  o json   jq  r   status resources   name       The dry run will populate the returned ApplicationSet s status with the Applications which would be managed with the  given config  You can compare to the existing Applications to see what would change


argocd Installation Have a file default location is Getting Started Requirements This guide assumes you are familiar with Argo CD and its basic concepts See the for more information Installed command line tool

Answer:
# Getting Started

This guide assumes you are familiar with Argo CD and its basic concepts. See the [Argo CD documentation](../../core_concepts.md) for more information.

## Requirements

* Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool
* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`).

## Installation

There are a few options for installing the ApplicationSet controller.

### A) Install ApplicationSet as part of Argo CD

Starting with Argo CD v2.3, the ApplicationSet controller is bundled with Argo CD. It is no longer necessary to install the ApplicationSet controller separately from Argo CD.

Follow the [Argo CD Getting Started](../../getting_started.md) instructions for more information.

### B) Install ApplicationSet into an existing Argo CD install (pre-Argo CD v2.3)

**Note**: These instructions only apply to versions of Argo CD before v2.3.0.

The ApplicationSet controller *must* be installed into the same namespace as the Argo CD it is targeting.

Presuming that Argo CD is installed into the `argocd` namespace, run the following command:

```bash
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/applicationset/v0.4.0/manifests/install.yaml
```

Once installed, the ApplicationSet controller requires no additional setup.

The `manifests/install.yaml` file contains the Kubernetes manifests required to install the ApplicationSet controller:

- CustomResourceDefinition for `ApplicationSet` resource
- Deployment for `argocd-applicationset-controller`
- ServiceAccount for use by ApplicationSet controller, to access Argo CD resources
- Role granting RBAC access to needed resources, for ServiceAccount
- RoleBinding to bind the ServiceAccount and Role

<!-- ### C) Install development builds of ApplicationSet controller for access to the latest features

Development builds of the ApplicationSet controller can be installed by running the following command:
```bash
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/applicationset/master/manifests/install.yaml
```

With this option you will need to ensure that Argo CD is already installed into the `argocd` namespace.

How it works:

- After each successful commit to *argoproj/applicationset* `master` branch, a GitHub action will run that performs a container build/push to [`argoproj/argocd-applicationset:latest`](https://quay.io/repository/argoproj/argocd-applicationset?tab=tags )
- [Documentation for the `master`-branch-based developer builds](https://argocd-applicationset.readthedocs.io/en/master/)  is available from Read the Docs.

!!! warning
    Development builds contain newer features and bug fixes, but are more likely to be unstable, as compared to release builds.

See the `master` branch [Read the Docs](https://argocd-applicationset.readthedocs.io/en/master/) page for documentation on post-release features. -->

<!-- ## Upgrading to a Newer Release

To upgrade from an older release (eg 0.1.0, 0.2.0) to a newer release (eg 0.3.0), you only need to `kubectl apply` the `install.yaml` for the new release, as described under *Installation* above.

There are no manual upgrade steps required between any release of ApplicationSet controller, (including 0.1.0, 0.2.0, and 0.3.0) as of this writing, however, see the behaviour changes in ApplicationSet controller v0.3.0, below.

### Behaviour changes in ApplicationSet controller v0.3.0

There are no breaking changes, however, a couple of behaviours have changed from v0.2.0 to v0.3.0. See the [v0.3.0 upgrade page](upgrading/v0.2.0-to-v0.3.0.md) for details. -->
## Enabling high availability mode

To enable high availability, you have to set the command ``` --enable-leader-election=true  ``` in argocd-applicationset-controller container and increase the replicas.

do following changes in manifests/install.yaml

```bash
    spec:
      containers:
      - command:
        - entrypoint.sh
        - argocd-applicationset-controller
        - --enable-leader-election=true
```

### Optional: Additional Post-Upgrade Safeguards

See the [Controlling Resource Modification](Controlling-Resource-Modification.md) page for information on additional parameters you may wish to add to the ApplicationSet Resource in `install.yaml`, to provide extra security against any initial, unexpected post-upgrade behaviour.

For instance, to temporarily prevent the upgraded ApplicationSet controller from making any changes, you could:

- Enable dry-run
- Use a create-only policy
- Enable `preserveResourcesOnDeletion` on your ApplicationSets
- Temporarily disable automated sync in your ApplicationSets' template

These parameters would allow you to observe/control the behaviour of the new version of the ApplicationSet controller in your environment, to ensure you are happy with the result (see the ApplicationSet log file for details). Just don't forget to remove any temporary changes when you are done testing!

However, as mentioned above, these steps are not strictly necessary: upgrading the ApplicationSet controller should be a minimally invasive process, and these are only suggested as an optional precaution for extra safety.

## Next Steps

Once your ApplicationSet controller is up and running, proceed to [Use Cases](Use-Cases.md) to learn more about the supported scenarios, or proceed directly to [Generators](Generators.md) to see example `ApplicationSet` resources.

Getting Started  This guide assumes you are familiar with Argo CD and its basic concepts  See the  Argo CD documentation        core concepts md  for more information          Requirements    Installed  kubectl  https   kubernetes io docs tasks tools install kubectl   command line tool   Have a  kubeconfig  https   kubernetes io docs tasks access application cluster configure access multiple clusters   file  default location is     kube config        Installation  There are a few options for installing the ApplicationSet controller        A  Install ApplicationSet as part of Argo CD  Starting with Argo CD v2 3  the ApplicationSet controller is bundled with Argo CD  It is no longer necessary to install the ApplicationSet controller separately from Argo CD   Follow the  Argo CD Getting Started        getting started md  instructions for more information         B  Install ApplicationSet into an existing Argo CD install  pre Argo CD v2 3     Note    These instructions only apply to versions of Argo CD before v2 3 0   The ApplicationSet controller  must  be installed into the same namespace as the Argo CD it is targeting   Presuming that Argo CD is installed into the  argocd  namespace  run the following command      bash kubectl apply  n argocd  f https   raw githubusercontent com argoproj applicationset v0 4 0 manifests install yaml      Once installed  the ApplicationSet controller requires no additional setup   The  manifests install yaml  file contains the Kubernetes manifests required to install the ApplicationSet controller     CustomResourceDefinition for  ApplicationSet  resource   Deployment for  argocd applicationset controller    ServiceAccount for use by ApplicationSet controller  to access Argo CD resources   Role granting RBAC access to needed resources  for ServiceAccount   RoleBinding to bind the ServiceAccount and Role            C  Install development builds of ApplicationSet controller for access to the latest features  Development builds of the ApplicationSet controller can be installed by running the following command     bash kubectl apply  n argocd  f https   raw githubusercontent com argoproj applicationset master manifests install yaml      With this option you will need to ensure that Argo CD is already installed into the  argocd  namespace   How it works     After each successful commit to  argoproj applicationset   master  branch  a GitHub action will run that performs a container build push to   argoproj argocd applicationset latest   https   quay io repository argoproj argocd applicationset tab tags      Documentation for the  master  branch based developer builds  https   argocd applicationset readthedocs io en master    is available from Read the Docs       warning     Development builds contain newer features and bug fixes  but are more likely to be unstable  as compared to release builds   See the  master  branch  Read the Docs  https   argocd applicationset readthedocs io en master   page for documentation on post release features                Upgrading to a Newer Release  To upgrade from an older release  eg 0 1 0  0 2 0  to a newer release  eg 0 3 0   you only need to  kubectl apply  the  install yaml  for the new release  as described under  Installation  above   There are no manual upgrade steps required between any release of ApplicationSet controller   including 0 1 0  0 2 0  and 0 3 0  as of this writing  however  see the behaviour changes in ApplicationSet controller v0 3 0  below       Behaviour changes in ApplicationSet controller v0 3 0  There are no breaking changes  however  a couple of behaviours have changed from v0 2 0 to v0 3 0  See the  v0 3 0 upgrade page  upgrading v0 2 0 to v0 3 0 md  for details         Enabling high availability mode  To enable high availability  you have to set the command       enable leader election true      in argocd applicationset controller container and increase the replicas    do following changes in manifests install yaml     bash     spec        containers          command            entrypoint sh           argocd applicationset controller             enable leader election true          Optional  Additional Post Upgrade Safeguards  See the  Controlling Resource Modification  Controlling Resource Modification md  page for information on additional parameters you may wish to add to the ApplicationSet Resource in  install yaml   to provide extra security against any initial  unexpected post upgrade behaviour    For instance  to temporarily prevent the upgraded ApplicationSet controller from making any changes  you could     Enable dry run   Use a create only policy   Enable  preserveResourcesOnDeletion  on your ApplicationSets   Temporarily disable automated sync in your ApplicationSets  template  These parameters would allow you to observe control the behaviour of the new version of the ApplicationSet controller in your environment  to ensure you are happy with the result  see the ApplicationSet log file for details   Just don t forget to remove any temporary changes when you are done testing   However  as mentioned above  these steps are not strictly necessary  upgrading the ApplicationSet controller should be a minimally invasive process  and these are only suggested as an optional precaution for extra safety      Next Steps  Once your ApplicationSet controller is up and running  proceed to  Use Cases  Use Cases md  to learn more about the supported scenarios  or proceed directly to  Generators  Generators md  to see example  ApplicationSet  resources