Contribute
This repository grows from field delivery. Found a bug, a broken link, an outdated step β or delivered something worth writing down? We would love to hear from you. No GitHub experience needed.
Two contribution shapes
A new scenario
Create a self-contained folder using the standard four artefacts so any engineer can pick it up and deliver it consistently. Add your scenario to the table in the section README.
A new pattern
Patterns ship as a pair: <PatternName>.md for the decision-oriented overview and
<PatternName>-Runbook.md for the implementation detail used during delivery.
The four files every scenario needs
Hyphens, not underscores
Folder and file names use Title-Case-With-Hyphens so links stay predictable across the repository.
β Correct
Enterprise-RAG-Pattern/FolderEnterprise-RAG-Pattern.mdOverviewEnterprise-RAG-Pattern-Runbook.mdRunbookβ Incorrect
Enterprise_RAG_Pattern/UnderscoresEnterpriseRAGPattern.mdNo separatorsenterprise_rag_runbook.mdLower caseThe Contributor Licence Agreement
Most contributions require you to agree to a Contributor Licence Agreement, confirming you have the right to grant us the rights to use your contribution. When you open a pull request, a CLA bot works out whether you need one and guides you through it β you only do this once across all Microsoft repositories that use the CLA.
This project has adopted the Microsoft Open Source Code of Conduct. Use of Microsoft trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.
Your first pull request, step by step
A pull request is how you suggest a change: you work on your own copy of the repository, then ask the
maintainers to bring your changes into the original. Never done it before? Follow the steps in order and
copy the commands as you go. You will need a GitHub account, Git on your computer
(git --version shows whether it is installed) and any text editor, such as Visual Studio Code.
Three copies of the repository
Git gives each copy a short name, and you will meet upstream and origin in the
commands below. Text highlighted like <your-username> is a placeholder:
replace it with your own value.
The original
upstreammicrosoft/ai-agent-runbooks on GitHub. Only maintainers change it.
Your fork
originYour personal copy on GitHub. You can change it freely.
Your computer
local cloneThe copy on your machine, where you edit files and save changes.
Other people's new work travels the other way: when you sync (step 4) it comes from the original straight to your computer.
One-time setup
Do these three steps once. You will not need to repeat them for later contributions.
-
1
Fork the repository
A fork is your own copy of the repository on GitHub, so you can change it freely without touching the original. Open the repository, select Fork at the top right, then Create fork.
Create your fork on GitHub β
You should see your own copy atgithub.com/<your-username>/ai-agent-runbooksin the address bar. -
2
Clone your fork to your computer
Cloning downloads your fork so you can edit the files. Run the commands in a terminal: Git Bash, PowerShell, Terminal or the terminal inside Visual Studio Code.
git clone https://github.com/<your-username>/ai-agent-runbooks.git cd ai-agent-runbooksPrefer SSH? Usegit@github.com:<your-username>/ai-agent-runbooks.gitinstead. The first clone can take a few minutes, which is normal. -
3
Connect your clone to the original repository
Add the original repository as a second remote called
upstream. This is how you will pick up other people's latest changes later.# Add the original repository under the nickname "upstream" git remote add upstream https://github.com/microsoft/ai-agent-runbooks.git # Check the result git remote -vYou should see two names, each listed twice (fetch and push):originis your fork andupstreamis the original.
Every time you contribute
Repeat these six steps for each change: a new scenario, a new pattern or a fix.
-
4
Sync your fork with the original
Always start from the latest version. Fetch downloads what is new; merge applies it to your
mainbranch.# Switch to your main branch git checkout main # Download the latest changes from the original repository git fetch upstream # Apply them to your main branch git merge upstream/main # Optional: update your fork on GitHub as well git push origin mainYou never commit tomainyourself (see step 5), so this is always a clean update with no conflicts. Prefer clicking? On your fork's GitHub page choose Sync fork β Update branch, then rungit checkout mainfollowed bygit pullon your computer. -
5
Create a branch for your change
A branch is a separate workspace for one change. Make a new one for every contribution, so
mainstays clean and each pull request stays small and easy to review.# Create a branch from the up-to-date main and switch to it git checkout -b <branch-name>Pick a short, descriptive name, for example
fix-broken-link-overvieworadd-hr-onboarding-scenario.Never commit directly to themainbranch. Keep it as a clean mirror of the original, so syncing in step 4 always works. -
6
Make your changes and commit them
Edit or add files in your editor. Follow the standards above: hyphenated Title-Case names, the four standard files for a scenario, the overview and runbook pair for a pattern. Then add a row for your work to the table in its section README.
# See what you changed git status # Stage your changes, ready to be saved git add . # Save them as a commit with a short message: what changed and why git commit -m "Add Invoice Triage scenario"You can commit as many times as you like while you work.
This repository is public. Never commit secrets, credentials or customer-confidential information. -
7
Refresh and tidy up before you submit
While you worked, other people may have merged their changes. Rebase replays your commits on top of the latest
main, so your pull request merges cleanly.# Download the latest changes git fetch upstream # Replay your commits on top of them git rebase upstream/mainNothing new upstream? Git simply reports that your branch is up to date. That is fine.Git stopped with a conflict?
A conflict means someone else changed the same lines as you. Git pauses and lists the affected files.
- Open each listed file and find the markers
<<<<<<<,=======and>>>>>>>. - Keep the content that should survive, respecting the changes already made upstream, and delete the markers.
- Save the file, then continue:
git add <file> git rebase --continueChanged your mind?
git rebase --aborttakes you back to where you were before the rebase.Optional: combine small commits into one
Lots of tiny commits ("fix typo", "oops") clutter the history. An interactive rebase lets you squash them into a few clear ones.
git rebase -i upstream/mainAn editor opens with your commits listed. Leave the first one as
pick, change the others tosquash(ors), then save and close. A second editor lets you write the combined commit message. - Open each listed file and find the markers
-
8
Push your branch and open the pull request
# Upload your branch to your fork on GitHub git push origin <branch-name>Then, on GitHub:
- Open your fork. A banner offers Compare & pull request: select it. (No banner? Choose your branch from the branch menu, then Contribute β Open pull request.)
- Check the direction: the base is
microsoft/ai-agent-runbooksonmain, and the head is your fork and your branch. - Give it a clear title and a short description: what changed, why, and any related issue.
- Select Create pull request.
First pull request? A bot checks whether you need to agree to the Contributor Licence Agreement (see above). If it asks, follow its instructions. You only do this once.Push rejected after a rebase or squash?
Rewriting commits you have already pushed changes your branch's history, so a normal push is refused. Use a forced push on your own branch only: the
--force-with-leaseflag stops it overwriting work you have not seen.git push --force-with-lease origin <branch-name> -
9
Respond to review, then clean up
A maintainer reviews your pull request and may ask for changes. Make them on the same branch, commit and push again. The pull request updates automatically.
git add . git commit -m "Address review feedback" git push origin <branch-name>Once it is merged, sync your fork again (step 4), which also switches you back to
main. Then delete the finished branch (GitHub shows a Delete branch button; on your computer rungit branch -d <branch-name>) and start your next contribution from a fresh branch.
For maintainers: test and merge a pull request
This part is for the people who handle incoming pull requests. In your clone of the original repository,
origin is microsoft/ai-agent-runbooks itself, with no fork in between.
1. Try the pull request locally (optional)
Replace 123 with the pull request number shown on GitHub.
# Download the pull request into a local branch
git fetch origin pull/123/head:pr-123
# Switch to it and try it out
git checkout pr-123
Treat it as a read-only test copy. Review comments belong on the pull request page.
2. Merge on GitHub (the usual way)
When GitHub reports no conflicts, select Merge pull request on the pull request page, then Confirm merge.
3. Or merge from the command line
Useful when you want to check or adjust the result before it lands on main.
# Check out the branch you are merging into
git checkout main
# Download the contributor's branch and merge it in one go
git pull https://github.com/<contributor>/ai-agent-runbooks.git <branch-name>
# Publish the result
git push origin main
Read this before you use anything here
A community-driven project, not an officially supported Microsoft product, provided as-is. Four things to know before you build on this content.
Read the full disclaimer
Please read the following disclaimers carefully before using any content in this repository.
1. Content accuracy and currency
The content, configurations, architecture diagrams, and implementation guidance included in this repository reflect information and product capabilities available at the time of authoring. Microsoft products and services β including Microsoft Copilot Studio, Azure AI Foundry, and Microsoft 365 Copilot β are continuously updated, and features, interfaces, APIs, and behaviors may change without notice following a product update or release.
Users are responsible for verifying that the guidance in this repository remains applicable and accurate against the current version of the relevant Microsoft products and services before use in any project or production environment.
2. No Microsoft support
This repository is a community-driven project and is not an officially supported Microsoft product. Content is contributed and maintained by Microsoft employees and community members acting in a voluntary capacity.
Microsoft Support (CSS) does not provide assistance, troubleshooting, or incident response for issues arising from the use of content in this repository. For official product support, please use the Microsoft Support portal or your designated Microsoft support channel.
3. Deployment responsibility
Any deployment of AI Agent solutions derived from or informed by the content in this repository is the sole responsibility of the customer or user performing the deployment. This includes, but is not limited to:
- Ensuring compliance with applicable laws, regulations, and organizational policies
- Validating configurations, integrations, and data handling practices in your target environment
- Managing access controls, security configurations, and data privacy requirements
- Testing and validating agent behavior prior to production release
Microsoft and the contributors to this repository assume no liability for any damages, data loss, service disruption, or compliance violations resulting from the use or deployment of content from this repository.
4. General use at own risk
This repository is provided βas-isβ, without warranty of any kind, express or implied. The authors and contributors make no representations or guarantees regarding the completeness, reliability, suitability, or availability of any content within this repository for any particular purpose. Use of this repository and its contents is entirely at your own risk.
Source of record: 00-overview Β· Disclaimer. Trademark guidance is covered by Microsoftβs Trademark & Brand Guidelines.