Skip to content

copilot-instructions.md

Latest commit

 

History

History
193 lines (152 loc) · 15.9 KB

copilot-instructions.md

File metadata and controls

193 lines (152 loc) · 15.9 KB
Raw

GitHub Copilot Custom Instructions for Android Multi-Repo Project

These instructions guide GitHub Copilot to provide suggestions and responses aligned with our Android project's conventions, architecture, and coding style, specifically addressing our multi-repository setup and language transition.

1. Repository Structure & Architecture

1.1 Repository Organization

The android-complete repository contains multiple sub-repositories as separate modules:

  • MSAL - Microsoft Authentication Library for client applications
  • ADAL - Azure Active Directory Authentication Library (legacy)
  • Broker - Brokered authentication service
  • Common - Shared utilities, helpers, and IPC logic
  • OneAuth - Library owned by another team (consumed by 1P apps like Teams, Outlook)
  • Authenticator - Microsoft Authenticator Android application (consumes SDK library releases)
  • 1ES-Pipelines - Production CI/CD pipeline YAML (releases, hotfixes, validation, publishing)

Important: When asked a question, always search across ALL repositories (including Authenticator when relevant) to provide comprehensive answers. Code may be duplicated or shared across these sub-repos.

1.2 Authentication Flow Architecture

Request Flow:

Client App (Teams/Outlook/etc.)
    ↓
MSAL or OneAuth (entry point)
    ↓
Common (IPC layer - sends request to Broker)
    ↓
Broker (processes authentication request)
    ↓
eSTS (Microsoft token service)
    ↓
Broker (receives token response)
    ↓
Common (IPC layer - returns response)
    ↓
MSAL or OneAuth
    ↓
Client App

Key Flow Details:

  • MSAL/OneAuth → Common → Broker → eSTS → Broker → Common → MSAL/OneAuth
  • Entry Points: Requests like AcquireToken or AcquireTokenSilent typically start from MSAL or OneAuth
  • OneAuth Specifics: OneAuth is consumed by 1P Microsoft apps (Teams, Outlook, etc.). We don't own this code. OneAuth flows start by calling methods from the BrokerMsalController class
  • Common Module: Contains all IPC (Inter-Process Communication) logic. MSAL/OneAuth use Common layer to send requests to Broker over IPC
  • Broker Module: Handles the actual authentication logic, communicates with eSTS, and returns tokens

1.3 DRI Copilot MCP Server

DRI Copilot MCP tools are available for querying documentation, TSGs, and past incidents:

  • Broker DRI Copilot (tools containing Broker_DRI_Copilot) - For Broker-related questions, PRT, device registration, brokered auth flows

For incident investigations: Use the incident-investigator skill (located at .github/skills/incident-investigator/SKILL.md) which provides a comprehensive workflow for IcM/customer-reported issues.

2. Core Principles

  • Primary Language for New Code: All new code and new files must be written in Kotlin.
  • Existing Language: Recognize that existing files predominantly use Java. When interacting with or modifying existing Java files, maintain the Java style.
  • Asynchronous Operations: Use Kotlin Coroutines for all asynchronous and background operations. Leverage structured concurrency.

