ado-connector

ado-connector

Authenticates against Azure DevOps and validates that the configured organisation, project, and (optionally) team are accessible before any iteration data is fetched.

Required Environment Variables

Variable	Description
ADO_ORG_URL	Azure DevOps organisation URL, e.g. https://dev.azure.com/your-org
ADO_PAT	Personal Access Token with Work Items (Read) scope

If either variable is missing, halt immediately:

ERROR: Azure DevOps authentication requires two environment variables:
  ADO_ORG_URL   — e.g. https://dev.azure.com/your-org
  ADO_PAT       — Personal Access Token with Work Items (Read) scope
                  Create at: dev.azure.com → User Settings → Personal Access Tokens

Run /sprint-init to verify your setup.

Authentication Method

Azure DevOps uses HTTP Basic Auth with an empty username and the PAT as the password. Base64-encode the string :{PAT} (note the leading colon):

Authorization: Basic base64(:{PAT})
Content-Type: application/json

Validation Steps

1. Validate org URL — check ADO_ORG_URL is a valid HTTPS URL
2. Validate project access — GET {orgUrl}/_apis/projects/{project}?api-version=7.1
   • HTTP 200 → project exists; capture id as projectId
   • HTTP 404 → halt: ERROR: Project '{project}' not found in organisation '{orgUrl}'. Check ado.project in .sprint-agent.json.
   • HTTP 401/403 → halt: ERROR: ADO_PAT does not have access to project '{project}'. Verify the token has Work Items (Read) scope.
3. Validate team access (only if team is configured) — GET {orgUrl}/{project}/_apis/teams/{team}?api-version=7.1
   • HTTP 200 → team exists; capture id as teamId
   • HTTP 404 → halt: ERROR: Team '{team}' not found in project '{project}'. Check ado.team in .sprint-agent.json.

For each validation failure, emit a specific error message that names the failing resource and where to fix it.

Output

{
  "authenticated": true,
  "orgUrl": "https://dev.azure.com/your-org",
  "project": "MyProject",
  "projectId": "abc-def-123",
  "team": "MyTeam",
  "teamId": "def-abc-456"
}

If team was not configured, team and teamId are null in the output.