Github Copilot Coding Agent

👉 Bitovi can help you integrate this into your own SDLC workflow: AI for Software Teams

1. Create a detailed Github Issue

2. Assign the issue to Copilot

   1. Open

      

       

   2. Copilot will respond with a PR. This is where all future communications and work on the issue happen.

3. Chat with Copilot directly in the PR

   1. Copilot will recognize any comments in in “Conversation” & from “Files changed” as long as they include @copilot in the message

      Open

      

      Example of mentioning copilot in conversation comment
      Open

      

      Chat with copilot in “Conversation” or while reviewing code in “Files changed”
   2. Open

      

      Example of mentioning copilot in conversation comment
   3. Open

      

      Example of mentioning copilot as part of a code review

       

       

   4. To see what copilot is doing at any point, click the Session button in the PR’s conversation view:

      Open

      

      Click here to see a copilot session
   5. Open

      

      Example copilot session

       

   6. View all current and past sessions on the Agents page

• Agents panel or page

  • github.com/copilot/agents

  • Open

    

    Delegate new tasks to Copilot and monitor progress from your Agents. Across all your repos/branches.

     

• Copilot Chat in Visual Studio Code

  • Requires GitHub Pull Requests extension

• Copilot Chat in other IDEs

• Copilot Chat in GitHub.com

If Copilot has not already been enabled in your repo, follow these instructions. All Bitovi-owned repos should already have it enabled. Test by attempting to assign a Github issue to copilot. There is no other initial setup required though some extra work is recommended when first using copilot coding agent in a repo:

1. Configure firewall (copilot tells you which urls it couldn’t access & provides instructions)

2. Add copilot-instructions.md (do this before firewall & instructions may reference links being blocked)

3. situational: setup .github/workflows/copilot-setup-steps.yml

• Recommend setting up a custom copilot configuration as the agents firewall is strict by default. If it finds blocked sites, Copilot will suggest doing one of the following:

  • Configure Actions setup steps to set up environment, which run before the firewall is enabled

  • Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

• If copilot-instructions are not already in the repo, every copilot PR will recommend adding them & provide a link to have copilot automatically generate them.

  • Result: Does a decent job & only requires minimal effort: (1️⃣)

• Attempting to use Bitovi’s instruction generator

  • Initial result may ignore instructions and use githubs process: 👎 (2️⃣)

  • May need to re-instruct to follow Bitovi prompt: ☹️ (3️⃣)

Example of github created copilot-instructions.md

Open

Screenshow of how it will suggest creating file. Just click “here” & assign the issue it generates to copilot.

Open

Example pre-filled issue that only requires clicking “Create” to start

 

default prompt by copilot

