@profoundlogic/coderflow-server 0.2.1

package/dist/web-ui/public/docs/README.md

@@ -0,0 +1,26 @@
+# CoderFlow Documentation
+
+CoderFlow runs AI coding agents in isolated containers to complete coding tasks on your repositories. You review the results and apply the changes you want.
+
+## Getting Started
+
+- [Overview](getting-started/overview.md) - What is CoderFlow and how it works
+- [Core Concepts](getting-started/core-concepts.md) - Environments, containers, and the task lifecycle
+
+## Using CoderFlow
+
+- [Objectives & Staging](objectives/working-with-objectives.md) - Plan work before execution
+- [Tasks](tasks/creating-tasks.md) - Create, run, and manage AI coding tasks
+- [Working with Code](code/files-and-editing.md) - Edit files, use terminal, VS Code, and CLI
+- [Testing](testing/application-servers.md) - Test your applications
+- [Templates](templates/task-templates.md) - Create reusable task templates
+
+## Integrations
+
+- [IBM i](integrations/ibmi/overview.md) - RAS, IBMiMake, and AI tools for IBM i
+
+## Administration
+
+- [Installation](admin/installation.md) - Set up the server
+- [Users & Roles](admin/users-and-roles.md) - Manage users and permissions
+- [Environments](admin/environments.md) - Configure your projects

package/dist/web-ui/public/docs/_sidebar.md

@@ -0,0 +1,47 @@
+- **Getting Started**
+  - [Overview](getting-started/overview.md)
+  - [Core Concepts](getting-started/core-concepts.md)
+
+- **Objectives & Staging**
+  - [Working with Objectives](objectives/working-with-objectives.md)
+  - [QA Mode](objectives/qa-mode.md)
+  - [Staged Tasks](objectives/staged-tasks.md)
+
+- **Tasks**
+  - [Creating Tasks](tasks/creating-tasks.md)
+  - [Task Groups & Variants](tasks/task-groups.md)
+  - [Providing Feedback](tasks/providing-feedback.md)
+  - [Winner Selection](tasks/winner-selection.md)
+  - [Judging](tasks/judging.md)
+  - [Approval & Deployment](tasks/approval-and-deployment.md)
+
+- **Working with Code**
+  - [Files & Editing](code/files-and-editing.md)
+  - [Terminal Access](code/terminal-access.md)
+  - [VS Code Extension](code/vscode-extension.md)
+  - [CLI](code/cli.md)
+
+- **Testing**
+  - [Testing Menu](testing/testing-menu.md)
+  - [Task Visualizations](testing/task-visualizations.md)
+  - [Profound Automated Testing](testing/profound-automated-testing.md)
+
+- **Templates**
+  - [Task Templates](templates/task-templates.md)
+  - [Template Examples](templates/template-examples.md)
+  - [Batch Processing](templates/batch-processing.md)
+
+- **Integrations**
+  - [Overview](integrations/overview.md)
+  - [IBM i](integrations/ibmi/overview.md)
+  - [Custom](integrations/custom.md)
+
+- **Administration**
+  - [Installation](admin/installation.md)
+  - [Users & Roles](admin/users-and-roles.md)
+  - [Single Sign-On](admin/sso.md)
+  - [Environments](admin/environments.md)
+  - [AI Providers](admin/ai-providers.md)
+  - [Git Providers](admin/git-providers.md)
+  - [Email Notifications](admin/email-notifications.md)
+  - [Skills](admin/skills.md)

package/dist/web-ui/public/docs/admin/ai-providers.md

