Home / Contribute

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.

Adding content

Two contribution shapes

A new scenario

01-scenarios/<Scenario-Name-Agent>/

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

02-patterns/<Pattern-Name>/

Patterns ship as a pair: <PatternName>.md for the decision-oriented overview and <PatternName>-Runbook.md for the implementation detail used during delivery.

Scenario artefacts

The four files every scenario needs

Naming

Hyphens, not underscores

Folder and file names use Title-Case-With-Hyphens so links stay predictable across the repository.

βœ… Correct

Enterprise-RAG-Pattern/Folder
Enterprise-RAG-Pattern.mdOverview
Enterprise-RAG-Pattern-Runbook.mdRunbook

❌ Incorrect

Enterprise_RAG_Pattern/Underscores
EnterpriseRAGPattern.mdNo separators
enterprise_rag_runbook.mdLower case
Before your first pull request

The 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.

How to contribute

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.

Only fixing a typo or a broken link? You can skip the command line. Open the file on GitHub, select the pencil icon (Edit this file) and follow the prompts β€” GitHub forks the repository for you and walks you through proposing the change. For anything bigger, use the steps below.
The big picture

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

upstream

microsoft/ai-agent-runbooks on GitHub. Only maintainers change it.

Your fork

origin

Your personal copy on GitHub. You can change it freely.

Your computer

local clone

The 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.

Part 1

One-time setup

Do these three steps once. You will not need to repeat them for later contributions.

  1. 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 at github.com/<your-username>/ai-agent-runbooks in the address bar.
  2. 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-runbooks
    Prefer SSH? Use git@github.com:<your-username>/ai-agent-runbooks.git instead. The first clone can take a few minutes, which is normal.
  3. 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 -v
    You should see two names, each listed twice (fetch and push): origin is your fork and upstream is the original.
Part 2

Every time you contribute

Repeat these six steps for each change: a new scenario, a new pattern or a fix.

  1. 4

    Sync your fork with the original

    Always start from the latest version. Fetch downloads what is new; merge applies it to your main branch.

    # 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 main
    You never commit to main yourself (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 run git checkout main followed by git pull on your computer.
  2. 5

    Create a branch for your change

    A branch is a separate workspace for one change. Make a new one for every contribution, so main stays 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-overview or add-hr-onboarding-scenario.

    Never commit directly to the main branch. Keep it as a clean mirror of the original, so syncing in step 4 always works.
  3. 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.
  4. 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/main
    Nothing 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.

    1. Open each listed file and find the markers <<<<<<<, ======= and >>>>>>>.
    2. Keep the content that should survive, respecting the changes already made upstream, and delete the markers.
    3. Save the file, then continue:
    git add <file>
    git rebase --continue

    Changed your mind? git rebase --abort takes 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/main

    An editor opens with your commits listed. Leave the first one as pick, change the others to squash (or s), then save and close. A second editor lets you write the combined commit message.

  5. 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:

    1. 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.)
    2. Check the direction: the base is microsoft/ai-agent-runbooks on main, and the head is your fork and your branch.
    3. Give it a clear title and a short description: what changed, why, and any related issue.
    4. 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-lease flag stops it overwriting work you have not seen.

    git push --force-with-lease origin <branch-name>
  6. 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 run git branch -d <branch-name>) and start your next contribution from a fresh branch.

Stuck on a step? Ask a question and we will help. First-time contributors are very welcome.
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
Disclaimer

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.

Please read before using this content
01 Content accuracy & currencyReflects product capabilities at the time of authoring. Features, interfaces, APIs and behaviours may change without notice β€” verify before use.
02 No Microsoft supportCommunity-driven and not an officially supported Microsoft product. Microsoft Support (CSS) does not assist with this content.
03 Deployment responsibilityAny deployment is the sole responsibility of the customer or user β€” including compliance, security, data privacy and validation.
04 Use at your own riskProvided β€œas-is”, without warranty of any kind, express or implied, and with no guarantee of completeness or suitability.
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.