Skip to content

Contributing to Agentic InfraOps

Thank you for your interest in contributing! Agentic InfraOps revolutionizes how IT Pros build Azure environments through coordinated AI agents.

This file is the quick contributor entrypoint. For the agent orchestration workflow, see Agent Architecture.

What We're Looking For

High-Priority Contributions

  1. Agent Improvements
  2. Enhancements to existing agents (.github/agents/*.agent.md)
  3. Better prompts and handoff patterns

  4. Additional validation checks

  5. Documentation

  6. Workflow improvements (workflow.md)
  7. Better examples and use cases

  8. Troubleshooting guides

  9. Best Practices

  10. Bicep and Terraform patterns and templates
  11. Azure Verified Module usage examples (Bicep and AVM-TF)
  12. Security and compliance guidance

Contribution Guidelines

Before You Start

  1. Check existing issues - Someone might already be working on it
  2. Open an issue - Discuss your idea before investing time

Branching and PRs (Canonical)

Protected main branch

Direct pushes to main are blocked. All changes must go through a pull request with passing status checks and at least one approval.

This repo uses a protected main branch. Contributions land via pull requests with required checks and review.

Code Standards

Bicep:

// Use consistent naming conventions
// Include parameter descriptions
// Add output values
// Follow Azure naming best practices

Terraform:

# Use consistent naming conventions (CAF)
# Variables in variables.tf with descriptions and validation
# Outputs in outputs.tf
# AVM-TF modules preferred over raw resources
# Provider pinned to ~> 4.0 (AzureRM)

Documentation Standards

  • Use clear, concise language
  • Include code examples
  • Document prerequisites
  • Use Mermaid for diagrams

Markdown Linting

This repository uses markdownlint for consistent formatting.

Running the linter:

# Check for issues
npm run lint:md

# Check links (docs/ only)
npm run lint:links

# Auto-fix issues
npm run lint:md:fix

Contribution Process

1. Fork & Clone

Contributing to the upstream project

For using Agentic InfraOps, create your own repo from the Accelerator template. The instructions below are for contributing back to this upstream project.

git clone https://github.com/YOUR-USERNAME/azure-agentic-infraops.git
cd azure-agentic-infraops
git remote add upstream https://github.com/jonathan-vella/azure-agentic-infraops.git

2. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

3. Make Your Changes

  • Follow the guidelines above
  • Test any Bicep changes with bicep build and bicep lint
  • Test any Terraform changes with terraform fmt -check, terraform validate, and npm run validate:terraform
  • Validate markdown and links with npm run lint:md and npm run lint:links

For the full local-to-PR flow, see:

4. Commit & Push

git add .
git commit -m "feat: add diagram generator improvements"
git push origin feature/your-feature-name

Note: commit message format is enforced by hooks and CI.

Commit Message Format (Required)

Enforced by commitlint

Commit messages are validated automatically before each commit. Non-conforming messages will be rejected with a helpful error.

This repository uses Conventional Commits with automated enforcement.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Type Description Version Bump
feat New feature Minor (1.x.0)
fix Bug fix Patch (1.0.x)
docs Documentation only changes None
style Code style (formatting, semicolons) None
refactor Code refactoring (no functional change) None
perf Performance improvements None
test Adding or updating tests None
build Build system or dependencies None
ci CI/CD configuration None
chore Maintenance tasks None
revert Reverting a previous commit None

Breaking Changes

For breaking changes, add ! after the type or include BREAKING CHANGE: in the footer:

# Breaking change indicator
git commit -m "feat!: redesign agent workflow architecture"

# Or with footer
git commit -m "feat: new output structure

BREAKING CHANGE: agent outputs now go to agent-output/ folder"

Breaking changes trigger a major version bump (x.0.0).

Examples

# Feature (minor version bump)
git commit -m "feat: add terraform validation agent"
git commit -m "feat(bicep): add diagnostic settings module"

# Bug fix (patch version bump)
git commit -m "fix: correct resource naming in Key Vault module"
git commit -m "fix(docs): update broken quickstart links"

# No version bump
git commit -m "docs: update workflow documentation"
git commit -m "chore: update dev container configuration"
git commit -m "refactor: simplify agent handoff logic"

Validation

Commits are automatically validated by the commit-msg hook. If your commit message doesn't follow the format, you'll see a helpful error with examples.

5. Create Pull Request

  1. Go to your fork on GitHub
  2. Click "New Pull Request"
  3. Fill out the PR template
  4. Link related issues

Pull Request Checklist

Before submitting:

  • [ ] Code follows repository standards
  • [ ] Documentation updated if needed
  • [ ] Markdown files pass linting (npm run lint:md)
  • [ ] Docs links pass checks (npm run lint:links)
  • [ ] Bicep templates validate (bicep build + bicep lint) if applicable
  • [ ] Terraform configs validate (terraform validate + terraform fmt -check) if applicable
  • [ ] No hardcoded secrets or subscription IDs
  • [ ] Links work correctly

Community Standards

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • No harassment or discrimination

Getting Help

  • Questions: GitHub Discussions
  • Issues: GitHub Issues

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for helping improve the Azure infrastructure workflow!