@@ -0,0 +1,132 @@
+# AI Provider Authentication
+
+AI Provider Authentication connects CoderFlow to Claude (Anthropic), Codex (OpenAI), and Gemini (Google) using OAuth. This enables agents to run tasks using your existing subscriptions to these services without managing API keys.
+
+> **Note**: CoderFlow is completely functional using only OAuth authentication, but be aware that certain features like automatic task naming require at least one API key to be defined.
+
+## Overview
+
+CoderFlow supports multiple accounts per provider, allowing teams to:
+
+- Connect different accounts for different purposes (e.g., production vs. development)
+- Share provider access across the team without sharing credentials
+- Switch between accounts as needed
+- Automatically refresh tokens to maintain continuous access
+
+Provider authentication is configured globally and applies to all environments. The active account for each provider is used when launching tasks.
+
+## Connecting Accounts
+
+Navigate to **Settings → Provider Authentication** to manage AI provider accounts.
+
+### Adding an Account
+
+1. Click **Add Account** next to the provider you want to connect (Claude, Codex, or Gemini)
+2. Optionally enter a label to identify this account (e.g., "Production", "Team Account")
+3. Click **Start Sign-In** to open the provider's authentication page
+4. Complete the sign-in process in your browser:
+   - **Claude**: Sign in and copy the authorization code displayed
+   - **Codex/Gemini**: Sign in and copy the URL from your browser's address bar after the redirect
+5. Paste the code or URL into CoderFlow and click **Complete Sign-In**
+
+The account will appear in your provider list. If this is your first account for that provider, it becomes the active account automatically.
+
+### Account Labels
+
+Labels help identify accounts when you have multiple connected. Good label examples:
+- Production
+- Development
+- Team Shared
+- Personal
+
+If you don't provide a label, the account email address is used when available. For Claude (which doesn't expose email through OAuth), a timestamp-based label is generated.
+
+## Managing Accounts
+
+### Setting the Active Account
+
+The active account (marked with a green checkmark and "Active" badge) is used for all task execution with that provider.
+
+To change the active account, click the **checkmark button** next to the account you want to activate. The button only appears for non-active accounts.
+
+Changing the active account immediately affects new task launches. Running tasks continue using the account they started with.
+
+### Renaming Accounts
+
+1. Click the **Edit** (pencil) icon next to the account
+2. Enter a new label
+3. Click **Save**
+
+### Removing Accounts
+
+1. Click the **Delete** (trash) icon next to the account
+2. Confirm the removal
+
+If you remove the active account, the next account in the list becomes active. If no accounts remain, tasks using that provider will fail until a new account is connected.
+
+## Token Refresh
+
+OAuth tokens expire periodically. CoderFlow automatically refreshes tokens before they expire. Token refresh is managed by the Agent Keep-Alive service.
+
+To configure token refresh, navigate to **Settings → Agent Keep-Alive**:
+
+- **Enable/Disable**: Toggle automatic refresh for each provider
+- **Refresh Interval**: Set how often to check and refresh tokens (1-24 hours)
+- **Status**: View the last refresh time and next scheduled refresh
+
+Failed refreshes are retried up to 3 times. If token refresh fails repeatedly (e.g., if you revoked access from the provider), you may need to reconnect the account.
+
+## Provider-Specific Notes
+
+### Claude (Anthropic)
+
+- Uses Anthropic's OAuth flow with PKCE for security
+- Displays an authorization code that you copy back to CoderFlow
+- Email address is not available through OAuth (labels are especially useful)
+- Access includes Claude Code inference capabilities
+
+### Codex (OpenAI)
+
+- Uses OpenAI's OAuth flow with PKCE
+- Redirects to a URL that you copy back to CoderFlow
+- Email is extracted from the OAuth token
+- Provides access to ChatGPT subscription models
+
+### Gemini (Google)
+
+- Uses Google's standard OAuth flow
+- Redirects to a URL that you copy back to CoderFlow
+- Email is fetched from Google's user info endpoint
+- Requires Google Cloud Platform access
+
+## CLI Compatibility
+
+CoderFlow maintains compatibility with Claude Code, Codex CLI, and Gemini CLI by synchronizing the active account's credentials to the standard CLI credential files:
+
+- Claude: `~/.claude/.credentials.json`
+- Codex: `~/.codex/auth.json`
+- Gemini: `~/.gemini/oauth_creds.json`
+
+When you change the active account in CoderFlow, the CLI credential files are updated automatically. This allows you to use the CLI tools with the same account that CoderFlow is using.
+
+## Troubleshooting
+
+### "Provider not configured" Error
+
+This error appears when launching tasks if no account is connected for the required provider. Connect an account in **Settings → Provider Authentication**.
+
+### Authentication Expired
+
+If you see authentication errors during task execution:
+1. Check if the account still appears in Provider Authentication
+2. Try removing and re-adding the account
+3. Verify your subscription is still active with the provider
+
+### Token Refresh Failures
+
+Check the server logs for refresh errors. Common causes:
+- Provider subscription expired
+- Access revoked from provider's settings
+- Network connectivity issues
+
+Re-authenticate by removing and re-adding the account to get fresh tokens.

