sdo - Simple DevOps Operations Tool¶

This page documents the sdo CLI tool. Use this page for detailed prerequisites, installation, usage examples, troubleshooting, and testing.

Overview¶

sdo (Simple DevOps Operations) is a modern CLI tool that provides unified operations for both work items and repositories across Azure DevOps and GitHub platforms. It parses backlog-style markdown files to create work items and offers comprehensive repository management capabilities.

Key Features¶

Work Item Creation: Parse markdown files and create GitHub issues or Azure DevOps work items (PBIs, Bugs, Tasks)
Repository Management: Create, list, show, and delete repositories on both platforms
Pull Request Management: Create, list, show, and update pull requests with work item linking
Pipeline Management: Create, run, monitor, and manage CI/CD pipelines across platforms
Multi-Platform Support: Seamless operations across Azure DevOps and GitHub
Dry-Run Previews: Preview operations before execution
Automatic Platform Detection: Detects platform from Git remote configuration

Prerequisites¶

Required Environment Variables¶

AZURE_DEVOPS_PAT - Personal Access Token for Azure DevOps API access
GITHUB_TOKEN - GitHub Personal Access Token (for GitHub operations)

Python Requirements¶

Python 3.8+
Dependencies listed in requirements.txt

Git Repository Context¶

The tool automatically detects Azure DevOps organization and project from the current Git remote configuration.

Installation¶

For detailed installation instructions, see SDO Installation.

Quick Installation (Virtual Environment)¶

# Navigate to NTools directory
cd "C:\Program Files\NBuild"

# Run the installer
python atools\install-sdo.py

Prerequisites¶

Python 3.8+
Administrative privileges (recommended)

Usage¶

Basic Command Structure¶

sdo [OPTIONS] COMMAND [ARGS]...

Global Options¶

-v, --verbose - Show detailed API error information
--version - Show version information

Work Item Operations¶

Create Work Item¶

sdo workitem create --file-path FILE_PATH [OPTIONS]

Options: - -f, --file-path PATH - Path to markdown file (required) - --dry-run - Parse and preview without creating

List Work Items¶

sdo workitem list [OPTIONS]

Lists work items with optional filtering. Works with both Azure DevOps and GitHub.

Options: - --type TYPE - Filter by work item type (PBI, Bug, Task, Spike, Epic) - --state STATE - Filter by state (New, Approved, Committed, Done, To Do, In Progress) - --assigned-to EMAIL - Filter by assigned user (email or display name) - --assigned-to-me - Filter by work items assigned to current user - --top INTEGER - Maximum number of items to return (default: 50) - -v, --verbose - Show detailed API information and URLs

Show Work Item¶

sdo workitem show --id ID [OPTIONS]

Shows detailed work item information including acceptance criteria.

Options: - --id INTEGER - Work item ID (required) - -c, --comments - Show comments/discussion - -v, --verbose - Show full API response

Update Work Item¶

sdo workitem update --id ID [OPTIONS]

Updates work item fields.

Options: - --id INTEGER - Work item ID (required) - --title TEXT - Update title - --description TEXT - Update description - --assigned-to EMAIL - Update assigned user (email or display name) - --state STATE - Update state (New, Approved, Committed, Done, To Do, In Progress) - -v, --verbose - Show full API response

Add Comment to Work Item¶

sdo workitem comment --id ID --text TEXT [OPTIONS]

Adds a comment to a work item or issue.

Options: - --id INTEGER - Work item ID (required) - --text TEXT - Comment text (required) - -v, --verbose - Show full API response

Repository Operations¶

Create Repository¶

sdo repo create [OPTIONS]

Creates a new repository in the current project/organization.

Options: - -v, --verbose - Show detailed API information

List Repositories¶

sdo repo ls [OPTIONS]

Lists all repositories in the current project/organization.

Options: - -v, --verbose - Show detailed API information

Show Repository¶

sdo repo show [OPTIONS]

Shows detailed information about the current repository.

Options: - -v, --verbose - Show detailed API information

Delete Repository¶

sdo repo delete [OPTIONS]

Deletes the current repository (with confirmation prompt).

Options: - -v, --verbose - Show detailed API information

Examples¶

Work Item Operations¶

Create Work Item¶

Dry Run (Preview)¶

sdo workitem create --file-path "atools/issue-azdo-example.md" --dry-run

Create Azure DevOps Work Item¶

sdo workitem create --file-path "atools/issue-azdo-example.md"

Create with Verbose Output¶

sdo workitem create --file-path "atools/issue-azdo-example.md" --verbose

