github.com/argoproj/argo-cd/v3@v3.2.1/docs/operator-manual/webhook.md (about)

     1  # Git Webhook Configuration
     2  
     3  ## Overview
     4  
     5  Argo CD polls Git repositories every three minutes to detect changes to the manifests. To eliminate
     6  this delay from polling, the API server can be configured to receive webhook events. Argo CD supports
     7  Git webhook notifications from GitHub, GitLab, Bitbucket, Bitbucket Server, Azure DevOps and Gogs. The following explains how to configure
     8  a Git webhook for GitHub, but the same process should be applicable to other providers.
     9  
    10  !!! note
    11      The webhook handler does not differentiate between branch events and tag events where the branch and tag names are
    12      the same. A hook event for a push to branch `x` will trigger a refresh for an app pointing at the same repo with
    13      `targetRevision: refs/tags/x`.
    14  
    15  ## 1. Create The WebHook In The Git Provider
    16  
    17  In your Git provider, navigate to the settings page where webhooks can be configured. The payload
    18  URL configured in the Git provider should use the `/api/webhook` endpoint of your Argo CD instance
    19  (e.g. `https://argocd.example.com/api/webhook`). If you wish to use a shared secret, input an
    20  arbitrary value in the secret. This value will be used when configuring the webhook in the next step.
    21  
    22  To prevent DDoS attacks with unauthenticated webhook events (the `/api/webhook` endpoint currently lacks rate limiting protection), it is recommended to limit the payload size. You can achieve this by configuring the `argocd-cm` ConfigMap with the `webhook.maxPayloadSizeMB` attribute. The default value is 50MB.
    23  
    24  ### Github
    25  
    26  ![Add Webhook](../assets/webhook-config.png "Add Webhook")
    27  
    28  !!! note
    29      When creating the webhook in GitHub, the "Content type" needs to be set to "application/json". The default value "application/x-www-form-urlencoded" is not supported by the library used to handle the hooks
    30  
    31  ### Azure DevOps
    32  
    33  ![Add Webhook](../assets/azure-devops-webhook-config.png "Add Webhook")
    34  
    35  Azure DevOps optionally supports securing the webhook using basic authentication. To use it, specify the username and password in the webhook configuration and configure the same username/password in `argocd-secret` Kubernetes secret in
    36  `webhook.azuredevops.username` and `webhook.azuredevops.password` keys.
    37  
    38  ## 2. Configure Argo CD With The WebHook Secret (Optional)
    39  
    40  Configuring a webhook shared secret is optional, since Argo CD will still refresh applications
    41  related to the Git repository, even with unauthenticated webhook events. This is safe to do since
    42  the contents of webhook payloads are considered untrusted, and will only result in a refresh of the
    43  application (a process which already occurs at three-minute intervals). If Argo CD is publicly
    44  accessible, then configuring a webhook secret is recommended to prevent a DDoS attack.
    45  
    46  In the `argocd-secret` Kubernetes secret, configure one of the following keys with the Git
    47  provider's webhook secret configured in step 1.
    48  
    49  | Provider        | K8s Secret Key                   |
    50  |-----------------|----------------------------------|
    51  | GitHub          | `webhook.github.secret`          |
    52  | GitLab          | `webhook.gitlab.secret`          |
    53  | BitBucket       | `webhook.bitbucket.uuid`         |
    54  | BitBucketServer | `webhook.bitbucketserver.secret` |
    55  | Gogs            | `webhook.gogs.secret`            |
    56  | Azure DevOps    | `webhook.azuredevops.username`   |
    57  |                 | `webhook.azuredevops.password`   |
    58  
    59  Edit the Argo CD Kubernetes secret:
    60  
    61  ```bash
    62  kubectl edit secret argocd-secret -n argocd
    63  ```
    64  
    65  TIP: for ease of entering secrets, Kubernetes supports inputting secrets in the `stringData` field,
    66  which saves you the trouble of base64 encoding the values and copying it to the `data` field.
    67  Simply copy the shared webhook secret created in step 1, to the corresponding
    68  GitHub/GitLab/BitBucket key under the `stringData` field:
    69  
    70  ```yaml
    71  apiVersion: v1
    72  kind: Secret
    73  metadata:
    74    name: argocd-secret
    75    namespace: argocd
    76  type: Opaque
    77  data:
    78  ...
    79  
    80  stringData:
    81    # github webhook secret
    82    webhook.github.secret: shhhh! it's a GitHub secret
    83  
    84    # gitlab webhook secret
    85    webhook.gitlab.secret: shhhh! it's a GitLab secret
    86  
    87    # bitbucket webhook secret
    88    webhook.bitbucket.uuid: your-bitbucket-uuid
    89  
    90    # bitbucket server webhook secret
    91    webhook.bitbucketserver.secret: shhhh! it's a Bitbucket server secret
    92  
    93    # gogs server webhook secret
    94    webhook.gogs.secret: shhhh! it's a gogs server secret
    95  
    96    # azuredevops username and password
    97    webhook.azuredevops.username: admin
    98    webhook.azuredevops.password: secret-password
    99  ```
   100  
   101  After saving, the changes should take effect automatically.
   102  
   103  ### Alternative
   104  
   105  If you want to store webhook data in **another** Kubernetes `Secret`, instead of `argocd-secret`. ArgoCD knows to check the keys under `data` in your Kubernetes `Secret` starts with `$`, then your Kubernetes `Secret` name and `:` (colon).
   106  
   107  Syntax: `$<k8s_secret_name>:<a_key_in_that_k8s_secret>`
   108  
   109  > NOTE: Secret must have label `app.kubernetes.io/part-of: argocd`
   110  
   111  For more information refer to the corresponding section in the [User Management Documentation](user-management/index.md#alternative).
   112  
   113  ## Special handling for BitBucket Cloud
   114  BitBucket does not include the list of changed files in the webhook request body.
   115  This prevents the [Manifest Paths Annotation](high_availability.md#manifest-paths-annotation) feature from working with repositories hosted on BitBucket Cloud.
   116  BitBucket provides the `diffstat` API to determine the list of changed files between two commits.
   117  To address the missing changed files list in the webhook, the Argo CD webhook handler makes an API callback to the originating server.
   118  To prevent Server-side request forgery (SSRF) attacks, Argo CD server supports the callback mechanism only for encrypted webhook requests.
   119  The incoming webhook must include `X-Hook-UUID` request header. The corresponding UUID must be provided as `webhook.bitbucket.uuid` in `argocd-secret` for verification.
   120  The callback mechanism supports both public and private repositories on BitBucket Cloud.
   121  For public repositories, the Argo CD webhook handler uses a no-auth client for the API callback.
   122  For private repositories, the Argo CD webhook handler searches for a valid repository OAuth token for the HTTP/HTTPS URL.
   123  The webhook handler uses this OAuth token to make the API request to the originating server.
   124  If the Argo CD webhook handler cannot find a matching repository credential, the list of changed files would remain empty.
   125  If errors occur during the callback, the list of changed files will be empty.