Copilot Instructions Setup | CLA AutoExtract

This guide will help you set up GitHub Copilot instruction files in your development environment to ensure consistent coding conventions, commit messages, and pull request descriptions across the team.

Overview

We use three Copilot instruction files to maintain consistency:

coding-conventions.md - Coding standards and best practices
commit-guidelines.md - Commit message formatting rules
pullrequest-guidelines.md - Pull request description templates

Prerequisites

GitHub Copilot extension installed in VS Code
Access to the repository containing the instruction files
ServiceNow ticket submitted and approved for GitHub Copilot access (Access Request Form)

Instruction File Templates

Coding Conventions: coding-conventions.md
Commit Guidelines: commit-guidelines.md
Pull Request Guidelines: pullrequest-guidelines.md

Where to add instructions files to your Repository

The instruction files should be added to your repository at:

.github/copilot-instructions/
├── coding-conventions.md
├── commit-guidelines.md
└── pullrequest-guidelines.md

VS Code Configuration

1. Open VS Code Settings

Open your VS Code settings.json file:

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
Type “Preferences: Open User Settings (JSON)”
Select the option to open settings.json

2. Add Commit Message Generation Configuration

Add the following configuration to enable custom commit message guidelines:

"github.copilot.chat.commitMessageGeneration.instructions": [
  {
    "file": ".github/copilot-instructions/commit-guidelines.md"
  }
],

This configuration tells Copilot to use our team’s commit message guidelines when generating commit messages.

3. Add Pull Request Description Configuration

Add the following configuration to enable custom pull request description guidelines:

"github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
  {
    "file": ".github/copilot-instructions/pullrequest-guidelines.md"
  }
],

This configuration ensures that Copilot generates pull request descriptions following our team’s standards.

4. Complete Settings Example

Your settings.json should include both configurations. Here’s an example of how it should look:

{
  // ... other settings ...
  
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {
      "file": ".github/copilot-instructions/commit-guidelines.md"
    }
  ],
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    {
      "file": ".github/copilot-instructions/pullrequest-guidelines.md"
    }
  ],
  
  // ... other settings ...
}

Using Copilot with Instructions

Coding Conventions

The coding-conventions.md file is automatically referenced by Copilot when you’re writing code in the repository. Copilot will suggest code that follows our team’s conventions.

Generating Commit Messages

Stage your changes in the Source Control panel
Click the sparkle icon (✨) in the commit message box, or
Use the command palette: Commit: Generate Commit Message
Copilot generates a commit message based on:
- Your current branch name
- The files staged for commit
- The rules defined in commit-guidelines.md

commit-guidelines.md provides Copilot with explicit instructions for how commit messages should be structured. It enforces extraction of the Azure Boards work item ID from the branch name, applies a consistent AB#<id> - <summary> prefix, limits subject length, and requires a concise, file-level summary of changes for every commit.

Commit Message Example:

AB#758500 - Updated Azure Service Bus connection string

helm/values-saas-prd.yaml - Changed Service Bus connection string to match production environment

In the above example, the commit message was generated automatically after updating the Azure Service Bus connection string in helm/values-saas-prd.yaml. Copilot inferred the work item ID from the branch name js_update_prd_sbs_value_758500 and summarized the staged changes according to the guidelines.

Generating Pull Request Titles and Descriptions

Pull request titles and descriptions can be generated using GitHub Copilot within the GitHub Pull Requests extension, following the rules defined in pullrequest-guidelines.md.

Prerequisites:

GitHub Pull Requests extension installed in VS Code
GitHub Copilot enabled
Branch name follows the required pattern: <Developer-Initials>_<short-description>_<User Story ID>
Commits follow the commit message guidelines and reference the correct work item

Steps to Generate a Pull Request Using Copilot:

Open the GitHub Pull Requests panel in VS Code
Click Create Pull Request
Verify:
- Base branch is set to main
- Compare branch is your feature branch
Click the sparkle icon (✨) to invoke GitHub Copilot
Review the generated content and ensure:
- The title follows the format
  Autobots | <User Story ID> | <Developer-Written Summary>
- The description structure matches your expectations
- The work item reference is correct
Make manual edits only to correct factual inaccuracies

Copilot uses the branch name, commit history, and repository context to generate the pull request content and applies the rules defined in the pull request guidelines

Generated Pull Request Example:

Pull Request Title:

Autobots | 758500 | Update Azure Service Bus connection string for SaaS production

Pull Request Description:

# Before submitting your PR, please make sure: 
- [ ] Branch name is like `[YOUR-INITIALS]_[SHORT-DESCRIPTION]_[TICKET-ID]`
- [ ] Commit messages are like `#[TICKET-ID] - [SHORT-DESCRIPTION]`
- [ ] PR title is like `[TEAM-NAME] | [TICKET-ID] | [TICKET-TITLE]`
- [ ] A user story or bug has been linked to the Pull Request
- [ ] The solution builds locally
- [ ] The solution runs without errors locally
- [ ] Unit tests were created to ensure code coverage requirements are met
- [ ] All unit tests were run and passed
- [ ] Ran lint testing and addressed all linting issues (0 errors and 0 warning)
- [ ] Merged latest MAIN and resolved all merge conflicts
- [ ] Properly captured the changes in the User Story so QA can pick up the work
- [ ] If API changes are being made the openapi.yaml is updated to reflect the endpoint changes
- [ ] Changes were demoed to the QA team
AB#758500
Updated the Azure Service Bus connection string to align with the production environment
`helm/values-saas-prd.yaml` - Changed Service Bus connection string to match production environment

The above example was generated using GitHub Copilot using the pull request guidelines. It demonstrates:

Correct title formatting
A single work item reference
A concise, factual high-level summary
An explicit file-by-file change list

Troubleshooting

Copilot Not Using Custom Instructions

Ensure the .github/copilot-instructions/ folder exists in your repository
Verify the file paths in settings.json are correct
Restart VS Code after making changes to settings.json
Make sure you’re working in a repository that contains the instruction files

Settings Not Taking Effect

Check that your settings.json has valid JSON syntax (no missing commas or brackets)
Ensure GitHub Copilot extension is up to date
Try reloading the VS Code window: Ctrl+Shift+P → “Developer: Reload Window”

Commit Message Generation Issues

Commit message generation may fail when too many files are staged or when changes are excessively large (for example, package-lock.json updates)
Stage a subset of files and generate a commit message
Save the generated message separately
Stage the remaining files and generate their commit message
Combine both messages before committing all files