Configure instructions for this repository as documented in [Best practices for Copilot coding agent in your repository](https://gh.io/copilot-coding-agent-tips). <Onboard this repo>

1️⃣ example copilot-instructions.md generated by default prompt (144 lines)

https://github.com/bitovi/taskflow/pull/4 TaskFlow — AI Feature Generation Demo TaskFlow is a modern task management app built with Next.js 15, React, TypeScript, and Prisma. It provides a comprehensive solution for managing tasks and projects with an intuitive drag-and-drop Kanban board interface. Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. Working Effectively Bootstrap, Build, and Test the Repository Install dependencies: npm install -- takes 45-50 seconds. NEVER CANCEL. Set timeout to 90+ seconds. Database setup (may fail in restricted environments): npm run db:setup -- Creates, migrates and populates SQLite database with sample data KNOWN ISSUE: In environments with restricted network access, this fails with "getaddrinfo ENOTFOUND binaries.prisma.sh" because Prisma engines cannot be downloaded WORKAROUND: Use npx prisma generate first, or create mock Prisma client in app/generated/prisma/ if engines unavailable Build the application: npm run build -- takes 15-20 seconds normally. NEVER CANCEL. Set timeout to 60+ minutes. KNOWN ISSUE: In environments with restricted network access, this fails with "Failed to fetch fonts from Google Fonts" because the app uses Inter and Poppins fonts from Google Fonts WORKAROUND: Temporarily comment out Google Font imports in app/layout.tsx, components/ui/card.tsx, and lib/fonts.ts Lint the code: npm run lint -- takes 3-5 seconds. Shows warnings and errors but runs successfully. Run the Application Development server: ALWAYS run the database setup first if possible npm run dev -- starts on http://localhost:3000, ready in ~1 second Uses Turbopack for fast refresh Production server: npm run build && npm run start Default Credentials Email: alice@example.com Password: password123 NOTE: These only work if database seeding was successful Validation CRITICAL: Always manually test login functionality after making authentication changes Test the Kanban board drag-and-drop functionality when modifying task components Always run npm run lint before finishing - the CI would fail on linting errors (though no CI is currently configured) ALWAYS test at least one complete end-to-end scenario after making changes: Login → View dashboard → Navigate to tasks → Create/edit/delete a task Login → View board → Drag tasks between columns Network Restrictions and Workarounds The following external dependencies may be blocked in restricted environments: Prisma Binary Downloads (binaries.prisma.sh) Affects: npm run db:setup, npx prisma generate Workaround: Create mock Prisma client with proper TypeScript interfaces Google Fonts (fonts.googleapis.com) Affects: npm run build, npm run dev Files using fonts: app/layout.tsx, components/ui/card.tsx, lib/fonts.ts Workaround: Comment out font imports and className usage Key Projects and Structure App Structure (Next.js App Router) app/ ├── (dashboard)/ # Protected dashboard routes │ ├── board/ # Kanban board view │ ├── tasks/ # Task list and task creation │ ├── team/ # Team overview │ └── page.tsx # Dashboard home ├── login/ # Authentication ├── signup/ # User registration ├── layout.tsx # Root layout with fonts └── globals.css # Global styles Key Components components/ ├── ui/ # shadcn/ui components (Button, Card, etc.) ├── kanban-board.tsx # Drag-and-drop board ├── task-list.tsx # Task list view ├── create-task-form.tsx # Task creation form ├── edit-task-form.tsx # Task editing form └── sidebar.tsx # Navigation sidebar Database and Actions prisma/ ├── schema.prisma # Database schema (SQLite) ├── seed.js # Sample data (7 users, 30+ tasks) └── clear.js # Database cleanup app/(dashboard)/tasks/actions.ts # Server actions for CRUD operations app/login/actions.ts # Authentication actions Common Tasks Database Management npm run db:seed — Populate with sample data npm run db:clear — Clear all data npm run db:reset — Clear and re-seed npm run db:setup — Push schema and reset data Key Files to Check When Making Changes Always check app/(dashboard)/tasks/actions.ts after modifying task-related functionality Always check app/login/actions.ts after modifying authentication Check prisma/schema.prisma when adding new fields or relationships Check component files in components/ when modifying UI Dependencies and Tech Stack Framework: Next.js 15 with App Router and Turbopack UI: shadcn/ui + Radix UI + Tailwind CSS v4 Database: Prisma ORM with SQLite Drag & Drop: @hello-pangea/dnd for Kanban board Auth: Custom session-based authentication with bcryptjs Charts: Recharts for dashboard analytics File Extensions and Imports Use .tsx for React components Use .ts for utilities and server actions Import paths use @/ alias for root directory Database imports: import { PrismaClient } from "@/app/generated/prisma" Use "use server" directive for server actions Branches for Reference main — Baseline application user-13-search-and-filter — Example AI-implemented feature with search and filters Environment Limitations Documentation When working in restricted environments, document these known issues: Prisma Setup Failure: "Cannot download Prisma engines" - requires manual mock or pre-built client Google Fonts Failure: "Cannot fetch fonts" - requires commenting out font imports No CI/CD: No .github/workflows directory exists, so no automated testing pipeline No Test Framework: No Jest, Vitest, or other testing setup detected Always include timeout values of 60+ minutes for build commands and 30+ minutes for database operations when they work normally.

Example using Bitovi Generator

Example prompt used to generate instructions

from https://github.com/bitovi/taskflow/issues/5 Configure instructions for this repository as documented in Bitovi's Instruction generation In particular, here are your instructions: Generate a .github/copilot-instructions.md file using a multi-step prompt chain. Open this repository on GitHub: https://github.com/bitovi/ai-enablement-prompts . Navigate to the /understanding-code/instruction-generation folder within the repo. Review all the prompt files in this folder WITHOUT executing them. This will help you understand the full scope of the prompt chain. Once you're familiar with the flow, begin executing the prompts in numerical order: 1-determine-techstack.md 2-categorize-files.md 3-identify-architecture.md 4-domain-deep-dive.md 5-styleguide-generation.md 6-build-instructions.md For each step, output results into a corresponding .instruction-generation-results/ folder. Mirror the step’s filename e.g., 1-determine-techstack.md > .instruction-generation-results/1-determine-techstack.md. Acceptence Criteria All instruction-generation steps are complete A full .github/copilot-instructions.md has been generated.

2️⃣ initial copilot-instructions.md generated where it ignored bitovi's generator prompt (231 lines)

from github.com/bitovi/taskflow/pull/6/files-commit#2 # TaskFlow - AI Task Management App Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. ## Working Effectively ### Bootstrap and Setup - Install dependencies: `npm install` -- takes ~49 seconds. Works reliably. - **NETWORK LIMITATIONS**: The following commands fail due to firewall restrictions: - `npm run db:setup` -- fails due to Prisma binary download restrictions (binaries.prisma.sh blocked) - `npm run build` -- fails due to Google Fonts access restrictions (fonts.googleapis.com blocked) - `npx prisma generate` -- fails due to Prisma binary download restrictions ### Core Commands That Work - `npm run lint` -- takes ~5 seconds. ALWAYS run before committing. Shows TypeScript warnings/errors. - Basic file operations, TypeScript compilation checks work normally - Git operations work normally ### Database & Prisma Limitations - **CRITICAL**: Database commands require network access to download Prisma binaries - Database setup commands in package.json: - `npm run db:setup` -- Create, migrate and populate database (FAILS due to network restrictions) - `npm run db:clear` -- Clear all data from database - `npm run db:seed` -- Populate database with sample data - `npm run db:reset` -- Clear and re-seed database - **WORKAROUND**: In environments with network restrictions, document that these commands cannot be executed - Prisma client generates to `app/generated/prisma` directory - Uses SQLite database (`prisma/app.db` file) ### Build System Limitations - **CRITICAL**: Build fails due to Google Fonts network access - `npm run build` fails because: - `app/layout.tsx` imports `Inter` from `next/font/google` - `lib/fonts.ts` imports `Poppins` from `next/font/google` - `components/ui/card.tsx` imports `Poppins` from `next/font/google` - **TypeScript Compilation Issues**: `npx tsc --noEmit` reveals: - 12 errors in 11 files - All Prisma client imports fail: `Cannot find module '@/app/generated/prisma'` - Missing generated types in: tasks/actions.ts, login/actions.ts, signup/actions.ts, components - **WORKAROUND**: In restricted environments, font imports must be replaced with local alternatives ### Development Server - `npm run dev --turbopack` -- starts development server on port 3000 - **TIMING**: Development server startup typically takes 10-15 seconds - **LIMITATION**: Will fail due to missing Prisma client and font dependencies in restricted environments - Uses Next.js 15.4.6 with App Router and Turbopack for fast refresh ## Validation Scenarios When the application is fully functional, ALWAYS test these complete user workflows: ### Authentication Flow 1. Visit http://localhost:3000 2. Navigate to /login 3. Use default credentials: `alice@example.com` / `password123` 4. Verify successful login redirects to dashboard ### Task Management Flow 1. Navigate to /tasks page 2. Click "New Task" to create a task 3. Fill out task form with title, description, priority, status, due date, assignee 4. Verify task appears in task list 5. Test task status updates via checkbox 6. Test task editing via dropdown menu 7. Test task deletion ### Dashboard Verification 1. Navigate to dashboard (/) 2. Verify statistics cards show correct data 3. Verify charts render properly with task data 4. Check recent tasks display ## Codebase Structure ### Key Directories ``` app/ ├── (dashboard)/ # Main application pages │ ├── page.tsx # Dashboard with stats and charts │ ├── tasks/ # Task management │ │ ├── page.tsx # Task list page │ │ ├── actions.ts # Server actions for CRUD │ │ └── new/ # Create task page │ ├── board/ # Kanban board view │ └── team/ # Team management ├── login/ # Authentication pages ├── signup/ └── generated/prisma/ # Generated Prisma client (network dependent) components/ ├── ui/ # shadcn/ui components ├── task-list.tsx # Main task listing component ├── kanban-board.tsx # Drag-drop kanban board ├── dashboard-charts.tsx # Charts for dashboard └── sidebar.tsx # Navigation sidebar prisma/ ├── schema.prisma # Database schema ├── seed.js # Sample data generation ├── clear.js # Database cleanup └── migrations/ # Database migrations ``` ### Server Actions Pattern - Actions located in `app/(dashboard)/tasks/actions.ts` - Uses Prisma ORM with TypeScript - Key actions: `createTask`, `getAllTasks`, `deleteTask`, `updateTaskStatus`, `updateTask` - Always use `revalidatePath("/tasks")` after mutations ### UI Component Pattern - Uses shadcn/ui + Radix UI components - Tailwind CSS for styling - Custom fonts: Inter (main), Poppins (headings) - Icons from Lucide React ### State Management - Uses React Server Components for server-side data fetching - Optimistic updates with `useOptimistic` hook - Form handling with Server Actions and `useActionState` ## Important Implementation Details ### Authentication - Session-based auth using cookies - Sessions stored in database - Password hashing with bcrypt - Default test user: alice@example.com / password123 ### Database Schema - Users: id, email, password, name - Tasks: id, name, description, priority, status, dueDate, assigneeId, creatorId - Sessions: id, token, userId, createdAt ### Task Statuses - `todo`, `in_progress`, `done`, `review` ### Task Priorities - `low`, `medium`, `high` ## Common Patterns ### Adding New Features 1. Create server action in appropriate `actions.ts` file 2. Build UI component following shadcn/ui patterns 3. Use TypeScript with Prisma-generated types 4. Always run `npm run lint` before committing 5. Test complete user workflow after changes ### TypeScript Usage - Use Prisma-generated types: `import type { Task, User } from "@/app/generated/prisma"` - Extend types with relations: `TaskWithProfile` pattern - Use proper typing for Server Actions and form data ### Styling Conventions - Use Tailwind CSS utility classes - Follow shadcn/ui component patterns - Use Poppins font for headings, Inter for body text - Consistent color scheme with CSS variables ## Linting and Code Quality ### Before Committing - ALWAYS run `npm run lint` -- takes ~5 seconds - Fix TypeScript warnings and errors - Current TypeScript issues requiring Prisma client generation: - 12 compilation errors in 11 files when Prisma client is missing - All imports from `@/app/generated/prisma` and `@/app/generated/prisma/client` fail - Key affected files: actions.ts files, components with Task types - Current known lint issues (as of last check): - `@typescript-eslint/no-unused-vars` warnings in several files - `@typescript-eslint/no-explicit-any` errors in login/signup pages - `@typescript-eslint/no-empty-object-type` error in textarea component - Implicit 'any' type errors in board/page.tsx and team/page.tsx ### Code Style - Use TypeScript strict mode - Prefer Server Components over Client Components when possible - Use Server Actions for data mutations - Follow Next.js App Router patterns ## Troubleshooting ### Network-Restricted Environments - Database setup will fail - document this limitation - Font loading will fail - replace with local fonts or system fonts - Build process will fail - address font dependencies first - **COMPLETE WORKAROUND FOR RESTRICTED ENVIRONMENTS**: 1. Replace all `next/font/google` imports with local font alternatives 2. Create mock Prisma client types in `app/generated/prisma/` directory 3. Use alternative database solutions or mock data for development 4. Document these changes as environment-specific modifications ### Development Issues - If Prisma client missing: Check network access for binary downloads - If fonts not loading: Check network access to fonts.googleapis.com - If build fails: Usually network-related font or dependency issues - If TypeScript errors: Usually missing Prisma client generation ### Common File Locations to Check After Changes - Always check `app/(dashboard)/tasks/actions.ts` after modifying task-related features - Always check component files in `components/` after UI changes - Always check `prisma/schema.prisma` after database changes - Always check font imports in `app/layout.tsx`, `lib/fonts.ts`, `components/ui/card.tsx` after styling changes ## CRITICAL Timing Information - **npm install**: ~49 seconds - NEVER CANCEL, set timeout to 120+ seconds - **npm run lint**: ~5 seconds - safe to use default timeout - **npm run build**: Network dependent - NEVER CANCEL if network available, set timeout to 300+ seconds - **npm run dev**: ~10-15 seconds startup - NEVER CANCEL, set timeout to 60+ seconds - **Database setup**: Network dependent - NEVER CANCEL if network available, set timeout to 180+ seconds ## Environment Requirements - Node.js (version requirement: "^20" per package.json) - npm (package-lock.json indicates npm usage) - Next.js 15.4.6 with App Router and Turbopack - Prisma 6.13.0 for database ORM - Network access for: - Prisma binary downloads (binaries.prisma.sh) - REQUIRED for database functionality - Google Fonts (fonts.googleapis.com) - REQUIRED for build process - Build-time dependencies ### Dependency Versions (Validated) - next@15.4.6 - @prisma/client@6.13.0 - prisma@6.13.0 - react@19.1.0 - TypeScript@5.x **ALWAYS validate these instructions work in your specific environment and document any additional limitations discovered.**

3️⃣ example copilot-instructions.md after enforcing instructions (184 lines + 24 files)

github.com/bitovi/taskflow/pull/6/files-commit#3 # TaskFlow - AI Copilot Instructions ## Overview This file enables AI coding assistants to generate features aligned with TaskFlow's architecture and conventions. These instructions are based on actual, observed patterns from the codebase analysis following the Bitovi instruction generation methodology. TaskFlow is a task management application built with Next.js 15, React 19, TypeScript, Prisma ORM, and Tailwind CSS. It features authentication, CRUD operations, kanban boards, and data visualization. ## File Category Reference ### next-js-pages **Purpose**: App Router pages that define routes and handle initial data loading **Examples**: `app/(dashboard)/page.tsx`, `app/login/page.tsx` **Key Conventions**: - Use consistent padding structure: `className="flex-1 space-y-4 p-4 md:p-8 pt-6"` - Headers with Poppins font: `className={`text-3xl font-bold tracking-tight ${poppins.className}`}` - Server pages use async functions for data fetching - Client pages start with "use client" directive ### server-actions **Purpose**: Server-side functions for data mutations and authentication **Examples**: `app/(dashboard)/tasks/actions.ts`, `app/login/actions.ts` **Key Conventions**: - Start with "use server" directive - Authentication check: `const user = await getCurrentUser(); if (!user) return { error: "Not authenticated." }` - Return format: `{ success: boolean, error?: string, message?: string }` - Always include `revalidatePath()` after mutations - Use `parseDateString()` for date handling ### react-components **Purpose**: Interactive UI components with state management **Examples**: `components/task-list.tsx`, `components/kanban-board.tsx` **Key Conventions**: - Use "use client" directive for interactivity - Optimistic updates with `useOptimistic` hook - Type extensions: `type TaskWithProfile = PrismaTask & { assignee?: Pick<User, "name"> | null }` - Event handlers combine optimistic updates with server actions ### ui-components **Purpose**: Reusable design system components built on Radix UI **Examples**: `components/ui/button.tsx`, `components/ui/card.tsx` **Key Conventions**: - Use `React.forwardRef` pattern - Class variance authority for variants - Radix UI primitives as foundation - Export all related components together ### utility-functions **Purpose**: Helper functions for common operations **Examples**: `lib/utils.ts`, `lib/date-utils.ts` **Key Conventions**: - Simple, focused functions - Timezone-safe date operations - JSDoc comments for complex logic - Flexible input types (Date | string) ### type-definitions **Purpose**: TypeScript type definitions extending Prisma types **Examples**: `lib/types.ts` **Key Conventions**: - Extend Prisma types with relationships - Use literal union types for status values - Nullable relationship patterns with Pick utility - Centralized in lib/types.ts ## Feature Scaffold Guide ### Creating a New Feature 1. **Determine file structure** based on feature scope: - Add page in `app/(dashboard)/feature-name/page.tsx` - Create server actions in `app/(dashboard)/feature-name/actions.ts` - Build components in `components/feature-name.tsx` - Add types to `lib/types.ts` if needed 2. **Follow naming conventions**: - Pages: `page.tsx` in feature folders - Components: kebab-case filenames, PascalCase exports - Actions: descriptive function names (createTask, updateTask) - Types: descriptive names with relationships (TaskWithProfile) 3. **Implement authentication protection**: - Server actions: Check `getCurrentUser()` first - Protected pages: Use dashboard route group - Forms: Handle error states from authentication ### Example: Adding a Comments Feature **Files to create**: - `app/(dashboard)/comments/page.tsx` - Comments list page - `app/(dashboard)/comments/actions.ts` - CRUD operations - `components/comment-list.tsx` - Comment display component - `components/create-comment-form.tsx` - Comment creation - Add Comment model to `prisma/schema.prisma` - Add CommentWithUser type to `lib/types.ts` ## Integration Rules ### Data Layer Constraints - All database access must use Prisma client from `@/app/generated/prisma` - Server Actions must include authentication checks via `getCurrentUser()` - Mutations must call `revalidatePath()` for cache invalidation - Date inputs must use `parseDateString()` utility ### UI Constraints - All interactive elements must use Radix UI components (Button, Dialog, etc.) - Styling must use Tailwind CSS classes and `cn()` utility - Icons must be imported from lucide-react package - Fonts must use Poppins for headings, defined in `lib/fonts.ts` ### State Management Constraints - Use Server Components for data fetching, not global state libraries - Client components receive data as props from server components - Optimistic updates must be paired with Server Actions - Forms must submit to Server Actions, not client-side libraries ### Authentication Constraints - Session-based authentication using httpOnly cookies - All auth operations must be Server Actions - Protected routes must check authentication at layout level - Passwords must be hashed with bcryptjs ### Drag and Drop Constraints - Must use Hello-Pangea DnD library components - Kanban boards must follow DragDropContext/Droppable/Draggable structure - Drag operations must update local state immediately and sync to server ### Data Visualization Constraints - All charts must use Recharts library with ResponsiveContainer - Chart components must be separate and receive processed data as props - Use consistent theme colors defined in chart components ## Example Prompt Usage **User Request**: "Create a searchable dropdown that lets users filter tasks by status" **Expected AI Response**: Create these files following TaskFlow conventions: 1. `components/status-filter-dropdown.tsx`: ```typescript "use client" import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select" interface StatusFilterProps { onStatusChange: (status: string | null) => void currentStatus?: string | null } export function StatusFilterDropdown({ onStatusChange, currentStatus }: StatusFilterProps) { return ( <Select value={currentStatus || "all"} onValueChange={(value) => onStatusChange(value === "all" ? null : value)}> <SelectTrigger className="w-48"> <SelectValue placeholder="Filter by status" /> </SelectTrigger> <SelectContent> <SelectItem value="all">All Statuses</SelectItem> <SelectItem value="todo">To Do</SelectItem> <SelectItem value="in_progress">In Progress</SelectItem> <SelectItem value="review">Review</SelectItem> <SelectItem value="done">Done</SelectItem> </SelectContent> </Select> ) } ``` 2. Update `components/task-list.tsx` to integrate the filter: ```typescript const [statusFilter, setStatusFilter] = useState<string | null>(null) const filteredTasks = optimisticTasks.filter(task => !statusFilter || task.status === statusFilter ) // Add in render: <StatusFilterDropdown onStatusChange={setStatusFilter} currentStatus={statusFilter} /> ``` This example demonstrates: - Using existing UI components (Select) - Following TypeScript patterns with proper interfaces - Integrating with existing state management patterns - Using consistent naming conventions - Respecting the established status literal types

• Tip: may want to include semantic branch naming instructions. Branch copilot/fix-7 means nothing, especially when it’s for issue #3

from: https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment#customizing-or-disabling-the-agents-firewall:

• Preinstall tools or dependencies in Copilot's environment

• Set environment variables in Copilot's environment

• Upgrade from standard GitHub-hosted GitHub Actions runners to larger runners

• Enable Git Large File Storage (LFS)

• Disable or customize the agent's firewall.

before the agent starts

• .github/workflows/copilot-setup-steps.yml

docs: https://docs.github.com/en/copilot/concepts/coding-agent/coding-agent

• Fix bugs

• Implement incremental new features

• Improve test coverage

• Update documentation

• Address technical debt

From Benefits over traditional AI workflows:

Copilot automates branch creation, commit message writing and pushing, PR opening, and PR description writing. Developers let the agent work in the background and then steer Copilot to a final solution using PR reviews. Working on GitHub adds transparency, where every step happens in a commit and is viewable in logs. Working on GitHub also opens up collaboration opportunities for the entire team.

From Copilot coding agent versus agent mode:

Copilot coding agent works autonomously in a GitHub Actions-powered environment to complete development tasks assigned through GitHub issues or GitHub Copilot Chat prompts, and creates pull requests with the results. In contrast, agent mode in Visual Studio and Visual Studio Code is part of the GitHub Copilot Edits feature that allows Copilot to make autonomous edits directly in your local development environment.

By default, Copilot Coding Agent only starts with access to a subset of the github-mcp-server tools.

To add other tools,

• see the official docs Preinstalling tools or dependencies in copilots environments https://bitovi.atlassian.net/browse/FE-461

• Or our docs on

  • How to Setup Github’s Cloud Coding Agent to listen to the Atlassian MCP Server

  • How to Setup Github’s Cloud Coding Agent to listen to the Figma MCP Server

  • How to Setup AI-Coding-Agent as a MCP Proxy Service for Atlassian in the Github Cloud Coding Agent

As mentioned above, Copilot will only recognize comments if they include @copilot in the message.

Open

However, including @copilot in the review summary eliminates the need to mention it in each inline comment during the code review (example)

• Strengths

  • Immediate responsiveness: Responds to every comment quickly and directly

  • Clear status updates: Provides detailed progress reports with ✅/❌ status indicators

  • Code references: Shows specific code examples when explaining changes

  • Multiple task handling: Successfully manages complex multi-part requests (file moves, component renames, prop additions)

  • Build verification: Runs tests and builds after changes to confirm success

• Weaknesses

  • Misses implicit feedback: Didn't catch the comment about styling tests that wasn't directly @-mentioned, or inside a code review

  • Incomplete type setup: did not install @types/jest (commit)

  • Session note isolation: Important findings (like pre-existing broken tests) only appear in session notes, not in comments

  • No proactive suggestions: Doesn't suggest follow-up actions or separate issues for unrelated problems found

https://github.blog/ai-and-ml/github-copilot/how-to-generate-unit-tests-with-github-copilot-tips-and-examples/

https://docs.github.com/en/copilot/tutorials/write-tests

• Strengths

  • Testing setup: Can establish testing frameworks in codebases that don't have them

  • Proactive testing: Runs tests before changes and writes/updates them automatically if codebase has existing tests

  • Smart test management: Updates existing component tests and adds new tests for features without explicit instruction

  • Focused scope: Stays on task without expanding to unrelated issues

• Weaknesses

  • Poor communication: Buries important findings (like unrelated broken tests) in session notes instead of alerting developers

  • Incomplete cleanup: Leaves behind broken types and doesn't ensure full codebase health (unless explicitly instructed)

  • Limited follow-up: Often skips suggesting next steps or mentioning separate issues for any unrelated problems found

  • No testing initiative: Won't add tests to codebases without existing tests or update unrelated tests (unless explicitly instructed)

• No issue updates after assignment: Changes to issues after Copilot is assigned are ignored.

  • To fix: edit issue then unassign/reassign (creates new PR), or comment new instructions in the PR itself

• Comment edits ignored: Unlike VSCode, edits to comments aren't recognized - forgot @copilot or hit enter early? Must send a new message with @copilot

• No clarifying questions: Copilot only follows initial ticket instructions without asking for missing details

From Docs - Limitations of Copilot coding agent:

• Repository scope: Limited to the same repository as the assigned issue

• Context access: Only accesses context from the assigned issue's repository

• Single PR: Opens exactly one pull request per assigned task

• Existing PRs: Cannot modify PRs it didn't create (can review them)

• Unsigned commits: Requires commit rewriting if signed commits are required

• Self-hosted runners: Doesn't work with self-hosted GitHub Actions runners

• Managed accounts: Doesn't work in personal repos owned by managed user accounts

• Content exclusions: Ignores content exclusion settings

• 🔥 Public code policy: Bypasses "Suggestions matching public code" blocks and may suggest public code anyway

• GitHub only: Only works with GitHub-hosted repositories

So, configuring the Cloud Coding Agent to work with the Jira MCP turned out to be a bit more obnoxious than initially anticipated. The crux of the problem being: Jira’s MCP service apparently requires a PKCE-flow auth token. Learning that this token was required and distinct/different from an API token or encrypted token with Basic auth was part of the time sink here. Furthermore, Github’s own documentation suggests secrets should be passed to the JSON MCP config as <COPILOT_MCP_SECRET> when in reality it should be $<COPILOT_MCP_SECRET>

Once that requirement was ascertained, shoutout to Justin Meyer for quickly figuring out a hacky way to grab one of those PKCE tokens to unblock investigation work. Below are the steps for configuring a repository in Github to leverage the Jira MCP server as part of its Cloud Coding Agent compute:

1. For the repository in question, navigate to its Settings tab

   Open

   

2. Within the Code and automation section, scroll down Copilot, expand it, and click Coding agent

   Open

   

3. Scroll down to the MCP configuration JSON block and input the following:

   { "mcpServers": { "jira": { "tools": ["*"], // for simplicity, allow all Atlassian tooling "type": "sse", "url": "https://mcp.atlassian.com/v1/sse", "headers": { "Authorization": "Bearer <PKCE token>" // see next steps for generating this } } } }

4. Next, in your terminal ensure you have modelcontextprotocol/inspector installed. If not, run the following to install:

   npx @modelcontextprotocol/inspector

5. This will open a localhost window that looks like the following:
   
   

   Open

   

6. In the left sidepane, under URL input the Jira MCP url - https://mcp.atlassian.com/v1/sse

7. Then press “Connect” at the bottom of the config options in the left sidepane (pictured it says “Reconnect”)

8. This will trigger the OAuth PKCE flow

9. After that is completed, select Auth from the top navigation bar

10. Open

    

    Scroll down until you see where it says Authentication Complete. Below that you’ll see a small dropdown for Access Tokens. Expand that to find your token to use!
    
    

    Open

    

     

11. Add your PKCE token to your Github secrets for Copilot, by Navigation to Repository → Settings → Code and automation click Environments → click copilot → Within the Environment Secrets section click Add environment secret
    
    

    Open

    

     

12. BE SURE YOUR SECRET NAME IS PREFIXED WITH COPILOT_MCP_ so that the Clouding Agent may use it.
    
    

13. Add the secret to your JSON config for the MCP server outlined in step 3, replacing <PKCE token> with the name of your COPILOT_MCP_ environment secret that you created in step 12.

14. Now, whenever you open an issue assigned to Copilot, if the issue instructions require reading a Jira ticket the agent will do that!

1. For the repository in question, navigate to its Settings tab

   Open

   

2. Within the Code and automation section, scroll down Copilot, expand it, and click Coding agent

   Open

   

3. Scroll down to the MCP configuration JSON block and input the following:

   { "mcpServers": { "figma": { "tools": ["*"], "type": "http", "url": "http://figma-mcp-load-balancer-1597143317.us-east-1.elb.amazonaws.com/mcp", "headers": { "Authorization": "Bearer $COPILOT_MCP_FIGMA_TOKEN" } } } }

4. Navigate to the Bitovi 1Password instance and locate the Authorization header information there: https://start.1password.com/open/i?a=GV2FYFKQURG4RCTEGPUDM2ZFFU&v=mecxwd3bzdov2zdnr2g7hqeq64&i=kz5ck7vq5xxtzq73tajehufwcu&h=bitovi.1password.com
   
   

5. Store the token portion of the information in Github’s copilot environment secrets by navigating to Repository → Settings → Code and automation click Environments → click copilot → Within the Environment Secrets section click Add environment secret
   
   

   Open

   

    

6. BE SURE YOUR SECRET NAME IS PREFIXED WITH COPILOT_MCP_ so that the Clouding Agent may use it.

   1. In the above JSON snippet example, the token is named COPILOT_MCP_FIGMA_TOKEN
      
      

7. Open a new Github issue and provide a link to a Figma node. Links are available by clicking on the code symbol in the top right corner of Layers and selecting Copy link to focus view.
   
   

   Open

   

    

8. Assign the issue to Copilot and create the issue! The agent should automatically pick up the task and successfully connect to the Figma MCP server!

Small, lovely gotchas here, too. Conceptually, all this will be is some sort of trigger on the Jira side that, whenever a new issue is created within a specified project, this will fire an API request to Github to create an issue with the Jira ticket information and automatically assign it to Copilot – which will kick off the cloud coding agent flow.

1. On the Jira side, within the relevant project, navigate to Project Settings
   
   

2. Open

   

   From Project Settings navigate in the left pane to Automation

3. From Automation in the top right corner, click the button that says Create Rule and choose the “From scratch” dropdown option.

4. For the initial trigger, within Add a Trigger search “Work Item Created” and select it.
   
   

5. Open

   

   Next click Add component and in the right wizard, select THEN: Add an action

6. Search “Web request”

   Open

   

    

7. Fill in your Web request to the Github API to look like the following:
   
   

   Open

   
   { "operationName": "CreateIssue", "query": "mutation CreateIssue($repositoryId: ID!, $title: String!, $body: String, $assigneeIds: [ID!]) { createIssue(input: { repositoryId: $repositoryId, title: $title, body: $body, assigneeIds: $assigneeIds }) { issue { id title assignees(first: 10) { nodes { login } } } } }", "variables": { "repositoryId": "R_kgDOPdj41Q", "title": "{{issue.key}} {{issue.summary}}", "body": " Implement the work described in Jira ticket {{issue.key}}", "assigneeIds": ["BOT_kgDOC9w8XQ"] } }

   1. This Uses the Github GraphQL API (seemingly their only service that will currently let you assign issues to the copilot bot)

   2. Note the headers and be sure to generate Github PAT to pass that has Content Read/Write access to the Repo.

   3. HEADS UP: YOU MUST ENSURE WHOEVER GENERATED THE ACCESS TOKEN HAS COPILOT PRIVILEGES IN THE ORGANIZATION – check the following link to verify:

      https://github.com/organizations/<YOUR_ORG>/settings/copilot/seat_management

   4. for repositoryId and the bot id within assigneeIds – you’ll need to query the Github API to pull those specific values for the repo in question. Here’s a helpful query you can make to pull that info:

      { "query": "query($owner: String!, $name: String!, $first: Int!) { repository(owner: $owner, name: $name) { id suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: $first) { nodes { ... on Bot { id } } } } }", "variables": { "owner": "bitovi", // or relevant owner "name": "taskflow", // or relevant repo "first": 1 } }

      1. Note: you’ll need to pass the following headers for all Github API requests:

         { "Accept": "application/vnd.github+json", "X-Github-API-Version": "2022-11-28", "Authorization": "Bearer <TOKEN>" // make a fine-grained access token in Github, ensure it has read/write access for Content }

8. You can run a Validate fxn to ensure your request works (pictured is the result of the query for ID information)
   
   

9. Open

   

   Once you’re satisfied, at the top right corner you can click "Turn on rule" and turn it on.

10. Now, whenever you make a new ticket in this Jira project, it should automatically create a Github issue in the specified repo assigned to copilot!

The theory here is that we will:

• Establish a Jira webhook as an automation trigger

• Configure a Github CICD pipeline yml file to communicate with that webhook, if the pipeline passes.

• Have the webhook trigger hand off the ticket key to a rule that will update its status to Done (but it could be to any accessible status configured in the project settings).

Open

1. On the Jira side, within the relevant project, navigate to Project Settings
   
   

2. Open

   

   From Project Settings navigate in the left pane to Automation

3. From Automation in the top right corner, click the button that says Create Rule and choose the “From scratch” dropdown option.

4. For the initial trigger, within Add a Trigger search “Incoming Webhook”

    

5. Then click “Add Component” below your trigger in the workflow UI

6. Select THEN: Add an action and search Transition work item

7. Configure the Destination status to be whatever status you want the ticket updated to:

   Open

   

    

8. Next, if your project doesn’t already have a CICD yml file, create one. Below is a simple yml to run a lint check. Create this file within .github/workflows/<newfile>.yml
   
   

   name: PR Lint Check and Jira Integration on: pull_request: types: [opened, synchronize, reopened, edited] jobs: lint: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v5 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "20" cache: "npm" - name: Install dependencies run: npm ci - name: Run lint check id: lint run: npm run lint

9. Now, here’s where we connect the dots to make the magic happen. Add a new job to run after the lint job that will communicate with our webhook. That would look like:
   
   

   name: PR Lint Check and Jira Integration on: pull_request: types: [opened, synchronize, reopened, edited] jobs: lint: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v5 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "20" cache: "npm" - name: Install dependencies run: npm ci - name: Run lint check id: lint run: npm run lint jira: runs-on: ubuntu-latest needs: lint steps: - name: Extract Jira ticket from branch name id: extract-ticket run: | branch_name="${{ github.head_ref }}" echo "Branch name: $branch_name" # Extract Jira ticket pattern (e.g., PROJ-123, ABC-456) # This regex matches common Jira ticket patterns jira_ticket=$(echo "$branch_name" | grep -oE '[A-Z]+-[0-9]+' | head -1 || echo "") if [ -n "$jira_ticket" ]; then echo "Found Jira ticket: $jira_ticket" echo "jira_ticket=$jira_ticket" >> $GITHUB_OUTPUT else echo "No Jira ticket found in branch name" echo "jira_ticket=" >> $GITHUB_OUTPUT fi - name: Update Jira Ticket Status if: steps.extract-ticket.outputs.jira_ticket != '' env: JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }} JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }} JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }} run: | jira_ticket="${{ steps.extract-ticket.outputs.jira_ticket }}" if [ -z "$JIRA_BASE_URL" ] || [ -z "$JIRA_EMAIL" ] || [ -z "$JIRA_API_TOKEN" ]; then echo "⚠️ Jira credentials not configured. Please set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN secrets." exit 0 fi echo "Looking up Jira ticket: $jira_ticket" # Make API request to Jira to get ticket details response=$(curl -s -w "\n%{http_code}" -X POST \ -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-type: application/json" \ -H "X-Automation-Webhook-Token: ${{ secrets.JIRA_WEBHOOK_TOKEN}}" \ --data "{\"issues\":[\"${jira_ticket}\"], \"data\": {\"releaseVersion\": \"5.3.2\"}}" \ "https://api-private.atlassian.com/automation/webhooks/jira/a/${{ secrets.JIRA_PRIVATE_ENDPOINT_ID}}") # Extract HTTP status code http_code=$(echo "$response" | tail -n1) response_body=$(echo "$response" | head -n -1) if [ "$http_code" = "200" ]; then echo "✅ Successfully found Jira ticket: $jira_ticket" echo "Ticket details:" echo "$response_body" | jq -r '.fields.summary // "No summary available"' echo "Status: $(echo "$response_body" | jq -r '.fields.status.name // "Unknown"')" echo "Assignee: $(echo "$response_body" | jq -r '.fields.assignee.displayName // "Unassigned"')" elif [ "$http_code" = "404" ]; then echo "❌ Jira ticket $jira_ticket not found" exit 1 else echo "❌ Failed to lookup Jira ticket. HTTP status: $http_code" echo "Response: $response_body" exit 1 fi

   1. Note: In this example, we first run the step Extra Jira ticket from branch name so that we know what ticket to lookup in our Jira webhook.

   2. Note: This ticket extraction assumes your branch naming convention will be as follows: <PROJECT-NUMBER>-other-details-...

   3. The magic is below. No data is passed really aside from the ticket key because all we need to do is ping Jira with the key. Jira takes it from with logic management within its webhook:

      response=$(curl -s -w "\n%{http_code}" -X POST \ -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ -H "Content-type: application/json" \ -H "X-Automation-Webhook-Token: ${{ secrets.JIRA_WEBHOOK_TOKEN}}" \ --data "{\"issues\":[\"${jira_ticket}\"], \"data\": {\"releaseVersion\": \"5.3.2\"}}" \ "https://api-private.atlassian.com/automation/webhooks/jira/a/${{ secrets.JIRA_PRIVATE_ENDPOINT_ID}}")

10. You’ll probably notice some environment secrets in the above yml. Navigate to your Github repository secrets settings, and set the following:

    JIRA_BASE_URL: https://<org>.atlassian.net/ JIRA_EMAIL: you@org.com // probably your email address that you use to access Jira JIRA_API_TOKEN: xxx // can be generated here https://id.atlassian.com/manage-profile/security/api-tokens JIRA_PRIVATE_ENDPOINT_ID: The last two path segmemts of id generated by Jira for its "Webhook url" JIRA_WEBHOOK_TOKEN: // Visible in the `Secret` section, when you created the Webhook trigger in Jira

11. You’re all set! Now whenever you open a PR with the appropriate branch naming, Github and Jira will communicate to update the status of the specified ticket to Done (or whatever status you selected in your Jira webhook settings)

Pretty straight-forward here with a small but crucial gotcha. We will proxy the Atlassian MCP server in this example.

1. Run the AI-Coding-Agent app locally

2. In a terminal ngrok the http 3000 port to create a navigable domain

3. In the AI-Coding-Agent local instance, run through the OAuth PKCE flow for Jira.

4. Once you see “authorized” for Jira in the UI, proceed. You may need to refresh the page.

5. Navigate to https://github.com/<org>/<repo>/settings/copilot/coding_agent and down to the MCP Configuration section

6. Open

   

   Create a new server entry (above named "my-proxy" and setup this config

   "my-proxy": { "type": "sse", "tools": ["*"], "url": "<ngrok-url>/api/mcp/jira/proxy", "headers": { "Content-Type": "application/json", "Authorization": "Bearer $COPILOT_MCP_your_secure_access_token_here" } }

   1. Note: Replace <ngrok-url> with whatever ngrok provides as the published domain in your terminal

   2. Note: Set COPILOT_MCP_your_secure_access_token_here with whatever the value of ACCESS_TOKENis in the ai-coding-agent .env file in your Github secrets (SPECIFICALLY in the copilot environment).

   3. Note: The gotcha in this instance is that the type for specifically the Atlassian proxy must be “sse” .

7. Save the MCP Configuration.

8. Create a new Github issue assigned to Copilot. Be sure to specify a ticket number and, to speed things along, in the Issue description tell it to use whatever the name of your proxy service (in this case "my-proxy") is to fulfill the ticket search.

• What environment is the github coding agent running in?

  • Documentation around how-to customize the dev environment the coding agent runs in: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment

    • Look like it runs in Node using a version from the cache tools specified by the specific Runner.

      • You can specify what runner you want copilot to operate in

    • To be clear, it can run on a Microsoft, Mac, or Ubuntu OS – this can specified through use of a specific runner image and setup before copilot runs via the copilot-setup-steps.yml

  • What version of node / linux / etc?

    • You can configure the runner environment for copilot like you could any other Github Action. There are various runner images maintained by Github, not to mention self-hosting your own custom runner.

    • Here’s an example of a runner image maintained by Github. You see see at the top level of this json that ”toolcache” is defined. We see that term used in the logs whenever the coding agent runs its jobs. Here specific software like node and linux among others can be specified.

• How can we control it?

  • Through use of a copilot-setup-steps.yml file to specify environment setup BEFORE copilot agent runs. See above for more details.

  • Can we effectively specify the container?

    • Yes, you can specify the container. According to Github, within the yml file these are the settings which you may customize (the rest would be ignored by copilot):

      In your copilot-setup-steps.yml file, you can only customize the following settings of the copilot-setup-steps job. If you try to customize other settings, your changes will be ignored. - steps - permissions - runs-on - container - services - snapshot - timeout-minutes (maximum value: 59)

• How can we specify other environment capabilities? Examples:

  • a mock screen so browsers can run? Example: Xvfb

    • The copilot yml has access to the steps setting, so within steps you could install something like Xvfb.

      • To be clear, for most of “what’s possible,” the answer to that question is another question:

        • “Is it possible in a normal Github runner via one of the outlined settings above? If so, then it should be possible here.”

  • could we run postgres?

    • According to the general documentation for setting up service containers in a Github Runner, you may setup a Postgres instance – the example in the link uses a Docker Hub postgres image. This information is specified within the services setting.

    • The services setting is accessible by the copilot-setup-steps.yml file and read by the coding agent, meaning one should be able to establish a postgres instance in their coding agent environment as well.

• What can we do with it?

  • Can we tell it to run a build?

    • Yes. It does this by default in the course of building code that would want to be tested.

  • Can we tell it to run tests and respond to test failures.

    • Yes, the Github Issue would need prompting if there is a specific follow-up on test fail or that a PR can’t be considered complete unless all tests are passing.

      • This sort of instructing can be in the Github Issue or in the repo copilot instructions.

  • How do we do that?

    • Prompting in the Github issue, or, and probably cleaner -
      
      Generate copilot instructions that tell Copilot how to build and test the repo and all relevant coding standards.
      
      

• Is there a way to tell the AI to take what it’s done and keep going?

  • Yes. When copilot generates a PR, you can leave comments on a PR tagging copilot asking it to make more changes.