package/dist/web-ui/public/docs/admin/email-notifications.md

@@ -0,0 +1,69 @@
+# Email Notifications
+
+Email notifications allow CoderFlow to send messages when users are mentioned in comments or when others comment on their tasks and objectives.
+
+## Configuration
+
+Navigate to **Settings → Email** to configure SMTP settings:
+
+- **SMTP Host** — Your mail server hostname (e.g., `smtp.office365.com`)
+- **Port** — SMTP port (typically `587` for STARTTLS or `465` for SSL)
+- **Use SSL/TLS** — Enable for port 465; leave disabled for port 587 with STARTTLS
+- **Username** — SMTP authentication username
+- **Password** — SMTP authentication password
+- **From Address** — Email address shown as the sender
+- **From Name** — Display name shown alongside the sender address (optional)
+
+After entering your settings, use **Test Connection** to verify the SMTP server is reachable, then **Send Test Email** to confirm full delivery.
+
+## User Preferences
+
+Each user can control which notifications they receive via **Profile Settings → Email Notifications**:
+
+- **@Mentions** — Receive emails when mentioned in comments
+- **Comments on my tasks/objectives** — Receive emails when others comment on tasks or objectives you created
+
+Users must have an email address configured in their profile to receive notifications.
+
+## Provider-Specific Notes
+
+### Office 365
+
+Use `smtp.office365.com` on port `587` with SSL/TLS disabled (STARTTLS is used automatically). Ensure your account allows SMTP authentication — you may need to enable "Authenticated SMTP" in the Microsoft 365 admin center for the sending account.
+
+### Gmail
+
+Use `smtp.gmail.com` on port `587` with SSL/TLS disabled. Gmail requires an App Password rather than your regular account password. Generate one at [Google Account → Security → App Passwords](https://myaccount.google.com/apppasswords). You must have 2-Step Verification enabled.
+
+### SendGrid
+
+Use `smtp.sendgrid.net` on port `587`. The username is literally `apikey` and the password is your SendGrid API key.
+
+### AWS SES
+
+Use `email-smtp.<region>.amazonaws.com` on port `587` (replace `<region>` with your AWS region, e.g., `us-east-1`). SES SMTP credentials are different from your AWS access keys — generate them in the AWS SES console under "SMTP Settings".
+
+## Troubleshooting
+
+### Connection Timeout
+
+- Verify the SMTP host and port are correct
+- Check that your firewall or network allows outbound connections on the SMTP port
+- Some cloud providers block port 25; use port 587 or 465 instead
+
+### Authentication Failed
+
+- Verify your username and password are correct
+- For Gmail, ensure you're using an App Password, not your regular password
+- For Office 365, confirm SMTP authentication is enabled for the account
+
+### Emails Not Received
+
+- Check the recipient's spam/junk folder
+- Verify the From address is valid and authorized to send from your mail server
+- For SES, ensure the From address is verified in your SES configuration
+
+### Certificate Errors
+
+- If using a self-signed certificate on your mail server, you may need to configure your environment to trust it
+- Ensure your server's system time is correct, as certificate validation depends on accurate timestamps

package/dist/web-ui/public/docs/admin/environments.md

@@ -0,0 +1,215 @@
+# Environments
+
+An environment defines where agents work—the Docker image, repositories, tools, and configuration they need to complete tasks. Administrators manage environments through the Web UI.
+
+## Configuration Storage
+
+All environment configuration is stored in your organization's coder setup repository—a git repository that defines your CoderFlow installation. This includes Dockerfiles, setup scripts, agent instructions, templates, and environment settings.
+
+The Web UI provides a complete interface for managing this configuration:
+
+- **Save** — Write changes to disk without committing
+- **Discard** — Revert uncommitted changes
+- **Commit & Push** — Commit changes to git and push to the remote repository
+
+This workflow lets you experiment with configuration changes before committing them. The repository status shows uncommitted changes, and you can pull updates from the remote to stay in sync with your team.
+
+## Environment Configuration
+
+Navigate to **Environments** in the Web UI to create and configure environments. Each environment has the following tabs:
+
+### Overview
+
+Basic environment settings:
+- **Description** — What this environment is for
+- **Default Agent** — AI agent to use for tasks
+- **Docker Image** — Container image name
+- **Timezone** — Timezone for the environment
+- **Skills** — Skills assigned to this environment
+- **README** — Documentation displayed to users
+
+### Repositories
+
+Git repositories cloned into the environment. To add a repository, click **Add Repository** and choose one of:
+
+- **With Git Provider** — Select a [Git Provider](admin/git-providers.md) from the dropdown, then choose a repository from the list of repos the provider can access. Authentication is automatic for all Git operations (clone, fetch, push) in builds, tasks, and deployments.
+- **Manual Entry** — Enter a repository URL directly without selecting a provider. Use this for public repositories or when using [PAT secrets](#using-secrets-as-git-pat) for authentication.
+
+Repository settings:
+- **Branch** — Default branch to check out
+- **Allow Branch Selection** — Let users choose branches when creating tasks
+- **Path** — Where to clone the repository in the container
+
+### Application Server
+
+Configuration for running and testing applications:
+- **Start Command** — How to launch the application server
+- **Proxy URL** — URL for proxying requests to the application
+- **QA URL** — URL template for testing (supports placeholders)
+- **Authentication** — Credentials for accessing the application
+- **Ports** — Ports to expose from the container
+- **Launch URLs** — Quick links for testing the application
+
+### Agent Instructions
+
+The AGENTS.md file that guides AI agents working in this environment. This markdown file describes:
+- Project structure and architecture
+- Build and test commands
+- Coding conventions and patterns
+- Domain-specific knowledge agents need
+
+### Skills
+
+Skills are reusable prompt-based actions that agents can invoke during tasks. In the **Overview** tab, use **Manage Skills** to assign skills to the environment. Assigned skills are injected into every task launched in this environment, so agents have them available immediately.
+
+If you need different skills for different projects, create separate environments or update the assigned skill set before launching new tasks.
+
+### Files
+
+Configuration files that define the environment:
+- **Dockerfile** — How the Docker image is built
+- **setup.sh** — Initialization script run when containers start
+- **cleanup.sh** — Cleanup script run when tasks complete
+
+### Secrets
+
+Secrets store sensitive values like API keys, credentials, and certificates for use in builds, tasks, and deployments. They are also used to define non-sensitive environment values like external service URLs, ports, and so on.
+
+**Defining Secrets**
+
+Navigate to the environment's **Secrets** tab and click **Add Secret**:
+
+- **Name** — Identifier for the secret (letters, numbers, underscores)
+- **Type** — Value (literal string) or File (path to a file on the host)
+- **Available For** — Where the secret can be used: Build, Tasks, Deploy
+- **Expose As** — How to expose the secret in Tasks/Deploy contexts: environment variable or file mount
+- **Target** — Variable name (for env var) or container path (for file mount)
+
+**Secret Types**
+
+- **Value** — Stores literal strings such as API keys, passwords, or tokens. Can be exposed as an environment variable.
+- **File** — References a file on the host system such as SSH keys or certificates. Can be mounted read-only in containers.
+
+**Using Secrets in Tasks**
+
+Secrets with **Tasks** availability are injected when task containers start:
+
+- **Expose as environment variable** — The secret value becomes available as the specified variable name
+- **Expose as file** — The file is mounted read-only at the specified container path
+
+**Using Secrets in Builds**
+
+Secrets with **Build** availability are passed to Docker BuildKit during image builds. Access them in your Dockerfile using `--mount=type=secret`:
+
+```dockerfile
+RUN --mount=type=secret,id=my_secret cat /run/secrets/my_secret
+```
+
+For example, to use an `.npmrc` file during build:
+
+```dockerfile
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm install
+```
+
+To expose a secret as an environment variable:
+
+```dockerfile
+RUN --mount=type=secret,id=api_key,env=API_KEY ./configure.sh
+```
+
+See [Docker Build Secrets](https://docs.docker.com/build/building/secrets/) for more details.
+
+**Using Secrets in Deployments**
+
+Secrets with **Deploy** availability are injected when deployment scripts run:
+
+- **Expose as environment variable** — The secret value becomes available as the specified variable name in the deployment script
+- **Expose as file** — The file is mounted read-only at the specified container path during deployment
+
+This is useful for storing deployment credentials, SSH keys for remote servers, API tokens for deployment services, or configuration files specific to deployment targets (Base, QA, Production).
+
+**Using Secrets as Git PAT**
+
+A secret can provide Git authentication for HTTPS repositories. When adding a secret, check **Use as Git PAT** and specify a **Git Host** (e.g., `github.com`) to use the secret as a Personal Access Token for Git operations. The PAT applies to any repository under [Repositories](#repositories) that matches the hostname.
+
+PAT secrets can be either **Value** type (token entered directly) or **File** type (token read from a file on the host). Select **Available For** contexts as needed—Build, Tasks, or Deploy. PAT secrets do not require "Expose as" configuration.
+
+In **builds**, PAT credentials are available as the `git-credentials` build secret. Mount it to the standard Git credentials location:
+
+```dockerfile
+RUN --mount=type=secret,id=git-credentials,target=/root/.git-credentials \
+    git clone https://github.com/myorg/private-repo.git
+```
+
+In **task and deployment containers**, the PAT is automatically configured in the Git credential store.
+
+**Note:** PAT secrets are ignored for repositories that have a [Git Provider](admin/git-providers.md) configured.
+
+### Build
+
+Building and scheduling:
+- **Schedule** — Automatic rebuild interval (e.g., nightly)
+- **Build History** — Previous builds with status and duration
+- **Build Now** — Trigger an immediate rebuild
+
+For build-time secrets (SSH keys, tokens), see [Secrets / Env Vars](#secrets).
+
+Rebuild the environment after changing the Dockerfile, setup scripts, or dependencies.
+
+### Tests
+
+Test commands available in the Testing menu:
+- Define commands agents can run to verify their changes
+- Configure expected outputs or assertions
+
+### Templates
+
+Task templates for this environment:
+- Reusable task definitions with parameters
+- See **Templates** section for details
+
+### Deployment Profiles
+
+Deployment Profiles provide built-in CI/CD capabilities for deploying code to different targets.
+
+Each profile defines:
+- **Target** — Where code deploys (Base, QA, Production, etc.)
+- **Deployment script** — Commands to run (e.g., setting environment variables, running build tools)
+- **Credentials** — Separate authentication for each target
+
+Deployments aren't just for production—they're part of the regular workflow. For example, with IBM i development, after code is approved and pushed to repositories, a deployment compiles the changes to the base environment. Additional profiles can then deploy to QA or production systems.
+
+For IBM i environments, this includes setting the right library list and running `ibmimake` against the target system.
+
+Deployments can be triggered from the Web UI.
+
+## Creating Environments
+
+To create a new environment:
+1. Navigate to **Environments** in the Web UI
+2. Click **New Environment**
+3. Configure the basic settings
+4. Add repositories and set up the Dockerfile
+5. Build the environment
+
+## Building Environments
+
+After configuring an environment, build its Docker image from the Build tab. Click **Build Now** to trigger a build. The build history shows previous builds with their status and duration.
+
+For automation or command-line workflows, you can also build from the server:
+
+```bash
+coder-server build <env-name>
+```
+
+For automated workflows, scheduled rebuilds can pull the latest code and rebuild the image at regular intervals.
+
+### Base Image
+
+All environments build on top of a shared base image. Rebuild the base image to update agent CLIs (Claude Code, Codex, Gemini) to the latest version or after updating core dependencies. Use the **Build Base Image** option in **Settings → Environments → Actions**, or from the CLI:
+
+```bash
+coder-server build base
+```
+
+After rebuilding the base image, rebuild any environments that depend on it.

package/dist/web-ui/public/docs/admin/git-providers.md

@@ -0,0 +1,147 @@
+# 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**
+
+#### 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
+   - **Account Type** — 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** — "Accounts in this organizational directory only"
+   - **Redirect URI** — Leave blank (not needed for client credentials flow)
+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 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.