> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server. # Copilot Instructions Setup 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](https://cla.service-now.com/esc?id=sc_cat_item_guide\&table=sc_cat_item\&sys_id=628ae9819377a69076e0f2aa7bba1087)) --- ## Instruction File Templates * **Coding Conventions:** [coding-conventions.md](/engineering/development/developer-onboarding/instruction-files/coding-conventions) * **Commit Guidelines:** [commit-guidelines.md](/engineering/development/developer-onboarding/instruction-files/commit-guidelines) * **Pull Request Guidelines:** [pullrequest-guidelines.md](/engineering/development/developer-onboarding/instruction-files/pullrequest-guidelines) --- ## 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: ```json "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: ```json "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: ```json { // ... 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 1. Stage your changes in the Source Control panel 2. Click the sparkle icon (✨) in the commit message box, or 3. Use the command palette: **Commit: Generate Commit Message** 4. 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# - ` 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: `__` * Commits follow the commit message guidelines and reference the correct work item --- **Steps to Generate a Pull Request Using Copilot:** 1. Open the **GitHub Pull Requests** panel in VS Code 2. Click **Create Pull Request** 3. Verify: * Base branch is set to `main` * Compare branch is your feature branch 4. Click the **sparkle icon (✨)** to invoke GitHub Copilot 5. Review the generated content and ensure: * The title follows the format\ `Autobots | | ` * The description structure matches your expectations * The work item reference is correct 6. 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:** ```markdown Autobots | 758500 | Update Azure Service Bus connection string for SaaS production ``` **Pull Request Description:** ```markdown # 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 --- ## Additional Resources * [GitHub Copilot Documentation](https://docs.github.com/en/copilot) * [VS Code Settings Documentation](https://code.visualstudio.com/docs/getstarted/settings)