3. Repository Specific Guidelines

  • MSAL (Microsoft Authentication Library): The Microsoft Authentication (MSAL) repo contains code for MSAL library which enables developers to acquire security tokens from the Microsoft identity platform to authenticate users and access secured web APIs. This is a client-side library consumed by app developers.
  • Broker: This repo is involved in brokered authentication. It uses inter-app communication. Copilot should be aware of IPC mechanisms, custom intents, and secure communication patterns relevant to a broker. Broker receives requests from MSAL/OneAuth via Common layer.
  • Common: This repo holds shared utilities, helper functions, and all IPC logic. MSAL/OneAuth use this layer to communicate with Broker. Suggestions in this context should aim for reusability and generality.
  • ADAL (Azure Active Directory Authentication Library): Similar to MSAL, this is an authentication library, potentially an older version or specific to certain flows. When working in ADAL context, align with its patterns.
  • OneAuth: Third-party library owned by another team (not us). Consumed by 1P Microsoft apps like Teams, Outlook, etc. OneAuth flows start by calling BrokerMsalController class methods.
  • Authenticator (Microsoft Authenticator): The Authenticator repo contains the Microsoft Authenticator Android application. It is a multi-module Gradle project rooted at authenticator/PhoneFactor/. Authenticator consumes SDK library releases from MSAL, Common, and Broker as dependencies. Key modules include:
    • MSAuthenticator (authenticator/PhoneFactor/app) — Main app entry point (MainActivity, UI, lifecycle)
    • MfaLibrary (authenticator/PhoneFactor/MfaLibrary) — MFA SDK: push notifications, PIN encryption, device-notification validation
    • CtapLibrary (authenticator/PhoneFactor/CtapLibrary) — FIDO2/CTAP passkey management: storage, registration, assertion
    • SharedCoreLibrary (authenticator/PhoneFactor/SharedCoreLibrary) — Core crypto, encryption, shared utilities
    • SecureKeystoreLibrary (authenticator/PhoneFactor/SecureKeystoreLibrary) — Secure key-pair generation (ECC/RSA) and Keystore access
    • NgcProviderLibrary (authenticator/PhoneFactor/NgcProviderLibrary) — NGC key provider: Android Keystore-backed credential management
    • AadRemoteNgcLibrary (authenticator/PhoneFactor/AadRemoteNgcLibrary) — AAD NGC: remote passwordless key registration/deletion
    • CommonUiLibrary (authenticator/PhoneFactor/CommonUiLibrary) — Shared UI components, dialogs, View extensions
    • BastionLibrary (authenticator/PhoneFactor/BastionLibrary) — Bastion validation for secure auth flows
    • GraphClient (authenticator/PhoneFactor/GraphClient) — Microsoft Graph API client for auth methods policy
    • ExperimentationLibrary (authenticator/PhoneFactor/ExperimentationLibrary) — ECS feature-flag provider integration
    • MsaAccountLibrary (authenticator/PhoneFactor/MsaAccountLibrary) — MSA ticket acquisition and account operations
    • WalletLibrary (authenticator/PhoneFactor/WalletLibrary/walletlibrary) — Entra Verified ID wallet
    • VerifiableCredential-SDK (authenticator/PhoneFactor/VerifiableCredential-SDK/sdk) — DID SDK: verifiable credential issuance/presentation
    • LocationLibrary (authenticator/PhoneFactor/LocationLibrary) — GPS-signal UI for conditional-access scenarios
    • RootDetectionLibrary (authenticator/PhoneFactor/RootDetectionLibrary) — Rooted device detection and telemetry
    • ScanQrCodeLibrary (authenticator/PhoneFactor/ScanQrCodeLibrary) — QR code scanning
    • AuthenticatorPolicyChannel (authenticator/PhoneFactor/AuthenticatorPolicyChannel) — Credential policy enforcement
    • AuthenticatorSignalsLibrary (authenticator/PhoneFactor/AuthenticatorSignalsLibrary) — Credential history signals for risk assessment
    • SilentNotificationChannelLibrary (authenticator/PhoneFactor/SilentNotificationChannelLibrary) — Silent push for background MFA approval
    • NativeLibrary (authenticator/PhoneFactor/NativeLibrary) — Native crash reporting via Breakpad
    • TestUtilitiesLibrary / AndroidTestUtilitiesLibrary — Unit and instrumented test helpers
    • uiautomator-tests (authenticator/PhoneFactor/uiautomator-tests) — UI Automator E2E smoke tests Authenticator is an opt-in submodule (controlled by includeAuthenticatorApp=true in gradle.properties or local.properties). When working in Authenticator context, note that it has its own build conventions, dependencies, and Kotlin/Java mix.
  • 1ES-Pipelines (AuthClientAndroidPipelines): This directory contains all 1ES-compliant production pipeline YAML for the Android Auth platform. It includes monthly release orchestrators, hotfix pipelines, daily validation, internal/external publishing, and reusable YAML templates. Files are organized into production/, non-production/, scripts/, and templates/ directories. This is NOT the same as azure-pipelines/ which contains legacy/deprecated pipeline code. When modifying pipelines, always work in 1ES-Pipelines/. All pipeline code is YAML. See the release-helper skill for detailed pipeline documentation.

Important: When generating code that interacts across these repositories (e.g., calling a function from common in MSAL, or consuming SDK APIs from Authenticator), ensure the generated code respects the language and API boundaries of each repository.

4. Naming Conventions & Style (Kotlin First)

  • Kotlin Style Guide: Follow the official Kotlin Coding Conventions and Google's Kotlin Style Guide.
  • Variables: Prefer val over var wherever immutability is possible.
  • Functions: Use expression bodies for single-expression functions.
  • Classes:
    • Use data class for simple data holders.
  • Visibility: Limit visibility of classes, functions, and variables to the minimum required (e.g., private, internal).

5. Android Components (Kotlin/Compose context)

  • Activities: Minimal logic in Activities; primarily used as entry points.
  • Services/Broadcast Receivers: Use as sparingly as possible. Prefer Kotlin Coroutines and Flow for background processing and inter-component communication where modern alternatives exist.

6. Testing

  • Unit Tests: Write comprehensive unit tests for Kotlin logic using JUnit 4/5 and Mockito/MockK.
  • Instrumented Tests: Use Espresso for UI tests in Android components.
  • Test Coverage: Aim for high test coverage, especially for new code.

7. Code Documentation & Comments

  • KDoc: Provide KDoc comments for all public Kotlin classes, functions, and properties.
  • JavaDoc: When modifying existing Java code, ensure JavaDoc comments are maintained and updated.
  • Conciseness: Comments should explain why something is done, not just what it does.
  • TODOs: Use TODO comments for incomplete tasks that need to be addressed.
  • Copywriting: Ensure all comments are clear, concise, and free of spelling/grammar errors. Every new file generated or added should have copyright information on top of the file.

