Git (Azure DevOps) connection
================================

Field reference: :doc:`../providers/git_azure_provider`. A standard
``git`` connection (Airflow's built-in git type). Workload identity (no
secret at all) is a third option, but it's set up at the AKS/platform
level rather than per connection: see the field reference's
"Prerequisites" for that. For a connection you create yourself in the UI,
there are two flows:

- **PAT**: a Personal Access Token from an Azure DevOps user account.
- **Service principal**: an app registration onboarded as an Azure
  DevOps org member. It needs the **Basic** access level (Stakeholder
  doesn't have Git access), and, scoped to the target repository only
  (Project Settings → Repositories → ``<repo>`` → Security), not
  organization-wide, the **Reader** + **Code: Read** roles. It also needs
  the **View project-level information** permission, granted at the
  project level: Project Settings → Permissions → Users → search for the
  service principal → expand its entry → enable **View project-level
  information**. Without it, the clone authenticates but fails, because
  the bundle can't resolve the project the repository belongs to.

Steps
------

1. In the Airflow UI, open **Admin → Connections**, then click **+** to
   add a new connection.

.. TODO: screenshot of the empty Connections list with the "+" button
   highlighted

2. Set **Connection Id** (matching the DAG bundle config's expected
   connection, or your DAG's own ``conn_id``) and **Connection Type** to
   ``git``.

.. TODO: screenshot of the Connection Type dropdown with git selected

3. Set **Host** to the HTTPS repository URL
   (``https://dev.azure.com/<org>/<project>/_git/<repo>``).

   - **PAT**: fill in **Password** with the token, leave **Login** and
     **Extra** empty.
   - **Service principal**: fill in **Login** (client ID), **Password**
     (client secret), and **Extra** with ``{"tenant_id":
     "<tenant-id>"}`` — the ``tenant_id`` extra is what tells the hook
     to treat the password as a client secret instead of a PAT. Confirm
     the app registration has already been onboarded to the Azure
     DevOps org (Basic license), granted Code: Read on the repo, and
     granted View project-level information on the project (Project
     Settings → Permissions → Users → search for the service principal
     → expand its entry) before saving, or the connection will
     authenticate but fail to clone.

   Click **Save**.

.. TODO: screenshot of the filled-in git connection form before Save
   (PAT variant)

.. TODO: screenshot of the filled-in git connection form before Save
   (service principal variant)