# Git Providers

Git Providers integrate with Git hosting services to provide automatic repository authentication. Once configured, agents can clone, fetch, and push to repositories without manual credential management.

Provider configuration is stored in your coder setup repository alongside environment definitions, giving you version control and backup of your authentication settings.

## Provider Types

Each provider type has its own setup process. GitHub providers are created through an automated wizard in CoderFlow. Azure DevOps providers require manual setup in the Azure Portal before adding the provider in CoderFlow.

### GitHub

GitHub providers use GitHub Apps for authentication, providing fine-grained repository access without personal access tokens. CoderFlow automates the GitHub App creation process through a guided setup wizard.

#### Requirements

- You must be logged into GitHub before starting the setup wizard
- To install the app into an organization, you must be an **organization owner**

#### Supported Hosts

- **github.com** — Standard GitHub
- **GitHub Enterprise Cloud** — Hosted enterprise (*.ghe.com)
- **GitHub Enterprise Server** — Self-hosted enterprise instances

#### Permissions Requested

The GitHub App requests these permissions:
- **Contents** — Read and write (for clone/fetch/push)
- **Metadata** — Read-only (required by GitHub)
- **Pull requests** — Read and write
- **Issues** — Read and write
- **Statuses** — Read and write
- **Checks** — Read and write