8. Logging

  • Custom Logger: Always use the Logger class for all logging purposes. Avoid using android.util.Log or other direct logging frameworks.
  • Sensitive Data: Never log sensitive information (e.g., personal identifiable information, tokens, passwords).

9. Interoperability

  • When writing new Kotlin code that needs to interact with existing Java code, use Kotlin's interoperability features effectively and safely.
  • When suggesting refactors of Java code to Kotlin, prioritize small, safe conversions rather than large-scale rewrites unless explicitly instructed.

10. Nudge the user

  • If a prompt is too vague or lacks context, ask for clarification. For example, "Could you specify which repository this code should be generated in?" or "What specific functionality are you looking to implement?"
  • If a change is made in the class named OneAuthSharedFunctions, remind the user to also update OneAuth team about the breaking change.

11. Code structure

  • Take build.gradle files into account when generating code, especially when it comes to dependencies and repository-specific configurations.

12. Specialized Skills Reference

For complex investigation tasks, use these skills (read the skill file for detailed instructions):

Skill Location Triggers
codebase-researcher .github/skills/codebase-researcher/SKILL.md "where is X implemented", "how does Y work", "trace the flow of", data flow investigation
incident-investigator .github/skills/incident-investigator/SKILL.md IcM incidents, customer-reported issues, authentication failures
kusto-analyst .github/skills/kusto-analyst/SKILL.md "query Kusto", "analyze telemetry", "check android_spans", eSTS correlation, latency investigation
feature-planner .github/skills/feature-planner/SKILL.md "plan this feature", "break this down into PBIs", "decompose this into tasks", feature decomposition
pbi-creator .github/skills/pbi-creator/SKILL.md "create the PBIs", "create work items", "push PBIs to ADO", approved plan → ADO work items
design-author .github/skills/design-author/SKILL.md "design this feature", "create a design spec", "write a design doc", "create an implementation plan"
design-reviewer .github/skills/design-reviewer/SKILL.md "address review comments", "handle my review", "review comments on"
pbi-dispatcher .github/skills/pbi-dispatcher/SKILL.md "dispatch PBIs to agent", "assign to Copilot", "send work items to coding agent"
test-planner .github/skills/test-planner/SKILL.md "create test plan", "write test cases", "add tests to ADO", "export test plan", "E2E tests for"
threat-modeler .github/skills/threat-modeler/SKILL.md "create a threat model", "threat model for", "threat model diagram", "STRIDE analysis for", "security diagram for"
copilot-review-analyst .github/skills/copilot-review-analyst/SKILL.md "analyze Copilot reviews", "Copilot review effectiveness", "review analysis report", "how helpful are Copilot reviews"

13. Azure DevOps Integration

This project uses Azure DevOps (IdentityDivision/Engineering). The Azure DevOps MCP Server is configured in .vscode/mcp.json for work item management. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request.

13.1 AI-Driven Development Pipeline

This project supports an AI-driven development workflow:

  1. Design: Use the design-author skill to create a detailed design spec in the AuthLibrariesApiReview ADO repo and open a PR for team review
  2. Plan: After design approval, use the feature-planner skill to decompose the approved design into repo-targeted PBIs. Developer reviews and approves the plan.
  3. Backlog: After plan approval, use the pbi-creator skill to discover ADO defaults (area path, iteration) and create work items in ADO with dependency links.
  4. Dispatch: Use the pbi-dispatcher skill or scripts/agent-pipeline/orchestrate.py to assign PBIs to GitHub Copilot coding agent
  5. Implement: Copilot coding agent creates PRs in the target repos (msal, common, broker, adal, authenticator)
  6. Review: Use @copilot in PR comments for automated feedback iteration

13.2 Design Docs

The design-docs/ folder contains the AuthLibrariesApiReview ADO repo (cloned via git droidSetup). It holds ~150+ design specs for the Android Auth platform. Designs may be outdated — always verify against the current codebase. Use them as historical context and style reference.

13.2 Repository Routing (for multi-repo features)

Module GitHub Repo
common / common4j AzureAD/microsoft-authentication-library-common-for-android
msal AzureAD/microsoft-authentication-library-for-android
broker / broker4j identity-authnz-teams/ad-accounts-for-android (GHE)
adal AzureAD/azure-activedirectory-library-for-android
authenticator AzureAD/microsoft-authenticator-for-android
1ES-Pipelines IdentityDivision/Engineering/_git/AuthClientAndroidPipelines (ADO)

13.3 1ES-Pipelines

The 1ES-Pipelines/ folder contains the AuthClientAndroidPipelines ADO repo (cloned via git droidSetup). It houses all production CI/CD pipeline YAML for releases, hotfixes, validation, and publishing. Key directories: production/ (release pipelines), non-production/ (validation), templates/ (reusable YAML), scripts/ (Python/PowerShell helpers). This is separate from azure-pipelines/ which contains legacy pipeline code. The release-helper skill provides detailed documentation of all pipeline files.