Contributor Guide
We ♥️ Contributions!
awesome-azd is a community-friendly resource to help developer discover, create, and share, open-source azd templates and supporting resources for streamlining your application development and CI/CD pipelines.
Submit a PR
Contribute a New Template
Our template gallery will be at its best when our community is involved in creating and contributing new templates.
We welcome contributions of requested templates as well as any others, subject to review.
To submit a template:
- Add an entry to website/static/templates.json that includes:
- Template title - A short title that reflects the local application stack that someone could use to get their application on Azure (e.g. "Containerized React Web App with Java API and MongoDB")
- Description - 1-2 sentence description of the architecture (e.g. Azure services) or solution that is defined by the template.
- Application Screenshot - Add application UI imagery to the
screenshotfield. Screenshots are shown separately from architecture diagrams on the template detail page. - Architecture Diagram - Add service topology imagery to the
architectureDiagramfield. The diagram should include all services and their connections (example). Add repository-hosted images to website/static/templates/images. - Link to Author's GitHub or other relevant website - Used for attribution.
- Author's Name - Name to credit on the gallery card
- Link to template source - Link to the template GitHub repo
- Tags - Special tags like msft, community, new, featured, and aiapplication, plus services/tools/topics (e.g., mongodb, kubernetes, dapr, helm, ai, enterprisepatterns). The legacy aicollection value is supported only in existing catalog URLs and should not be added to template metadata. If you don't see a relevant tag? Feel free to add one!
- Languages - Tags for languages used in the template (e.g., python, javascript, dotnetCsharp).
- Frameworks - Tags for frameworks used in the template (e.g., reactjs, fastapi, django).
- Azure Services - Tags for Azure services used in the template (e.g., aca, functions, openai, cosmosdb, azuresql).
- IaC - Infrastructure as Code tag (bicep or terraform).
- ID - Please provide a unique uuid.
- Add the template's normalized GitHub repository URL and at least one reviewed primary use case to website/src/catalog/template-use-cases.json. This mapping is required for the template to appear in the unified catalog.
- If the template is Microsoft-authored, we encourage you to also publish it to learn.microsoft.com/samples.
- Open a PR!
- If possible, add a link to the PR in your repo where you made your app
azdcompatible to the PR description. This will help us provide feedback on your template and speed up the review process.
If you would like to contribute a template but are not sure where to start, making an existing project azd compatible is a great first step. Doing so consists of three main steps:
- Set up a new environment (with
azd init) - Add Bicep files
- Update azure.yaml
Automated Template Submission
For a faster submission experience, use the automated pipeline:
- Submit a template issue — Fill out the form with your template details
- Automatic validation — A workflow validates your repository, adds the required catalog use-case mapping, and creates a PR automatically
- Review & merge — A maintainer reviews and approves the PR
Submit a Resource
Did you write or find an article that helped you get started with azd? Or maybe you created or found a video that showed you how to create an azd template? Whatever the resource might be, we would love for you to share it with our community! Submit content you think should be included in awesome-azd/README.md
Other Ways To Help
Other than these, we always welcome feedback through a:
- request a template: if you cannot find a template with architecture that works for you-- you can submit a request for that template
- Keep in mind, templates are made to be flexible and extensible. You can use a template's architecture and swap out the source code. For example, if you want to create a grocery list making application using Azure SQL and Azure App service, you can use the React Web App with C# API and SQL Database on Azure template and swap out the source code.
- bug report: let us know if something is broken
- feature request: for improvements to our awesome-azd site
Next Steps
- Visit our FAQ