For more details about GitHub Apps, see [About GitHub Apps](https://docs.github.com/en/apps/overview).

#### Setup Wizard

Navigate to **Settings → Server Settings → Git Providers** and click **Add Git Provider** to start the automated setup:

1. **Configure the provider**:
   - **Provider Name** — Identifier for this provider in CoderFlow
   - **App Name** — Name for the GitHub App (will appear in GitHub)
   - **Description** — Optional description shown on the GitHub App page
   - **GitHub Host** — Select github.com, GitHub Enterprise Cloud (ghe.com), or GitHub Enterprise Server
   - **Owner** — Organization or Personal account
   - **Organization Name** — Required if using an organization account

2. **Create the GitHub App**: Click "Create GitHub App" to be redirected to GitHub. Review the app permissions and click "Create GitHub App" on GitHub to approve.

3. **Install the App**: After creation, you'll be redirected to install the app. Choose **All repositories** or select specific repositories, then click **Install**.

4. **Complete**: CoderFlow automatically captures all credentials and creates the provider. You'll see a success message with the new provider details.

#### After Setup

Use **Test Connection** on the provider to verify the configuration. You can edit the provider later to view or update settings.

### Azure DevOps

Azure DevOps providers use Service Principals (App Registrations) with OAuth 2.0 client credentials flow for authentication. This supports both Azure DevOps Services (cloud) and Azure DevOps Server (on-premises).

#### Prerequisites

- An Azure subscription with access to Microsoft Entra ID (formerly Azure AD)
- Owner or admin access to your Azure DevOps organization
- Permissions to create App Registrations in Microsoft Entra ID

#### In Azure Portal: Create App Registration

1. Navigate to **Microsoft Entra ID -> App registrations**
2. Click **New registration**
3. Configure the application:
   - **Name** — A descriptive name (e.g., "CoderFlow Git Access")
   - **Supported account types** — "Single tenant only"
   - **Redirect URI** — Select **Web** and enter `https://{your-coderflow-host}/api/git-oauth/callback`
4. Click **Register**

After creation, note the **Application (client) ID** and **Directory (tenant) ID** from the app's Overview page.

#### In Azure Portal: Create Credentials

Choose one authentication method:

**Client Secret** (simpler setup)
1. In your App Registration, go to **Certificates & secrets -> Client secrets**
2. Click **New client secret**
3. Add a description and select expiration period
4. Click **Add** and copy the secret value immediately (it won't be shown again)

**Certificate** (more secure, recommended by Microsoft)
1. Generate a certificate with private key:
   ```
   openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=CoderFlow"
   cat cert.pem key.pem > combined.pem
   ```
2. In your App Registration, go to **Certificates & secrets -> Certificates**
3. Click **Upload certificate** and upload `cert.pem`
4. Keep `combined.pem` (certificate + private key) for CoderFlow configuration

#### In Azure Portal: Add API Permission

1. In your App Registration, navigate to **API permissions > Add a permission > Azure DevOps > Delegated > `user_impersonation`**
2. Confirm adding the permission

This permission enables both app-level access (service principal) and user-level access (User Credentials mode).

#### In Azure DevOps: Grant Access

1. Navigate to your Azure DevOps organization: `https://dev.azure.com/{org}`
2. Go to **Organization settings -> Users**
3. Click **Add users**
4. Search for your App Registration by name or client ID
5. Add it with the appropriate access level:
   - **Basic** — For read/write access to repositories
   - **Stakeholder** — For read-only access
6. Optionally, add the Service Principal to specific project teams for granular access

For more details, see [Use service principals in Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops)

The steps above correspond to the **Implementation guide** sections:
- **Step 1: Create your identity**
  - **Option A: Create a service principal (application registration)**
- **Step 2: Add the identity to Azure DevOps**
- **Step 3: Configure permissions**

#### In CoderFlow: Add the Provider

Navigate to **Settings → Git Providers** and click **Add Provider**. Configure these fields:

- **Name** — Identifier for this provider (lowercase, alphanumeric, hyphens)
- **Type** — Select "Azure DevOps"
- **Organization** — Your Azure DevOps organization name
- **Tenant ID** — Directory (tenant) ID from Azure Portal (GUID format)
- **Client ID** — Application (client) ID from Azure Portal (GUID format)
- **Authentication Method**:
  - **Client Secret** — Enter the secret value from Azure Portal
  - **Certificate** — Upload the PEM file containing both certificate and private key

After adding the provider, use **Test Connection** to verify the configuration.

## Using Providers in Environments

To add a repository using a Git Provider:

1. Open an environment and go to the **Repositories** tab
2. Click **Add Repository**
3. Select a **Git Provider** from the dropdown
4. Choose a repository from the list of repos the provider can access

See [Environments - Repositories](admin/environments.md#repositories) for more about repository configuration.

## Authentication

Once a repository is associated with a Git Provider, authentication is automatic in all contexts:

- **Builds** — Repositories are cloned automatically with credentials injected by the build system.
- **Tasks & Deployments** — A built-in credential helper provides credentials transparently. Git operations (clone, fetch, push) work without additional configuration.

Repositories with a Git Provider ignore any PAT secrets configured for the same host.

## Credential Modes

When adding a repository to an environment, you can choose how Git operations authenticate with the remote provider:

### App Credentials (Default)

Authenticates with the Git provider using the application identity (GitHub App or Azure DevOps Service Principal).

- All pushes appear in provider audit logs as the app
- Provider-side rules (branch protection, required reviewers) see the app as the actor
- Simplified setup—no per-user configuration needed

### User Credentials

Authenticates with the Git provider using the individual user's personal account via OAuth.

- Pushes appear in provider audit logs as the individual user
- Provider-side rules see the actual user as the actor—useful for branch protection policies that restrict who can push
- Requires users to connect their Git account before running tasks
**Note:** Commit authorship (the name and email in the git log) is always set to the CoderFlow user, regardless of credential mode. Credential mode only affects how CoderFlow authenticates when communicating with the remote provider.

To use User Credentials, users must first connect their Git account in **Profile Settings → Git Connections** (see [Connecting Your Git Account](#connecting-your-git-account)).

When a user attempts to run a task with User Credentials but hasn't connected their Git account, they'll be prompted to connect before the task can proceed.

## Connecting Your Git Account

Users can connect their personal Git accounts to use User Credentials mode:

1. Click your profile icon in the navigation bar
2. Select **Profile Settings**
3. In the **Git Connections** section, click **Connect** next to a provider
4. Authorize CoderFlow in the Git provider's OAuth flow
5. After authorization, you'll be returned to CoderFlow

Connected accounts can be disconnected at any time from the same screen. Disconnecting revokes the OAuth token—you'll need to reconnect to use User Credentials for that provider again.

**Note:** Only providers that support User OAuth appear in the Git Connections section.