List Work Items¶

# List all work items
sdo workitem list

# List only PBIs in "New" state
sdo workitem list --type PBI --state New

# List work items assigned to you
sdo workitem list --assigned-to-me

# List tasks in progress with verbose output
sdo workitem list --type Task --state "In Progress" --verbose

# List top 10 work items
sdo workitem list --top 10

Show Work Item¶

# Show work item details
sdo workitem show --id 123

# Show work item with comments
sdo workitem show --id 123 --comments

# Show with verbose API response
sdo workitem show --id 123 --verbose

Update Work Item¶

# Update work item state
sdo workitem update --id 123 --state "In Progress"

# Update title and description
sdo workitem update --id 123 --title "New Title" --description "Updated description"

# Assign work item to user
sdo workitem update --id 123 --assigned-to "user@example.com"

# Update multiple fields
sdo workitem update --id 123 --state Done --assigned-to "user@example.com" --verbose

Add Comment¶

# Add a comment to work item
sdo workitem comment --id 123 --text "This is a test comment"

# Add comment with verbose output
sdo workitem comment --id 123 --text "Completed testing" --verbose

Repository Operations¶

Create Repository¶

sdo repo create
sdo repo create --verbose

List Repositories¶

sdo repo ls
sdo repo list  # Alternative command

Show Repository Details¶

sdo repo show
sdo repo show --verbose

Delete Repository¶

sdo repo delete  # Will prompt for confirmation

Pull Request Operations¶

Create Pull Request¶

sdo pr create [OPTIONS]

Creates a new pull request from a markdown file.

Options: - -f, --file PATH - Path to markdown file containing PR details (required) - --work-item INTEGER - Work item ID to link to the pull request (required) - --draft - Create as draft pull request - --dry-run - Parse and preview PR creation without creating it - -v, --verbose - Show detailed API information and responses

Examples:

# Create PR with dry-run preview
sdo pr create -f pr-description.md --work-item 123 --dry-run

# Create draft PR
sdo pr create -f pr-description.md --work-item 123 --draft

# Create PR with verbose output
sdo pr create -f pr-description.md --work-item 123 --verbose

List Pull Requests¶

sdo pr ls [OPTIONS]

Lists pull requests in the current repository.

Options: - --status STATUS - Filter by status (active, completed, abandoned) [default: active] - --top INTEGER - Maximum number of PRs to show [default: 10] - -v, --verbose - Show detailed API information

Examples:

# List active PRs
sdo pr ls

# List completed PRs
sdo pr ls --status completed

# List with custom limit
sdo pr ls --top 20

# List with verbose output
sdo pr ls --verbose

Show Pull Request Details¶

sdo pr show PR_NUMBER [OPTIONS]

Shows detailed information about a specific pull request.

Options: - -v, --verbose - Show detailed API information

Examples:

# Show PR details
sdo pr show 123

# Show PR with verbose API details
sdo pr show 123 --verbose

Check Pull Request Status¶

sdo pr status PR_NUMBER [OPTIONS]

Shows the current status of a specific pull request including CI/CD check results.

Displays: - PR status (open, closed, merged, etc.) - Title, author, and branch information - CI/CD checks status (GitHub and Azure DevOps) - Check results with pass/fail indicators and URLs

Options: - -v, --verbose - Show detailed API information

Examples:

# Check PR status with CI/CD checks
sdo pr status 123

# Check PR status with verbose details
sdo pr status 123 --verbose

Update Pull Request¶

sdo pr update [OPTIONS]

Updates an existing pull request.

Options: - --pr-id INTEGER - Pull request ID to update (required) - -f, --file PATH - Path to markdown file with updated PR details - -t, --title TEXT - New title for the PR - --status STATUS - New status (active, abandoned, completed) - -v, --verbose - Show detailed API information

Examples:

# Update PR title
sdo pr update --pr-id 123 --title "Updated PR Title"

# Update PR from markdown file
sdo pr update --pr-id 123 --file updated-pr.md

# Update PR status to completed
sdo pr update --pr-id 123 --status completed

Examples¶

Pull Request Operations¶

Create Pull Request from Markdown¶

sdo pr create -f pr-description.md --work-item 208

Preview PR Creation¶

sdo pr create -f pr-description.md --work-item 208 --dry-run

List Recent Pull Requests¶

sdo pr ls --top 5

Show Pull Request Details¶

sdo pr show 211

Check Pull Request Status¶

sdo pr status 211

Output includes CI/CD checks:

✅ PR #211: MERGED
Title: [208] Implement Comprehensive Pull Request Management for SDO CLI
Author: naz-hage
Branch: gh-208 → main

CI/CD Checks:
Python Tests    pass    27s     https://github.com/naz-hage/ntools/actions/runs/...
Publish Docs    pass    13s     https://github.com/naz-hage/ntools/actions/runs/...
Running a workflow (Release)    pass    3m24s   https://github.com/naz-hage/ntools/actions/runs/...

Update Pull Request¶

sdo pr update --pr-id 211 --title "Updated: Implement PR Management"

Pipeline Operations¶

Create Pipeline¶

sdo pipeline create [OPTIONS]

Creates a new pipeline/workflow in the current project.

Options: - -v, --verbose - Show detailed API information

Examples:

sdo pipeline create
sdo pipeline create --verbose

How Pipeline Creation Works¶

The sdo pipeline create command automatically detects your platform and creates pipelines differently for each:

Azure DevOps Pipeline Creation¶

What it does: 1. Validates YAML file exists locally - Checks that the pipeline YAML file exists before creating the pipeline definition 2. Auto-detects configuration from your Git remote: - Organization: your-org - Project: your-project - Repository: your-repo - Pipeline Name: your-repo (same as repository name) - YAML Path: .azure-pipelines/azurepipeline.yml - Folder: \ (root folder)

Creates the pipeline using Azure DevOps REST API
Links to existing YAML file in your repository

Prerequisites: - Repository must contain a pipeline YAML file at .azure-pipelines/azurepipeline.yml - AZURE_DEVOPS_PAT environment variable must be set - User must have "Edit build pipeline" permissions

What happens during creation:

✅ Detected Azure DevOps repository:
   Organization: contoso
   Project: my-project
   Repository: my-app
   Pipeline Name: my-app
   Pipeline YAML Path: .azure-pipelines/azurepipeline.yml
   Pipeline Folder: \

✅ Pipeline YAML file found: .azure-pipelines/azurepipeline.yml
Creating pipeline 'my-app'...
✅ Pipeline created successfully!
   ID: 12345
   Name: my-app
   URL: https://dev.azure.com/contoso/my-project/_build?definitionId=12345
   Folder: \

Error if YAML file missing:

❌ Pipeline YAML file not found: .azure-pipelines/azurepipeline.yml
Please create the pipeline YAML file before creating the pipeline definition.

Example YAML file structure:
  .azure-pipelines/azurepipeline.yml
  trigger:
  - main

  pool:
    vmImage: 'ubuntu-latest'

  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

GitHub Actions Workflow Creation¶

Important: SDO does not create GitHub workflow files automatically.

What it does: - Checks for existing workflows in .github/workflows/ directory - Lists existing workflow files if any are found - Provides guidance for manual workflow creation

Manual creation steps: 1. Create the workflows directory:

mkdir -p .github/workflows

Create a workflow YAML file (e.g., ci.yml):

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Run a one-line script
      run: echo Hello, world!

Commit and push the workflow file:

git add .github/workflows/ci.yml
git commit -m "Add CI workflow"
git push

SDO output for GitHub (no existing workflows):

GitHub Actions workflows are created by adding YAML files to .github/workflows/
SDO does not create workflow files automatically.

To create a workflow:
1. Create the directory: mkdir -p .github/workflows
2. Add a workflow YAML file (e.g., ci.yml)
3. Commit and push the changes

Example workflow file (.github/workflows/ci.yml):
  name: CI
  on:
    push:
      branches: [ main ]
    pull_request:
      branches: [ main ]
  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: echo 'Add your test commands here'

SDO output for GitHub (with existing workflows):

GitHub Actions workflows found in your repository:
  • ntools.yml
  • ci.yml

Your repository already has workflow files.
To create additional workflows, add more YAML files to .github/workflows/
and commit/push them to trigger GitHub Actions.

SDO output for GitHub (no existing workflows):

GitHub Actions workflows are created by adding YAML files to .github/workflows/
SDO does not create workflow files automatically.

To create a workflow:
1. Create the directory: mkdir -p .github/workflows
2. Add a workflow YAML file (e.g., ci.yml)
3. Commit and push the changes

Example workflow file (.github/workflows/ci.yml):
  name: CI
  on:
    push:
      branches: [ main ]
    pull_request:
      branches: [ main ]
  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: echo 'Add your test commands here'

Platform Detection¶

SDO automatically detects your platform from Git remote URLs:

Azure DevOps URLs: - https://dev.azure.com/organization/project/_git/repository - https://organization@dev.azure.com/organization/project/_git/repository

GitHub URLs: - https://github.com/owner/repository.git - git@github.com:owner/repository.git

Common Issues¶

Azure DevOps Issues: - "YAML file not found": Ensure .azure-pipelines/azurepipeline.yml exists in your repository - "Access denied": Check PAT permissions include "Build (Read & execute)" - "Pipeline already exists": Pipeline with that name already exists (command exits successfully)

GitHub Issues: - Manual process required: GitHub workflows cannot be created via API - File naming: Use lowercase with hyphens (e.g., ci.yml, not CI.yml)

Pipeline Naming Convention¶

Azure DevOps: Pipeline name defaults to repository name GitHub: Workflow name comes from the name: field in YAML or filename

Security Considerations¶

Azure DevOps PAT requires appropriate permissions
GitHub workflows run with repository permissions
YAML files should be reviewed before committing

List Pipelines¶

sdo pipeline ls [OPTIONS]

Lists pipelines in the current project or repository.

Options: - --repo REPO - Filter pipelines by repository name - --all - Show all pipelines in the project (default: current repository only) - -v, --verbose - Show detailed API information

Examples:

# List pipelines for current repository
sdo pipeline ls

# List pipelines for specific repository
sdo pipeline ls --repo my-repo

# List all pipelines in project
sdo pipeline ls --all

# List with verbose output
sdo pipeline ls --verbose

Show Pipeline¶

sdo pipeline show [OPTIONS]

Shows detailed information about the current pipeline.

Options: - -v, --verbose - Show detailed API information

Examples:

sdo pipeline show
sdo pipeline show --verbose

Delete Pipeline¶

sdo pipeline delete [OPTIONS]

Deletes the current pipeline (with confirmation prompt).

Options: - -v, --verbose - Show detailed API information

Examples:

sdo pipeline delete  # Will prompt for confirmation

Run Pipeline¶

sdo pipeline run [PIPELINE_NAME] --branch BRANCH [OPTIONS]

Runs a pipeline on the specified branch.

Arguments: - PIPELINE_NAME - Name of pipeline to run (optional, uses current repository pipeline if not specified)

Options: - -b, --branch BRANCH - Branch to run pipeline on (required) - -v, --verbose - Show detailed API information

Examples:

# Run current repository pipeline on main branch
sdo pipeline run --branch main

# Run specific pipeline on develop branch
sdo pipeline run my-pipeline --branch develop

# Run with verbose output
sdo pipeline run --branch main --verbose

Check Pipeline Status¶

sdo pipeline status [BUILD_ID] [OPTIONS]

Shows the status of a pipeline build/run.

Arguments: - BUILD_ID - Specific build ID to check (optional, shows latest if not specified)

Options: - -v, --verbose - Show detailed API information

Examples:

# Show latest build status
sdo pipeline status

# Show specific build status
sdo pipeline status 12345

# Show with verbose API details
sdo pipeline status 12345 --verbose

Show Pipeline Logs¶

sdo pipeline logs [BUILD_ID] [OPTIONS]

Shows logs for a pipeline build/run.

Arguments: - BUILD_ID - Build ID to get logs for (required)

Options: - --build-id BUILD_ID - Alternative way to specify build ID - -v, --verbose - Show detailed API information

Examples:

# Show logs for build ID 12345
sdo pipeline logs 12345

# Alternative syntax
sdo pipeline logs --build-id 12345

# Show with verbose output
sdo pipeline logs 12345 --verbose

Show Last Build¶

sdo pipeline lastbuild [OPTIONS]

Shows information about the last build of the current pipeline.

Options: - -v, --verbose - Show detailed API information

Examples:

sdo pipeline lastbuild
sdo pipeline lastbuild --verbose

Update Pipeline¶

sdo pipeline update [OPTIONS]

Checks if the pipeline configuration needs updating and provides guidance.

Options: - -v, --verbose - Show detailed API information

Examples:

sdo pipeline update
sdo pipeline update --verbose

Examples¶

Pipeline Operations¶

Create Pipeline¶

sdo pipeline create

List Pipelines¶

# List all pipelines for current repository
sdo pipeline ls

# List all pipelines in project
sdo pipeline ls --all

Run Pipeline¶

# Run pipeline on main branch
sdo pipeline run --branch main

# Run specific pipeline
sdo pipeline run ci-pipeline --branch feature-branch

Check Pipeline Status¶

# Check latest build status
sdo pipeline status

# Check specific build
sdo pipeline status 12345

View Pipeline Logs¶

# View logs for build 12345
sdo pipeline logs 12345

Show Last Build Information¶

sdo pipeline lastbuild

Markdown File Format¶

SDO expects markdown files with specific metadata headers. See the example files:

Azure DevOps Examples: - issue-azdo-bug-example.md - Bug work item format - issue-azdo-task-example.md - Task work item format - issue-azdo-pbi-example.md - Product Backlog Item format - issue-azdo-epic-example.md - Epic work item format

GitHub Examples: - issue-gh-example.md - GitHub issue format

Required Metadata¶

# Issue Title

## Target: azdo|github
## Type: PBI|Bug|Task|Issue
## Project: ProjectName (for Azure DevOps)

Description content here...

Supported Platforms¶

Azure DevOps¶

Work Item Types: Product Backlog Item (PBI), Bug, Task
Work Item Fields: Title, Description, Area Path, Iteration Path, Priority, Effort
Repository Operations: Create, List, Show, Delete repositories
Pull Request Operations: Create, List, Show, Update pull requests with work item linking
Pipeline Operations: Create, Run, Monitor, Update CI/CD pipelines
Authentication: Personal Access Token (PAT)
API: REST API integration
Automatic: Organization/Project detection from Git remote

GitHub¶

Work Item Types: Issues
Work Item Fields: Title, Description, Labels, Assignees
Repository Operations: Create, List, Show, Delete repositories
Pull Request Operations: Create, List, Show, Update pull requests with issue references
Pipeline Operations: Run, Monitor GitHub Actions workflows
Authentication: GitHub CLI (gh) or Personal Access Token
API: GitHub CLI integration for repositories, REST API for work items and PRs
Automatic: Repository detection from Git remote

Error Handling¶

SDO provides clear error messages for common issues:

Authentication: Missing or invalid PAT tokens
File Access: Markdown file not found or unreadable
API Errors: Azure DevOps/GitHub API failures
Validation: Missing required metadata fields

Use --verbose flag for detailed error information including API responses.

Testing¶

Run All Tests¶

cd atools
python -m pytest tests/

Test Categories¶

Unit Tests: Core functionality validation
Integration Tests: API interaction testing
CLI Tests: Command-line interface validation
Error Path Tests: Failure scenario handling

Test Coverage¶

All major functionality is tested with comprehensive test cases covering: - Work item creation workflows - Repository management operations - Pull request management operations (create, list, show, update) - Pipeline management operations (create, run, monitor, update) - Multi-platform API integrations - Error handling and validation - CLI command interfaces - Markdown parsing and metadata extraction - Platform-specific operations - Error handling scenarios - CLI argument parsing

Troubleshooting¶

Common Issues¶

Authentication Failures¶

Error: Authentication failed. Check your AZURE_DEVOPS_PAT token.

Solution:

# Set PAT token
export AZURE_DEVOPS_PAT="your-token-here"

# Verify token has required permissions
# Azure DevOps: Work Items (Read/Write), Project (Read)
# GitHub: Issues (Read/Write), Repository (Read)

Git Remote Configuration¶

Error: Unable to detect Azure DevOps organization from Git remote

Solution:

# Check current remote
git remote -v

# Should show Azure DevOps URL like:
# origin  https://dev.azure.com/organization/project/_git/repo (fetch)

File Format Issues¶

Error: Missing required metadata: target

Solution: Ensure markdown file includes required headers:

## Target: azdo
## Type: PBI

Debug Mode¶

Enable verbose output for detailed troubleshooting:

sdo --verbose workitem create --file-path file.md

This shows: - API request/response details - File parsing results - Authentication status - Full error stack traces

Architecture¶

SDO is built with a modular architecture:

cli.py - Click-based command interface
client.py - Azure DevOps REST API client
work_items.py - Business logic for work item operations
pull_requests.py - Business logic for pull request operations
pipelines.py - Business logic for pipeline operations
platforms/ - Platform-specific implementations (GitHub, Azure DevOps)
github_pr_platform.py - GitHub pull request operations
azdo_pr_platform.py - Azure DevOps pull request operations
parsers/ - Markdown parsing and metadata extraction

Development¶

Code Quality¶

SDO maintains high code quality standards: - Linting: flake8 with comprehensive rules - Testing: 34 test cases with high coverage - Type Hints: Full type annotation support - Documentation: Comprehensive docstrings

Contributing¶

Follow existing code patterns
Add tests for new functionality
Update documentation
Run full test suite before submitting