DEV Community: Andrew

🚀 Copilot Velocity Hub - Transform Your Dev Workflow with AI

Andrew — Fri, 13 Mar 2026 14:41:57 +0000

🎬 Live Project

Repository: GitHub - copilot-velocity-hub

What I Built

After seeing several posts about Copilot Plugin Marketplaces following this post from GitHub, I decided to see what all the fuss was about. I mostly Vibe Coded a production-ready Next.js application that transforms GitHub Copilot CLI into an intuitive, beautifully designed productivity hub. Instead of wrestling with terminal commands, developers can now access powerful AI-assisted tools through a modern web interface with real-time output streaming.

🎯 The Problem I Solved

GitHub Copilot CLI is incredibly powerful, but it requires terminal fluency. Copilot Velocity Hub makes these capabilities accessible to developers of all skill levels with an elegant, responsive web application that executes complex tasks with a single click.

✨ Key Features

🎨 Beautiful Modern UI - Production-grade SaaS design with smooth animations and terminal-style output display
⚡ Fast & Responsive - Built with Next.js 16, React 19, and TailwindCSS 4
🔌 4 Powerful Built-in Plugins:
- 📄 Generate README - Create comprehensive, well-structured project documentation instantly
- 🔗 Summarize Git Commits - Analyze git history and generate professional changelogs
- 🧪 Generate Test Cases - Scaffold unit and integration tests following best practices
- 🔍 Repository Review - Comprehensive code quality, security, and architecture audits
🔒 Security First - No command injection vulnerabilities, strict whitelist validation, sandboxed execution
📦 Extensible - Add new plugins in 2 minutes with minimal code changes
🧪 Production Ready - Full TypeScript, comprehensive error handling, Jest test suite, security hardened

📸 The Experience

Homepage - Clean & Intuitive

Beautiful Terminal-Style Output

🚀 Getting Started (2 Minutes)

# 1. Clone the repository
git clone https://github.com/ghostinthewires/copilot-velocity-hub.git
cd copilot-velocity-hub

# 2. Install dependencies
npm install

# 3. Ensure Copilot CLI is authenticated
copilot auth login

# 4. Start development server
npm run dev

Then open http://localhost:3000 and start boosting your productivity!

📋 Requirements

Node.js 18.0.0+
npm 9.0.0+
Git (latest)
GitHub Copilot CLI (installed globally: npm install -g @github-copilot/cli)
GitHub Account (for Copilot authentication)

Quick verify:

node --version          # v18.0.0+
npm --version           # 9.0.0+
copilot --version       # 1.x+
copilot auth login      # Authenticate once

My Experience with GitHub Copilot CLI

🎯 Why I Chose Copilot CLI

I wanted to showcase how powerful Copilot CLI becomes when integrated into a real-world application. Rather than building a simple demo, I created a production-grade platform that brings AI-assisted development to the entire team, regardless of terminal proficiency.

The key insight: Copilot CLI is powerful, but buried in the terminal. What if we gave it a beautiful, user-friendly interface that the entire team could use?

💡 How I Used Copilot CLI

1. Direct Process Execution

The application executes Copilot CLI commands securely:

import { exec } from 'child_process';

export async function executePlugin(promptText: string): Promise<string> {
  return new Promise((resolve, reject) => {
    exec(`copilot prompt "${promptText}"`, 
      { maxBuffer: 10 * 1024 * 1024, timeout: 30000 },
      (error, stdout, stderr) => {
        if (error) reject(error);
        resolve(stdout);
      }
    );
  });
}

2. Specialised Prompts for Each Plugin

Each plugin sends carefully crafted prompts:

Generate README Plugin:

const prompt = `Analyze this project and create a comprehensive README.md file that includes:
- Project description and purpose
- Features overview
- Installation instructions
- Usage examples
- Contributing guidelines
- License information

Format the output as valid Markdown.`;

Summarize Commits Plugin:

const prompt = `Review the recent git commit history and generate a structured CHANGELOG that:
- Groups changes by category (Added, Changed, Fixed, Removed)
- Highlights breaking changes
- Includes commit references
- Follows semantic versioning conventions

Make it suitable for release notes.`;

Generate Tests Plugin:

const prompt = `Analyze the codebase and generate comprehensive test cases that:
- Cover happy path scenarios
- Include edge case handling
- Test error conditions
- Follow Jest best practices
- Are well-documented with clear assertions`;

Repository Review Plugin:

const prompt = `Perform a detailed code review of this repository covering:
- Code quality and architecture
- Security vulnerabilities
- Performance opportunities
- Testing coverage gaps
- Best practices compliance
- Refactoring suggestions

Prioritize by impact and severity.`;

3. Real-Time Output Streaming

Users see results appear instantly in a beautiful terminal-style interface as Copilot processes each prompt.

🎨 Why This Approach Works

For Individual Developers:

✅ Quick access to AI-powered code analysis without CLI commands
✅ Beautiful output display makes results easy to read
✅ Copy-to-clipboard makes integration seamless
✅ All available at a single web URL

For Teams:

✅ Standardised AI-assisted workflows across the team
✅ No terminal knowledge required
✅ Audit trail of AI suggestions
✅ Easy to add team-specific plugins

For Organisations:

✅ Can be deployed as internal tool
✅ Consistent code quality practices
✅ Reduced security review time
✅ Accelerated documentation generation

🚀 Impact on Development Experience

Dramatically Improved:

✅ Accessibility: Non-terminal users now leverage Copilot CLI effectively
✅ Efficiency & Speed: 2-minute setup, Plugins execute 3-5 complex tasks quickly
✅ Quality: AI-assisted documentation, testing, and reviews improve consistency
✅ Scalability: Easy to add new plugins without core code modifications
✅ Safety: Robust error handling and security validation prevent issues

What Copilot CLI Enabled:

Professional Documentation - Generate README files that meet industry standards
Intelligent Changelogs - Structured release notes from commit analysis
Comprehensive Test Suites - Coverage suggestions and test scaffolding
Smart Code Reviews - Architecture, security, and quality recommendations
Team Alignment - Consistent coding standards through AI analysis

🎓 Key Learning Journey

Building Copilot Velocity Hub taught me:

Process Management: Safely integrating CLI tools into web applications
Security: Preventing command injection while enabling CLI integration
User Experience: Making complex AI outputs accessible and beautiful
Plugin Architecture: Designing extensible systems for easy feature addition
Modern Web Stack: Next.js 16, React 19, TypeScript, and testing best practices
Error Handling: Graceful degradation and user-friendly error messages

⚡ Performance & Reliability

The application is optimised for:

30-second timeout on plugin execution (prevents hanging processes)
10MB output buffer (handles large analysis outputs safely)
Real-time streaming (users see progress immediately)
Error recovery (graceful degradation if Copilot CLI fails)
Fast builds (<3 seconds with Next.js)
Responsive UI (page loads in <500ms)

🔐 Security Considerations

I implemented multiple layers of protection:

Whitelist Validation - Only registered plugins can execute
No User Input - Prompts are hardcoded per plugin (no injection risk)
Process Isolation - Child processes run with strict resource limits
Buffer Limits - Prevents memory exhaustion from large outputs
Error Containment - Safe error messages without sensitive data leakage
Environment Isolation - Separate process context for each execution

💬 Why This Matters

GitHub Copilot CLI is revolutionary for developer productivity, but it lives in the terminal. By creating Copilot Velocity Hub, I've demonstrated:

Copilot CLI can power sophisticated, production-ready web applications
AI tools don't need to be complex - they can be beautifully simple
Teams can standardise on AI-assisted workflows without tribal knowledge
Security and usability are complementary, not opposing forces
Modern web frameworks make integration straightforward and safe

📊 Project Highlights

Metric	Value
Build Time	<3 seconds
Dev Startup	~5 seconds
Page Load	<500ms
TypeScript Coverage	100% of source code
Security Vulnerabilities	0 (audited)
Pre-built Plugins	4 powerful, extensible
Test Coverage	Comprehensive Jest suite
Documentation	Detailed guides
Code Quality	Production-ready

🚀 Getting More from Copilot CLI

Custom Plugins

Want to extend Copilot Velocity Hub? Adding new plugins is straightforward:

const customPlugin = {
  id: 'api-docs-generator',
  name: 'Generate API Docs',
  description: 'Auto-generate OpenAPI/Swagger documentation',
  icon: '📚',
  copilotPrompt: 'Generate comprehensive API documentation with examples...'
};

Integration Ideas

CI/CD Pipeline - Trigger analysis on every commit
Code Review Bot - Use plugin outputs in PR comments
Slack Bot - Execute plugins and post results to channels
VS Code Extension - Embed directly in the editor
Desktop App - Package with Electron or Tauri

🙏 Credit & Resources

GitHub Copilot CLI - The powerful backbone
Next.js - Modern web framework
React - Latest React features
TailwindCSS - Beautiful styling
TypeScript - Type safety
Based On - This project
Jest - Testing framework

🎉 Closing Thoughts

Copilot Velocity Hub proves that GitHub Copilot CLI's power extends far beyond the terminal. By combining security, usability, and AI capabilities, we can build tools that genuinely accelerate development workflows.

Whether you're:

A developer wanting to learn Next.js
A team looking to standardise AI-assisted workflows
An organisation seeking to improve code quality consistently
A learner exploring AI integration patterns

...this project provides a solid, production-ready foundation.

The code is clean, well-documented, secure, and ready to extend. Contributions are welcome!

🚀 Start Your Journey

Ready to boost your development velocity?

git clone https://github.com/ghostinthewires/copilot-velocity-hub.git
cd copilot-velocity-hub
npm install && npm run dev

Then visit http://localhost:3000 and experience the future of AI-assisted development.

Have questions or ideas? Open an issue or submit a pull request on GitHub!

Connect on LinkedIn

More than a decade of Azure: What I’d Do Again and What I Regret

Andrew — Mon, 02 Mar 2026 15:15:29 +0000

Reflecting on two decades of leading technology transformations. Global FinTech SaaS platforms processing millions of transactions. AI-driven automation that reclaimed hundreds of person-days. High-pressure private equity exits. Kubernetes clusters that bridged the gap from legacy to cloud-native. Terraform state files that moved the needle for global consultancies.

I’ve seen the "cloud-native" definition shift multiple times. This is the post I wish someone had written for me when I started my journey through the ranks. moving through roles as a DevOps Engineer, an Engineering Lead and now Senior DevOps Manager, I’ve navigated the Azure ecosystem's growth from a "Windows-first" cloud to a powerhouse of Linux, Kubernetes, and AI.

Every decision below is something I’ve either shipped to production and would do again, or something I’ve spent months deconstructing to pay down technical debt.

If I were starting a greenfield project today, or stepping into a new role, here is how I would weigh the decisions that actually move the needle on business outcomes.

No theoretical fence-sitting. No playing it safe with vendor-neutrality. This is the raw reality of scaling Azure under pressure.

Azure

🟩 Endorse

Picking Azure over AWS

The Azure Advantages (Why I’d do it again):

The Container Gold Mine: AWS AppRunner is a non-starter. If you want true serverless containers that actually scale to zero, Azure Container Apps (ACA) is the industry leader. Similarly, AKS feels like a cohesive product, whereas EKS often feels like a collection of parts you have to bolt together yourself.
Identity that Works: Microsoft Entra ID (formerly Azure AD) is the undisputed heavyweight champion. Compared to the headache of AWS Cognito, Entra ID is a robust, enterprise-grade solution that I’ve relied on to secure highly regulated, global platforms.
The Developer Ecosystem: Between GitHub Actions and Azure DevOps, the CI/CD story is just tighter. When you’re pushing for on-time delivery, having your repos, boards, and pipelines in one ecosystem is a massive force multiplier.

The AWS Envy (The "Regrets" and Hurdles):

Networking Flexibility: I’ll be honest, Route 53 is easier to wield than Azure DNS. AWS handles global routing and health checks with a level of simplicity that Azure's Front Door and Traffic Manager can sometimes overcomplicate.
Tooling & Local Dev: Azure still lacks a true "LocalStack" equivalent. Being able to emulate the entire cloud locally is a huge win for AWS developers. In the Azure world, we rely more on emulators like Azurite, but it’s not quite the same "cloud-in-a-box" experience.
Deployment Velocity: There’s no sugar-coating it, Azure Resource Manager (ARM) and even some Bicep deployments can be painfully slow. Watching a gateway or a firewall provision for 20 minutes is a "coffee break" I’d rather not have to take.
The Talent War: It’s still a reality that finding AWS-specialised engineers is easier on the open market. Building the high-performing Azure teams I have led in the past required more internal "up-skilling" and intentional training programs because the talent pool is shallower.
Security Group Fatigue: While Azure’s NSGs and ASGs are logical, tracing a routing issue through multiple VNet peers and UDRs (User Defined Routes) can become "complicated AF" compared to the more fluid networking model AWS sometimes offers.

The Bottom Line:

I’ve shipped on both. AWS might have the "easy" button for networking and local dev, but for enterprise-scale automation, serverless maturity, and AI-driven efficiency, I’m putting my money on the Azure stack every single time.

Azure Container Apps (ACA) vs AKS

🟩 What I Endorse: Use Azure Container Apps (ACA) for the majority of microservices. In previous years, we went straight to AKS (Azure Kubernetes Service). While I’ve successfully utilised Kubernetes to optimize cloud operations for global organisations, the cognitive load on the team is significant. ACA provides the "Serverless Container" experience that allows teams to scale to zero and focus on the code, not the control plane. Having managed 24/7 operational environments, I’ve learned that the best infrastructure is the one you don't have to babysit. ACA gives you the "Serverless Container" benefit without the "Kubernetes Tax."

🟧 What I regret: Using AKS (Azure Kubernetes Service) for small, product-focused teams. I regret the times I built a full K8s orchestration layer for a simple API. Unless you have the resilient team structures in place to manage the complexity of ingress controllers, service meshes, and node pools, it’s an unnecessary tax on productivity.

Azure SQL vs Cosmos DB

🟩 What I Endorse: Default to Azure SQL (Hyperscale or Managed Instance) for 80% of enterprise workloads. Relational data is the backbone of sectors like Insurance and Finance. I’ve found that the reliability and familiar tooling of SQL Server, scaled via Azure’s elastic tiers, solve most business problems without the complexity of distributed NoSQL. Azure SQL is battle-tested. It scales, it’s familiar, and it’s consistently reliable for the heavy lifting I've overseen.

🟧 What I regret: Using Cosmos DB as a "catch-all" database.
Cosmos DB is incredible for global scale and low-latency NoSQL needs. However, I regret using it in scenarios where the data schema was actually quite rigid. If you don't need global distribution or a flexible schema, Cosmos DB is an expensive way to realize you should have just used a JOIN. Cosmos DB is an engineering marvel, but the cost of mismanagement (improper partitioning) is high. I now reserve Cosmos for specific, high-scale event stores rather than general-purpose storage.

Terraform vs Bicep

🟩 What I Endorse: Stick with Terraform for hybrid and multi-cloud environments. My experience reflects a heavy reliance on Terraform and ARM templates because consistency is king. Its ability to manage state and provide a platform-agnostic language is vital when coordinating hybrid cloud infrastructure. In lots of previous roles I championed the migration of applications to Azure; Terraform provided the common language that allowed us to bridge the gap between legacy on-prem and cloud enablement.

🟧 What I regret: Waiting too long to adopt Azure Bicep for Azure-only projects. If you are 100% in the Azure ecosystem, the "Day 0" support for new features in Bicep is superior to waiting for provider updates in Terraform. When I first started working with the cloud it was in AWS, and the regret was often not using CDK. In Azure, the regret is sticking with verbose, nested ARM Templates for too long. For Azure-native shops, Bicep offers a much cleaner abstraction. While I still champion Terraform for the "big picture," I regret not moving our Azure-specific modules to Bicep sooner to lower the cognitive load for the team. However, for the strategic, global portfolios I manage now, Terraform remains the gold standard for state management and modularity.

Azure Functions vs Logic Apps

🟩 What I Endorse: A "Functions-first" approach for event-driven logic. Utilising C# and Python Functions has allowed my teams to focus on product development rather than infrastructure patching. It’s the ultimate tool for reducing technical debt while maintaining a high velocity. Functions Triggers have "reactivity" baked into the DNA. You aren't writing "glue code" just to move an event to a HTTP call, the integration with Service Bus and Blob Storage is seamless and saves weeks of development time.

🟧 What I regret: Building complex business logic directly into Logic Apps. While Logic Apps are great for "no-code" glue between SaaS products, they are a nightmare for version control, unit testing, and complex CI/CD pipelines. I regret not moving that logic into Azure Functions earlier, where we could apply proper software engineering rigor.

Application Insights & Log Analytics vs Tool Sprawl

🟩 What I Endorse: Investing heavily in Application Insights from day zero. You cannot manage a 24/7 operational environment without a unified view. Also, shifting the perception of IT within an organisation requires data. By leveraging Azure Monitor and App Insights, I’ve been able to show stakeholders real-time dashboards that link system health to business value.

🟧 What I regret: Relying on fragmented third-party monitoring tools.
In high-pressure 24/7 environments, "tool sprawl" is the enemy. I regret the times we had separate logs for the app, the network, and the database that didn't talk to each other. Consolidating into a unified Log Analytics workspace is nearly always the better move.

Azure Kubernetes Service Node Auto-Provisioning (NAP)

🟩 Endorse

If you’re running AKS without Azure Kubernetes Service Node Auto-Provisioning (NAP), which manages the open source project Karpenter, you’re essentially burning money.

In the old world, the Cluster Autoscaler was the bottleneck: slow, rigid, and constantly fighting with manual Node Pool configurations. In the modern Azure ecosystem, Node Auto-Provisioning (based on the Karpenter model) is the game-changer. It’s fast, intelligent, and provisions the exact VM sizes your pods actually need in real-time.

Drawing from my experience optimising cloud operations for global SaaS platforms, we’ve seen 30-40% cost reductions on compute after moving away from static node pools.

Spot Instance Handling: It actually works without the "eviction anxiety" of the past.

True Consolidation: It proactively scales down and moves workloads to ensure you aren't paying for "ghost" capacity.

Real Bin-Packing: No more half-empty D-Series VMs sitting idle; the scheduler finally treats your compute like a fluid resource.

The learning curve: Getting your head around NodePool objects, Provisioning configuration, and taints/tolerations, is real. But for any strategic portfolio in 2026, this isn't an "add-on", it’s a non-negotiable requirement for a resilient, cost-efficient infrastructure.

KEDA (Kubernetes Event-Driven Autoscaling)

🟩 Endorse for Azure event-driven workloads

In my time directing technology transformations, I’ve seen too many teams rely on standard HPA (Horizontal Pod Autoscaler) scaling on CPU/Memory. That’s a blunt instrument. KEDA is the precision tool. While HPA watches your hardware, KEDA watches your business logic: Azure Service Bus queue depth, Event Hub lag, or Storage Queue message counts.

If you’re running workers that process insurance claims or property management updates, KEDA is the answer. We’ve used it to cut costs significantly on batch processing workloads that used to sit idle 24/7 "just in case." Now, they scale to zero when the queue is empty and ramp up instantly based on the actual backlog.

Where it shines in the Azure Stack:

Azure Service Bus / Storage Queues: Scaling based on activeMessageCount. This is the "gold standard" for async processing.

Azure Event Hubs: Scaling based on partition lag to ensure you aren't falling behind on high-throughput data streams.

Scheduled Jobs: Using cron-based scaling for predictable peak periods (e.g., end-of-month reporting), which often outperforms standard Kubernetes CronJobs for long-running processes.

Azure Monitor/Log Analytics: Scaling on custom KQL (Kusto) metrics that your application exposes.

Where it doesn’t:

Request-based scaling: If you're scaling a public-facing API based on traffic, stick with HPA + Azure Application Gateway/Ingress metrics.

Latency-sensitive "Instant-on" workloads: If your application cannot handle a cold start from zero, keep a minimum replica count.

The Strategy: Use KEDA (ScaledObjects) for your async workers and background processors, and HPA for your synchronous REST APIs. They coexist perfectly in the same AKS cluster, one handles the reactive "pull" work, the other handles the proactive "push" traffic.

The Actual Lessons:

Two decades in the trenches have distilled my architectural "religion" down to these hard-won truths. If you’re building on Azure in 2026, this is the blueprint.

Non-negotiable:

AKS + Node Auto-Provisioning (NAP): If you aren't using the Karpenter-based model, you’re burning money on static node pools.

Azure Container Apps (ACA) for Microservices: Stop paying the "Kubernetes Tax" for simple APIs. Focus on the code, not the control plane.

Entra ID (Azure AD): The undisputed heavyweight champion of identity. If you aren't using it to secure your global platforms, you're creating a headache for your future self. Use it for everything. OIDC federation is the only way to kill long-lived CI credentials.

Terraform for the Big Picture: Its ability to manage state and provide a platform-agnostic language is vital for coordinating hybrid cloud infrastructure.

KEDA for Async Workers: If it’s an event-driven consumer, scale on queue depth, not CPU. Precision scaling based on Azure Service Bus depth or Event Hub lag. Scale to zero or fail your budget.

Application Insights from Day Zero: End-to-end observability is the only way to manage 24/7 operational environments and shift the perception of IT within an organisation.

Avoid at all costs:

Logic Apps for Complex Logic: It’s a CI/CD and unit-testing nightmare. Keep the "glue" in Azure Functions.

Cosmos DB as a "Catch-all": It’s an expensive way to store relational data. Unless you truly need global sub-10ms latency, stick to Azure SQL. Reserve it for global-scale NoSQL, not rigid schemas.

AKS for Small Teams: Don't build a full K8s orchestration layer for a simple API unless you have the platform team to babysit it.

Tool Sprawl: Fragmented third-party monitoring is the enemy of incident response. Stop paying for three different monitoring tools that don't talk to each other. Consolidate into a unified Log Analytics workspace.

Verbose ARM Templates: Don't stay in the "nested ARM" world for Azure-native projects; the cognitive load isn't worth it.

Niche wins worth knowing:

Innersourcing: The most effective way to improve culture and reduce technical debt across global silos.

The Meta-Lessons:

Ship Business Outcomes, Not Infrastructure: My most successful projects weren't because of a "perfect" cluster; they were because the infrastructure allowed the product to scale without the team burning out.

Boring Technology is Resilient Technology: The C# Azure Function that’s been running for three years without a restart is worth more than the experimental service mesh that requires a weekly post-mortem.

Automation is Your Legacy: In a high-pressure environment automation isn't a luxury, it’s your only defense against chaos.

Business Observability: If your logs and metrics don't link system health to business value in 15 minutes, your architecture is too clever for its own good.

Connect on LinkedIn

Introducing Our Engineering Progression Framework

Andrew — Tue, 28 Jun 2022 14:45:58 +0000

At the beginning of 2022 we wrapped up the first version of our Engineering Progression Framework. Now we’ve been using it internally for a little while, we also wanted to share it more widely, to help others learn more about Engineering here.

A progression framework is a communication tool that supports fairness

Before we jump into the details, here’s a quick overview of what we mean when we talk about a "progression framework".

Quite simply, it’s a set of shared expectations that we use to explain what we expect of engineers at different levels of seniority. Each level is described in the framework with a description, plus an illustration of the type of behaviours, impact, and skills we think are reflective of someone at that level.

However, importantly, it’s not an exhaustive checklist. We’ve intentionally focused on a core set of examples that we think can fairly apply to any engineer here, but they’re not intended as a finite list of everything a great engineer could do or be. People will almost certainly be doing important things that aren’t in the framework. There are many 'shapes' of engineers, and we’ll aim to celebrate people’s different strengths whilst also aiming for fairness and clarity through our core expectations.

We’re pretty pleased with the result, but we’re not finished!

We’re planning to keep making improvements as we change and grow, but for now you can take a peek at what we’re using below:

Engineers
Engineering Managers

Historically in the engineering space the only way for engineers to progress was through stopping coding and moving into management. We believe these are fundamentally different sets of skills, and we want to make sure all our engineers have the opportunity to progress without changing career. That said, for many folks, moving into management and creating systems to help engineers do their best is where they find their future lies, so you can see we support a switch of framework once engineers reach a certain level. We’re also planning to support folks who want to "swing on the engineer/manager pendulum", and switch back to engineering after a couple of years.

What’s next?

This framework will naturally evolve as we apply it – it will never be finished or perfect, and it is to be considered a living document, so our teams and our managers will help steer this.

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

The Engineering Handbook

Andrew — Fri, 17 Jun 2022 08:48:11 +0000

We’ve been working on codifying some of our working practices here into an Engineering Handbook.

I've found that the key ingredients to empower autonomous teams are ownership, trust, and a common language.

We want every team to own our customers’ success. As opposed to a static command and control model, we start from a position of trust in every team and continually work together to verify the quality, security, and reliability of a product.

We then scale this practice by ensuring our engineers have a common language. This includes a set of principles, rituals, and expectations to which they can align. The outcome is a loosely coupled and highly aligned system that empowers our teams to move fast, make decisions, and come up with innovative solutions that propel us forward.

Take a look at our live Engineering Handbook

We want to share the way we work with everyone, to help improve teams across industries. Hopefully, our learnings will help you build autonomous teams and ingrain ownership in your own organisation.

If you would like to build your own Engineering Handbook, feel free to fork my GitHub Repo.

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

Tech Radar for visualising Technology Strategy. What is it and how to build it?

Andrew — Wed, 15 Jun 2022 11:35:18 +0000

In this blog post I would like to share my knowledge about a very useful tool that helps you to visualise your Technology Strategy — Tech Radar.

Also, at the end of this blog I will share the live Tech Radar from my organisation and a link to my GitHub Repo so you can build your own!

What is a Tech Radar?

Tech Radar uses two categorising elements: the quadrants and the rings. The quadrants represent different kinds of blips. The rings indicate what stage is in an adoption lifecycle.

The quadrants are a categorisation of the type of blips:

Languages and Frameworks. As it suggests, things such as C#, Java etc
Tools. These could be software development tools, such as code scanners, Terraform etc.
Platforms & Infrastructure. Things that we build software on top of such as Azure, Salesforce etc
Techniques. These include elements of a software development process, such as Continuous Delivery ; and ways of structuring software, such as Microservices.

The Tech Radar also has four rings:

The Adopt ring is for Technologies you have high confidence in to serve your purpose. Technologies with a usage culture in your production environment, low risk and recommended to be widely used.
The Trial ring is for Technologies that you have seen work with success in project work to solve a real problem; first serious usage experience that confirm benefits and can uncover limitations. Trial technologies are slightly more risky; some engineers in your organisation may have walked this path and will share knowledge and experiences.
The Assess ring is for Technologies that are promising and have clear potential value-add for you; technologies worth investing some research and prototyping efforts in to see if it has impact. Assess Technologies have higher risks; they are often brand new and highly unproven in your organisation. You will find some engineers that have knowledge in the technology and promote it, you may even find teams that have started a prototyping effort.
The Hold ring is for Technologies not recommended to be used for new projects. Technologies that we think are not (yet) worth to (further) invest in. Hold technologies should not be used for new projects, but usually can be continued for existing projects.

Why do you need a Tech Radar?

Firstly, creating the Tech Radar is a very valuable exercise. It helps you to do an audit of your portfolio. Finding the potential risks and blind spots.
It gives more transparency into your Technology Department. The Tech Radar helps your teams and architects choose the best technologies for future projects. It shows the current state of your technology landscape and teams can choose the best tools and technology that are already adopted in your company.
If you keep your Tech Radar public (like we do) it can be very beneficial for your recruitment and Engineering brand. On one hand potential candidates can see the technology stack of the company. On the other hand you will be able to understand whether the knowledge and experience of the candidate are suitable for your environment.

How to create and update?

The Tech Radar is a living tool. And you should keep this tool up to date because this is your current technology landscape and the future target.

Depending on the size of your organisation, updating the radar can be done by the community of the most active engineers (like we do), team leaders, architects or a special department.

It is advisable to check and update the radar at least once every 6 months. Check legacy technologies, whether it’s time to change them to new ones that have passed the adaptation period. And check current radar for your target technology strategy.

When you introduce new technologies or tools in your teams — check with your Tech Radar. Perhaps the new technology is already being tested in another team and you will save time & effort.

Our live Tech Radar!

So as promised at this start of this blog, here is our live Tech Radar

Using our Tech Radar you can trace the usage and adaptation of many technologies and languages in our organisation.

For example, you can see that GitHub Actions are currently running in Adopt mode — a CI/CD service that is used to build and deploy services, to run automated tests, deploy IaC etc.

Also, here is the link to my GitHub Repo which you can fork to build your very own Tech Radar!

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

Would I replace Terraform with Bicep ? 💪🏽

Andrew — Thu, 10 Mar 2022 14:21:25 +0000

For a long time I have been a huge fan of Terraform by Hashicorp for deploying my Azure cloud services. This is mainly due to finding ARM templates to be too verbose and cumbersome to work with - Microsoft’s response to these complaints is Bicep.

This week I decided to take a look at what all the fuss is about & see if I might replace Terraform with Bicep.

What is Bicep?

Bicep is a declarative language that is classified as a domain-specific language (DSL) for deploying Azure resources.

The goal of this language is to make it easier to write Infrastructure as Code (IaC) targeting Azure Resource Manager (ARM) using a syntax that’s more friendly than the JSON syntax of Azure ARM Templates.

Bicep works as an abstraction layer built on top of ARM Templates. Anything that can be done with Azure ARM Templates can be done with Bicep as it provides a "transparent abstraction" over ARM (Azure Resource Manager). With this abstraction, all the types, apiVersions, and properties valid within ARM Templates are also valid with Bicep.

Bicep is a compiled / transpiled language. This means that the Bicep code is converted into ARM Template code. Then, the resulting ARM Template code is used to deploy the Azure resources. This transpiling enables Bicep to use it’s own syntax and compiler for authoring Bicep files that compile down to Azure Resource Manager (ARM) JSON as a sort of intermediate language (IL).

The way that Bicep is transpiled into ARM JSON is similar to how there are many different languages that can be written in, then transpiled into JavaScript that can be run within the web browser. One popular example of this type of transpiled language is TypeScript. A transpiled language offers benefits of adding an abstraction layer to make it easier and / or more feature full to write code that then gets compiled down to IL code that gets executed. This is also similar to how C# and VB.NET code compile down to MSIL in .NET code.

In the development world, it’s common to encounter the use of transpiled languages. It’s also common in the DevOps world where YAML and JSON are converted between one or the other. Bicep offers some similarity in how it’s transpiled into ARM JSON. This enables you to use an alternative syntax and feature set for writing declarative Infrastructure as Code than the often-cumbersome ARM JSON syntax.

Bicep Benefits

Support for all resource types and API versions.
Better authoring experience using editors such as VS Code (you will get validation, type-safety, intellisense).
Modularity can be achieved using modules. You can have modules representing an entire environment or a set of shared resources and use them anywhere in a Bicep file.
Integration with Azure services such as Azure Policy, Templates specs, and Blueprints.
No need to store a state file or keep any state. You can even use the what-if operation to preview your changes before deploying them.
Bicep is open source with a strong community supporting it. All the binaries for the different supported operating systems can be downloaded from the official releases page of the Bicep open source project.

Bicep pre-requisites

The tooling is pretty much the same as for ARM templates. That means that you need the following:

Either Azure PowerShell or Azure CLI. (I’ll use Azure CLI in this post, as I find it much more logical)
The Bicep CLI (more on this in a second)
Some form of text editor. I suggest VS Code as it can provide some pretty awesome help when working with Bicep templates
Optional: The VS Code Bicep extension. This will give you superpowers when working with Bicep in VS Code

Note: I’m going to assume that you have the Azure CLI installed.

Bicep CLI

To be able to work with Bicep files instead of ARM templates, you need the Bicep CLI. This is the part of the tool chain that is responsible for transpiling Bicep files to and from ARM templates. Yes…to AND from! More on that later!

The Bicep CLI is installed by running:

az bicep install

Or…if you are using Azure CLI version 2.20.0 or above, you can just ignore that step, as the Bicep CLI will be automatically installed when you run a command that needs it. So, in most cases, you don’t need to do anything to get Bicep file support on your machine.

Note: If you are on an earlier version of the Azure CLI, I would recommend updating that, instead of manually installing the Bicep CLI.

To verify your Azure CLI version, you can run:

az version

{
  "azure-cli": "2.34.1",
  ...
}

And to verify the installed version of the Bicep CLI you can run:

az bicep version

Bicep CLI version 0.4.1272

If you try running this command without having the Bicep CLI installed, you get an error message that says

Bicep CLI not found. Install it now by running "az bicep install".

And, as the error message says, you fix that by running az bicep install, or any Bicep related command that will automatically install it.

If you have an outdated Bicep CLI version, and want to update it to the latest and greatest, you just need to run:

az bicep upgrade

Once you have the Bicep CLI installed (or just want to ignore it and have the Azure CLI install it when needed), you need a text editor of some kind to edit the Bicep files.

VS Code and the Bicep extension

I would highly recommend using VS Code when working with Bicep files. The reason for this, besides it being light-weight, cross platform, fast and generally quite awesome, is the ability to install the Bicep extension that gives you extra help when working with Bicep files.

The Bicep extension is available from the marketplace. Just search for bicep and you will find it.

That’s actually all there is to it from a tooling point of view.

Bicep Syntax

Every Bicep resource will have the below syntax:

resource <symbolic-name> '<resource-type>@<api-version>` = {  
  //properties
  name: 'ghostinthewiresstorage'
  location: 'westeurope'  
  properties: {
    //...sub properties
  }
}

Where:

resource: is a reserved keyword.
symbolic name: is an identifier within the Bicep file which can be used to reference this resource elsewhere.
resource-type: is the type of the resource you're defining, e.g. Microsoft.Storage.
api-version: each resource provider publishes its own API version which defines which version of the Azure Resource Manager REST API should be used to deploy this resource.
properties: these are the resource specific properties. For example every resource has a name and location. In addition some have sub properties which you can pass on.

Parameters

When we talk about infrastructure as a code and reusability of our templates, we definitely end up using parameters to customise our resources. Be its name, sku, username or password, we will need to change these per environment or application.

In a Bicep file you can define the parameters that need to be passed to it when deploying resources. You can put validation on the parameter value, provide default value, and limit it to allowed values. The format of a parameter will be such as below:

param <parameter-name> <parameter-type> = <parameter-value>

Where:

param: is a reserved keyword.
parameter-name: is the name of the parameter.
parameter-type: is the type of the parameter such as string, object, etc.
parameter-value: is the value of the parameter you're passing in.

Let's review two examples to get a better understanding of the structure.

@minLength(6)
@maxLength(21)
param storageName string

In this example you're limiting the storageName parameter's value length to be between 6 and 21 characters. Or:

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageRedundancy string = 'Standard_GRS'

In this example you're specifying the allowed values for the storageRedundancy parameter and also provide the default value if nothing is provided during the deployment.

With ARM templates you had to use a separate file to pass the parameters during the deployments usually with a name ending in .parameters.json. In Bicep you need to use the same JSON file to pass the parameters in:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageName": {
      "value": "myuniquestoragename"
    },
    "storageRedundancy": {
      "value": "Standard_GZRS"
    }
  }
}

Variables

Similar to parameters, variables play an important part in our templates, especially when it comes to naming conventions. These can store complex expressions to keep our templates clean and their maintenance simple. In Bicep variables are defined using the var keyword:

var <variable-name> = <value>

Where variable-name is the name of your variable. For example in our previous Bicep file we could have used a variable for our storage name:

var storageAccName = 'sa${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageAccountName
  //...
}

Since we need a unique name for our storage account the uniqueString function is used (Don't worry about that for now). The point is that we can create variables and use them in our template with ease.

There are multiple variable types you can use:

String
Boolean
Numeric
Object
Array

Expressions

Expressions are used in our templates for variety of reasons, from getting the current location of the resource group to subscription id or the current datetime.

Functions

The good thing is that ANY valid ARM template function is also a valid Bicep function.

param currentTime string = utcNow()

var location = resourceGroup().location

var makeCapital = toUpper('all lowercase')

Output

ARM templates have an output section where you could send information out of your pipeline to be accessed within other deployments or subsequent tasks. In Bicep you have the same concept via the output keyword.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  //...
}

output storageId string = stg.id

Loops

In ARM templates if you wanted to deploy a resource multiple times you could leverage the copy operator to add a resource n times based on the loop count. In Bicep you have the for operator at your disposal:

resource foo 'my.provider/type@2021-03-01' = [for <ITERATOR_NAME> in <ARRAY> = {...}]

Where ITERATOR_NAME is a new symbol that's only available inside your resource declaration.

param containerNames array = [
  'images'
  'videos'
  'pdf'
]

resource blob 'Microsoft.Storage/storageAccounts/blobServices/containers@2019-06-01' = [for name in containerNames: {
  name: '${stg.name}/default/${name}'
  //...
}]

This snippet creates three containers within the storage account in a loop.

Existing keyword

If you want to deploy a resource which is depending on an existing resource you can leverage the existing keyword.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
  name: storageAccountName
}

You won't need the other properties since the resource already exists. You need enough information to be able to identify the resource. Now that you have this reference, you can use it in other parts of your deployment.

Modules

In ARM templates you had the concept of linked templates when it came to reuse a template in other deployments. In Bicep you have modules. You can define a resource in a module and reuse that module in other Bicep files.

.
├── main.bicep
└── storage.bicep

In our storage file you will define the resource, its parameters, variables, outputs, etc:

//storage.bicep
param storageAccountName
var storageSku = 'Standard_LRS'

resource storage 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  kind: 'Storage'
  sku: {
    name: storageSku
  }
}

And in the main file you will reuse the storage account as a module using the module keyword:

//main.bicep
module storage './storage.bicep' = {
  name: 'storageDeploy'
  params: {
    storageAccountName: '<YOURUNIQUESTORAGENAME>'
  }
}

output storageName array = stg.outputs.containerProps

You only need to pass the required properties which in case of our storage account is the name.

The any keyword

There might be some cases where Bicep throws a false positive when it comes to errors or warnings. This might happen based on different situations such as the API not having the correct type definition. You can use the any keyword to get around these situations when defining resources which have incorrect types assigned. One of examples is the container instances CPU and Memory properties which expect an int, but in fact they are number since you can pass non-integer values such as 0.5.

resource wpAci 'microsoft.containerInstance/containerGroups@2019-12-01' = {
  name: 'wordpress-containerinstance'
  location: location
  properties: {
    containers: [
      {
        name: 'wordpress'
        properties: {
          ...
          resources: {
            requests: {
              cpu: any('0.5')
              memoryInGB: any('0.7')
            }
          }
        }
      }
    ]
  }
}

By using any and passing the value you can get around the possible errors which might be raised during the build or the validation stage.

How to Create Bicep Files

As previously mentioned, developers can use Microsoft-provided Visual Studio Code extensions for the Bicep language to enhance the functionality that Bicep brings to the table. These extensions, specifically, provide language support and resource autocompletion to assist with creating and validating Bicep files, reducing coding errors, and making the writing of code more efficient.

One of the nice things with Bicep, compared to ARM templates, is the fact that you don’t need to add any form of "base structure" to make it a valid Bicep file. ARM templates require us to create a JSON root element. In Bicep, as long as the file extension is .bicep, it is considered a Bicep file.

Take a look at the following template Bicep code. Notice the compact code structure; it is maybe half the size of the typical ARM template. Bicep is smart enough to figure out if resources are dependent on each other. Additionally, Bicep knows it first needs to deploy appServicePlan and automatically adds the dependsOn part when it gets converted from Bicep to an ARM template. Here is the code:

param name string = 'ghostinthewires-bicep-webapplication'
param location string = resourceGroup().location
param sample string = 'ghostinthewires'
param sampleCode string = 'G1'
resource webApp 'Microsoft.Web/sites@2022-01-01' = {
  name: name
  location: location
  properties: {
    name: name
    siteConfig: {
      metadata: [
        {
          name: 'MY_TECH_STACK'
          value: 'dotnetcore'
        }
      ]
    }
    serverFarmId: appServicePlan.id
  }
}
resource appServicePlan 'Microsoft.Web/serverfarms@2022-01-01'  = {
  name: name
  location: location
  properties: {
    name: name
  }
  sample: {
    Tier: sample
    Name: sampleCode
  }
}

The following code snippet is used by Bicep for deployment of your resources array, with the link to the template and a link to the parameters file if available.

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2022-01-01",
    "name": "linkedTemplate",
    "properties": {
      "mode": "Incremental",
      "templateLink": {
        "uri": "https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.json",
        "contentVersion": "1.0.0.0"
      },
      "parametersLink": {
        "uri": "https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.parameters.json",
        "contentVersion": "1.0.0.0"
      }
    }
  }
]

Once you have your fully formed Bicep file, we can verify that it is syntactically correct by building it. Building a Bicep file transpiles it to an ARM template.

To build your .bicep file, we can execute the following command:

az bicep build --file iac.bicep

How to Convert ARM Templates to Bicep

Bicep can be easily used to convert an ARM template to Bicep code. The command for this is az bicep decompile. It takes a JSON file as input and attempts to make it into Bicep.

To decompile ARM template JSON files to Bicep, use Azure CLI:

az bicep decompile --file AzureARM.json

Developers can export the template for a resource group and then pass it directly to the decompile command. Refer to the following example:

az group export --name "my_resource_group_name" > AzureARM.json
az bicep decompile --file AzureARM.json

CI/CD

If, like me, you're using GitHub Actions for your CI/CD pipeline, there is already a Bicep action created by Microsoft Developer Advocate Justin Yoo which you can use to build you bicep file and deploy it to Azure.

If you are using Azure Pipelines you can use the Azure CLI task as you would do from your laptop.

Conclusion

I find Bicep much nicer to work with than ARM Templates and looking at it from a purely Microsoft native standpoint, it would also be my bet for the future. Sure, ARM templates need to support pretty much any feature that Bicep uses, in some way. But I think the main focus from Microsoft, when it comes to the end-user experience, will go into Bicep.

However, back to my initial question:

Would I replace Terraform with Bicep ?

In a word, No!

Terraform is a different beast when compared to ARM and Bicep, even if the syntax is actually quite similar to the one used by Bicep.

Under the hood, it works in a completely different way, using the Azure REST API instead of talking directly to the Azure Resource Manager. The downside to this is that any new features being added to Azure will first have to be released in the REST API, then in the Go SDK, and finally in the Terraform Azure provider. A chain of events that might take a while.

Having that said, this is only really an issue if you are using bleeding edge features. If not, pretty much all other features are supported. The flip side to this is obviously that by using a provider-based system, Terraform is able to target a lot of different clouds and systems. Which in turn allows you to use your IaC not only for your Azure resources, but potentially for a bunch of different systems and clouds. Something that ARM/Bicep will never be able to do.

So, if you need to go outside the realm of Azure, where ARM/Bicep is not going to cut it, I still think Terraform is my favoured option. On the other hand, if you are strictly Azure focused, and have no other clouds/systems you want to integrate with, I think Bicep might still be a great option.

But keep in mind, there are also other tools such as Pulumi. An IaC tool that also utilizes the benefit of the provider-based architecture, but also adds the ability to use a real programming language when creating your desired state.

So I would urge you to try out the various options, MVP-style, and see what works for you!

Bonus tip: If you want to play around a bit more with Bicep, I suggest having a look at the Bicep learning path at Microsoft Docs. This will give you a deeper introduction to Bicep in an easy to digest format.

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

How we used DORA metrics to boost deployments, increase automation and more

Andrew — Mon, 28 Feb 2022 16:09:25 +0000

In 2021, I started wondering how I could measure the overall improvements in performance in the engineering department. We were in the early stages of a program of work called North Star. North Star was all about making engineering capability more efficient and flexible in responding to the business needs.

After researching various options, we decided on the DORA metrics. They provided us with all the necessary insights to track our success, and benchmark ourselves against a definition of good.

What is DORA?

DORA is the acronym for the DevOps Research and Assessment group: they’ve surveyed more than 50,000 technical professionals worldwide to better understand how the technical practices, cultural norms, and management approach affect organisational performance.

(Take a dive into the latest DORA Report and in the book that summarizes the findings: Accelerate).

What are the metrics we are using?

Cycle Time - Time between the first commit on a merge request to master and production deployment
Deployment Frequency - Deployment Frequency helps identify the rate at which you are delivering new business value to your customers. Smaller deployments have less risk of going wrong and provide an opportunity to deliver value to your customers in shorter iterations, allowing you to learn quicker.
Change Failure Rate - For the primary application or service you work on, what percentage of changes to production or released to users result in degraded service (e.g., lead to service impairment or service outage) and subsequently require remediation (e.g., require a hotfix, rollback, fix forward, patch)
Throughput (Detecting Burnout) - Throughput gives us a sense of the team's bandwidth. It gives us a picture into how much work we can typically accomplish. Teams should aim for consistent throughput.

How do we understand the metrics?

Cycle Time - Reducing amount of blockers for developers
Deployment Frequency - Limiting amount of code going to production at once (limited batch size)
Change Failure Rate - Improving quality focus, part of our Continuous Testing Strategy.
Throughput (Detecting Burnout) - Paying back technical debt & introducing automation to reduce toil

Following the rules of lean:

Optimize Work In Progress (Cycle Time)
Value is only released to production, once it leaves the factory floor (Deployment Frequency)
Practice Kaizen (Change Failure Rate)
Invest in SRE/DevOps automation (Throughput (Detecting Burnout))

How are the metrics used internally ?

The dashboard is regularly reviewed by the senior engineering management and are discussed and reviewed in our monthly town hall meeting, and our fortnightly Ops Review. Each team is encouraged to reflect on the metrics as they plan their work, and consider improvements they could introduce.

The metrics also influence the decisions and prioritisation. Just as importantly, they help us to transform our company culture.

In terms of changes measured:

Cycle Time as we have not measured it before, the main benefit for us is understanding what we need to improve. In 2021 this actually increased to 18.5 days (due to reasons) but we are currently in the area of 8 days on average for 2022.

Deployment Frequency was improved from once a week to once every 1.4 days (x5 Increase).

Change Failure Rate was about 8% before we started, it is now oscillating between ~3-4%. (50% Decrease)

Throughput (Detecting Burnout) as with Cycle Time we have not measured it before, the main benefit for us is understanding what we need to improve. The throughput per developer per week increased by 93% - however we know why this is (new ways of working, additional code bases etc). We are still keeping a close eye on this to ensure it returns to healthy levels, which so far in 2022, it is!

The main cultural changes were:

We have automated the majority of our deployment pipelines (Using GitHub Actions).
We have moved the bulk of our infrastructure management to a standardised Infrastructure as Code (mainly Terraform).
We have improved our Quality Assurance & Testing process.

We hold the ambition to join the elite performing group of organisations as defined by the State of DevOps report. Each day brings us closer to that goal.

What are our future plans?

On the technical side, we are working to improve automation of the CI/CD pipelines, testing process & Observability.

On the DevOps/DORA culture side, we are providing regular talks and training to wider audiences (not only engineering), to establish DORA as a reference point in future product development. We are also making it a key point of our new consolidated engineering strategy.

I’ve found the DORA metrics helped us improve our software development and delivery processes. With these findings, organisations can make informed adjustments in their process workflows, automation, team composition, tools, and more. I recommend you try this in your organisation too.

Implementing a Continuous Testing strategy for DevOps

Andrew — Thu, 17 Feb 2022 12:09:48 +0000

So, before I jump into our Continuous Testing Strategy, I want to cover off why we want to enhance our testing capability.

At the heart of it, it is to reduce the risk of incidents that could cause loss to the business.

As you can see in the above image, the cost to the business increases exponentially the later a bug is found

The expected outcomes we are aiming for are:

1. To support rapid deployment & decision making
2. To manage and maintain an effective risk appetite
3. To define clear roles and accountability for testing

We will use the Test Automation Pyramid as a strategy guide to planning our DevOps Testing Strategy.

Continuous Testing needs to be a key element in our DevOps testing strategy if we want to successfully implement a DevOps pipeline.

Continuous Testing, which is often called shift-left testing, is an approach to software and system testing in which testing is performed earlier in the software development lifecycle, with the goal of increasing quality, shortening long test cycles and reducing the possibility of software defects making their way into production code.

A best practice is to use test automation to eliminate much of the risk that comes with continuous integration and to get quick feedback on application quality. Pairing continuous integration with test automation enables teams to easily test every new code iteration and reduces the risk of errors occurring in Production.

And as you move further up that pyramid, toward manual tests things generally get slower & more expensive.

However, we have to be careful what we choose to automate & where, as this is not always the case, which is why we will be taking a risk based approach & automating where it is sensible to do so.

And this leads me on to how do we get there ?

I see this as a four-step approach:

Step 1: Setting the Proper Foundations

We needed to understand how the business were currently ensuring the quality of systems and business processes. When and how are applications being tested and how are end-to-end business processes being validated when new technology is deployed?

Step 2: Start with a Project

We wanted to take steps to prove the new approach before making a large-scale investment, and the best way to do that was to identify a project with which to demonstrate the value of testing.

The identified project has a simplified version of the testing capability we want to create, this has been successful and will help pave the way and drive demand for more.

Step 3: Build a Testing Centre of Excellence Programme

We want to establish automated business process validation as a competency. To achieve business value and innovation, the TCOE must be managed the way any business asset is: as an integrated set of repeatable activities focused on producing a positive business outcome. Building a TCOE entails adopting an approach and a technology across the business, but it͛’s more than skill alone. It includes people, processes, technology & tooling – As shown in the image above.

Step 4: Adopt across the business

The single most important aspect to the success of a TCOE is strong executive sponsorship and an executive champion. To move the TCOE forward by effecting change and quantifying the value one project at a time and continue to demonstrate its successes and value through key projects, strong communications and measurable results.

To keep working on the improvements to generate better ROI and establish an environment of quality across the entirety of the business.

Hope this overview of how we plan to implement a Continuous Testing Strategy will help you in your journey as an Engineering Manager / Test Manager 😇

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

So what are we doing about Technical Debt ?

Andrew — Thu, 17 Feb 2022 10:34:43 +0000

For those of you not familiar with the term “Technical Debt” – this is a concept introduced by Ward Cunningham (who is an American software Developer & a co-author of the Manifesto for Agile Software Development.

This can be summarised as: the incremental cost and loss of agility to a company as a result of prior decisions that were made to save time or money when implementing new systems or maintaining existing ones.

Financial debt is a term that most people are well versed in, yet technical debt can have similarly crippling consequences due to the hidden costs that it can incur.

Just like Financial Debt - Technical Debt should be reserved for cases when people have made a considered decision to adopt a design strategy that isn't sustainable in the longer term, but yields a short term benefit. The point is that the debt yields value sooner, but needs to be paid off as soon as possible.

So, how are we going to deal with our Technical Debt ?

So, I've split this into Management & Prevention

First step is to figure out what and how much technical debt we have

Just like financial debt, that has a seniority of what gets paid back first. Technical debt has a similar pattern of seniority; to begin with, we must start with our mission-critical systems. What technical debt do they have? Then look at the wider ecosystem—better put, what technical debt between your systems is causing us expense?

Keep this simple! - Get our top ten ideas and put them into a 2x2 matrix: easy/hard to pay down on one axis and degree of benefits on the other.

2. Next, we need to decide what to do

Once we know what technical debt we have, we now need to decide how to deal with it. There are many options to take.

It may ultimately be best to do nothing. For debt that is either assessed to be “small” or with a “low interest rate,” it may be optimal to just leave it—likewise, if there is significant “prepayment penalty” of paying it off early.
There could also be strategic advantages too. Being one version behind and staying there is usually fine and sometimes has the advantage of letting kinks get worked out on someone else’s money.

Paying back or reducing technical debt will involve replacing systems and taking the cost hit. This can either be done immediately, or over time through a process of gradual improvements. As with financial debt, there are creative ways in which you can “refinance” technical debt, with outsourcing the maintenance being one such way.

A good example is cloud-based software and hardware services – This brings in a comparison to the popularity of lease-based finance. Using cloud services is also an effective tool for reducing technical debt, both in removing CAPEX requirements and shifting the development focus onto the cloud provider.

3. Next, we need to create a payment plan

The main thing to remember here is to not get overwhelmed by the cost of reducing our technical debt and don’t try to pay it off all at once. This would be an ambitious exercise that could overwhelm an organization of any size or balance sheet.

Again, going back to the financial comparisons, we need to have a mentality of paying off the credit card with the highest interest rate first. This simply means attacking high value/low effort activities first.

Managing Technical Debt Going Forward

Once we’ve established our baseline and plan of attack, we are going to want to both preserve that visibility and prevent new debt from creeping in. Think of the exercise as a fresh start and a chance to implement best practices to prevent issues from ever escalating again in the future.

1. Establish best practices in coding and documentation, peer reviews, automated testing etc. Automate processes to perform regression tests / source code analysis. Leverage off the shelf tools like GitHub and SonarQube.

2. Use tracking tools to collect metrics –i.e. defect rate, time spent to refactor, and feature development over time, all of which will drive prioritization decisions.

3. Re-Train Our Underwriters - In simple terms, change management’s job is to ensure that new changes to the company’s technology system don’t impact other systems. They do this by ensuring that the new system complies with standardized methods and procedures. We should be using this process to prevent new debt from being introduced (or at least identify it) – Architecture Review Board to be stood up etc.

Hope this overview of how we plan to tackle technical debt will help you in your journey as an Engineering Manager / Developer 😇

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

Would you like an OpenSource Engineering Handbook Template ? 🚀

Andrew — Wed, 16 Feb 2022 16:42:24 +0000

Launching 🚀

🔥 - An OpenSource Engineering Handbook Template for Engineering Teams who want to go further, faster 🚀

Github Repo Link ⭐

Creating an Engineering Handbook Website from scratch is time-consuming and that's why I have created an OpenSource Engineering Handbook Website Template so Engineering Managers don't have to build their website from scratch. 💯

Instead, Engineering Managers can focus on building better Engineering Teams without worrying about the Engineering Handbook Website itself. 🤘

Features:

Easy to Setup ✅
Free to Use ( OpenSource ) ✅
Fully Responsive ✅
Super Fast and Optimized for SEO ✅

The project is made with HTML, CSS, some JavaScript, and Jekyll. Don't worry if you don't know any, I have provided the instructions on how to use the template and set up your own Engineering Handbook in the README.md file inside the Github Repository.

Check out the Github Repository 👨‍💻
Drop a Github Star ⭐ 😉
Fork the Repository 🍴
Start using it for your own Engineering Handbook 🙌

The Demo Link of the template shows you what it will look like ✅

Hope this Engineering Handbook Template will help you in your journey as an Engineering Manager / Developer 😇

Important 😸

I regularly post useful content related to Azure, DevOps and Engineering on Twitter. You should consider following me on Twitter

How FirstPort are leveraging the power of Open Source to drive continuous code quality

Andrew — Mon, 23 Aug 2021 14:47:59 +0000

Introduction

As many of you will already know, I am Head of Technology at FirstPort.

A key part of my role is delivering FirstPort’s vision of ‘People First’ technology. To do this, it is imperative that I select the right technology to underpin the delivery of services that help make customers’ lives easier.

Today I want to talk about my selection of SonarQube (and a whole host of other cool tools & services such as GitHub Actions, Terraform, Caddy, Let's Encrypt, Docker & more)

SonarQube is the leading tool for continuously inspecting the Code Quality and Security of your codebases and guiding development teams during Code Reviews

Building our Container Image

I did not want to use SonarCloud nor did I want to host this on a VM. So I decided on ACI (Azure Container Instances)

However, when trying to use ACI with an external database I found that any version of SonarQube after 7.7 throws an error:

ERROR: [1] bootstrap checks failed
[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

I found this was because SonarQube uses an embedded Elasticsearch, therefore you need to ensure that your Docker host configuration complies with the Elasticsearch production mode requirements

As the requirements above suggest, in order to fix this it would mean changing the host OS settings to increase the max_map_count, on a Linux OS this would be changing the /etc/sysctl.conf file to update the max_map_count

vm.max_map_count=262144

The problem with ACI is that there is no access to the host, so how can the latest SonarQube (latest version at the time of writing was 9.0.1) be ran in ACI if this cannot be changed.

In this blog I am going to detail the way we run SonarQube in Azure Container Instances with an external Azure SQL database.

Here at FirstPort, we also use Terraform to build the Azure infrastructure and of course GitHub Actions.

Next Steps

The first thing is to address the max_map_count issue, for this we need a sonar.properties file that contains the following setting:

sonar.search.javaAdditionalOpts=-Dnode.store.allow_mmap=false

This setting provides the ability to disable memory mapping in elastic search, which is needed when running SonarQube inside containers where you cannot change the hosts vm.max_map_count. (See Elasticsearch documentation)

Now we have our sonar.properties file we need to create a custom container so we can add that into the setup. A small dockerfile can achieve this:

FROM sonarqube:9.0.1-community
COPY sonar.properties /opt/sonarqube/conf/sonar.properties
RUN chown sonarqube:sonarqube /opt/sonarqube/conf/sonar.properties

This dockerfile is now ready to be built using Docker and pushed to an ACR (Azure Container Registry).

For more info on how to build a container and/or push to an ACR then have a look at the Docker and Microsoft documentation which have easy to follow instructions.

We first build the ACR using Terraform:

resource "azurerm_container_registry" "acr" {
  name                = join("", [var.product, "acr", var.location, var.environment])
  resource_group_name = azurerm_resource_group.rg.name
  location            = azurerm_resource_group.rg.location
  admin_enabled       = true
  sku                 = "Standard"

  tags = local.tags
}

and then use our standard workflow for running Terraform in GitHub Actions

Next we use GitHub Actions to build & push our container image to the ACR setup above. Note the cd container line. This is because we have our dockerfile and sonar.properties files in a folder called container (the sonar folder contains all the Terraform files for the rest of the infrastructure):

name: Build Container Image & Push to ACR
on:
  workflow_dispatch:

jobs:
  build:
    name: Build Container & Push to ACR
    runs-on: ubuntu-latest

    steps:

      - name: Checkout
        uses: actions/checkout@master

      - name: ACR build
        uses: azure/docker-login@v1
        with:
          login-server: acrname.azurecr.io
          username: acrusername
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - run: |
          cd container && docker build . -t acrname.azurecr.io/acrrepo:${{ github.sha }}
          docker push acrname.azurecr.io/acrrepo:${{ github.sha }}

Building the SonarQube Infrastructure

So now that we have a container image uploaded to ACR we can look at the rest of the configuration.

There are a number of parts to create:

File shares
External Database
Container Group
- SonarQube
- Reverse Proxy

At FirstPort our default is to use IaC (Infrastructure as Code), so I will show you how I use Terraform to configure the SonarQube infrastructure.

File Shares

The SonarQube documentation mentions setting up volume mounts for data, extensions and logs, for this I use an Azure Storage Account and Shares.

resource "azurerm_storage_account" "storage" {
  name                     = join("", [var.product, "strg", var.location, var.environment])
  location                 = azurerm_resource_group.rg.location
  resource_group_name      = azurerm_resource_group.rg.name
  account_tier             = "Standard"
  account_replication_type = "RAGZRS"
  min_tls_version          = "TLS1_2"
  tags                     = local.tags
}

resource "azurerm_storage_share" "data-share" {
  name                 = "data"
  storage_account_name = azurerm_storage_account.storage.name
  quota                = 50
}

resource "azurerm_storage_share" "extensions-share" {
  name                 = "extensions"
  storage_account_name = azurerm_storage_account.storage.name
  quota                = 50
}

resource "azurerm_storage_share" "logs-share" {
  name                 = "logs"
  storage_account_name = azurerm_storage_account.storage.name
  quota                = 50
}

External Database

For the external database part I am using Azure SQL Server, a SQL Database and setup a firewall rule to allow azure services to access the database.

By using the random_password resource to create a SQL password no secrets are included and there is no need to know the password as long as the SonarQube Server does.

resource "azurerm_mssql_server" "sql_server" {
  name                         = join("", [var.product, "sql", var.location, var.environment])
  location                     = azurerm_resource_group.rg.location
  resource_group_name          = azurerm_resource_group.rg.name
  version                      = "12.0"
  administrator_login          = "sonaradmin"
  administrator_login_password = random_password.sql_admin_password.result
  minimum_tls_version          = "1.2"

  identity {
    type = "SystemAssigned"
  }

  tags = local.tags
}

resource "azurerm_mssql_server_transparent_data_encryption" "sql_tde" {
  server_id = azurerm_mssql_server.sql_server.id
}

resource "azurerm_sql_firewall_rule" "sql_firewall_azure" {

  name                = "AllowAccessToAzure"
  resource_group_name = azurerm_resource_group.rg.name
  server_name         = azurerm_mssql_server.sql_server.name
  start_ip_address    = "0.0.0.0"
  end_ip_address      = "0.0.0.0"
}

resource "azurerm_mssql_database" "sonar" {
  name      = "sonar"
  server_id = azurerm_mssql_server.sql_server.id
  collation = "SQL_Latin1_General_CP1_CS_AS"
  sku_name  = "S2"

  tags = local.tags
}

resource "random_password" "sql_admin_password" {
  length           = 32
  special          = true
  override_special = "/@\" "
}

Container Group

Setting up the container group requires credentials to access to the Azure Container Registry to run the custom SonarQube container. Using the data resource allows retrieval of the details without passing them as variables:

data "azurerm_container_registry" "registry" {
  name                = "acrname"
  resource_group_name = "acr-rg-name"
}

For this setup we are going to have two containers - the custom SonarQube container and a Caddy container. Caddy can be used as a reverse proxy and is small, lightweight and provides management of certificates automatically with Let’s Encrypt.

The SonarQube container configuration connects the SQL Database and Azure Storage Account Shares configured earlier.

The Caddy container configuration sets up the reverse proxy to the SonarQube instance:

resource "azurerm_container_group" "container" {
  name                = "containergroupname"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  ip_address_type     = "public"
  dns_name_label      = "acrdnslabel"
  os_type             = "Linux"
  restart_policy      = "OnFailure"
  tags                = local.tags

  image_registry_credential {
    server   = data.azurerm_container_registry.registry.login_server
    username = data.azurerm_container_registry.registry.admin_username
    password = data.azurerm_container_registry.registry.admin_password
  }

  container {
    name   = "sonarqube-server"
    image  = "${data.azurerm_container_registry.registry.login_server}/acrrepo:latest"
    cpu    = "2"
    memory = "4"
    environment_variables = {
      WEBSITES_CONTAINER_START_TIME_LIMIT = 400
    }
    secure_environment_variables = {
      SONARQUBE_JDBC_URL      = "jdbc:sqlserver://${azurerm_mssql_server.sql_server.name}.database.windows.net:1433;database=${azurerm_mssql_database.sonar.name};user=${azurerm_mssql_server.sql_server.administrator_login}@${azurerm_mssql_server.sql_server.name};password=${azurerm_mssql_server.sql_server.administrator_login_password};encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30;"
      SONARQUBE_JDBC_USERNAME = azurerm_mssql_server.sql_server.administrator_login
      SONARQUBE_JDBC_PASSWORD = random_password.sql_admin_password.result
    }

    ports {
      port     = 9000
      protocol = "TCP"
    }

    volume {
      name                 = "data"
      mount_path           = "/opt/sonarqube/data"
      share_name           = "data"
      storage_account_name = azurerm_storage_account.storage.name
      storage_account_key  = azurerm_storage_account.storage.primary_access_key
    }

    volume {
      name                 = "extensions"
      mount_path           = "/opt/sonarqube/extensions"
      share_name           = "extensions"
      storage_account_name = azurerm_storage_account.storage.name
      storage_account_key  = azurerm_storage_account.storage.primary_access_key
    }

    volume {
      name                 = "logs"
      mount_path           = "/opt/sonarqube/logs"
      share_name           = "logs"
      storage_account_name = azurerm_storage_account.storage.name
      storage_account_key  = azurerm_storage_account.storage.primary_access_key
    }
  }

  container {
    name     = "caddy-ssl-server"
    image    = "caddy:latest"
    cpu      = "1"
    memory   = "1"
    commands = ["caddy", "reverse-proxy", "--from", "acrrepo.azurecontainer.io", "--to", "localhost:9000"]

    ports {
      port     = 443
      protocol = "TCP"
    }

    ports {
      port     = 80
      protocol = "TCP"
    }
  }
}

Final Configuration

Just follow the SonarQube documentation for your specific source control. Then add the required steps to your application code GitHub Actions workflows, then you will see something like this within the SonarQube dashboard:

Next Steps

Once the container instance is running you probably do not want it running 24/7 so using an Azure Function or Logic App to stop and start the instance when its not needed will definitely save money. I plan to run an Azure Logic App to start the container at 08:00 and stop the container at 18:00 Monday to Friday (I can feel another blog post coming on!)

I hope I could help you learn something new today, and share how we do things here at FirstPort.

Any questions, get in touch on Twitter

// Detect dark theme var iframe = document.getElementById('tweet-1190197872404377600-946'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1190197872404377600&theme=dark" }

How FirstPort execute a Database as Code Strategy using DbUp, Terraform & GitHub Actions

Andrew — Tue, 20 Jul 2021 12:32:17 +0000

Introduction
- Goals
- DbUp
- HTML report
- Create the DbUp console application
- Program.cs file
- GitHub Actions Configuration
- Summary

Introduction

As many of you will already know, I am Head of Technology at FirstPort.

Today I want to talk about my selection of DbUp

DbUp is an open-source .NET library that helps you to deploy changes to SQL Server databases. It tracks which SQL scripts have been run already, and runs the change scripts that are needed to get your database up to date.

You could ask the question why DbUp and not EF Migrations?

I have used a lot of them and I have to say that DbUp seems to me the most pure solution. I don’t like C# "wrappers" to generate SQL for me. DDL is an easy language and I don’t think we need a special tool for generating it.

Here at FirstPort, we also use Terraform to build the Azure SQL infrastructure and of course GitHub Actions. The focus of today however will mainly be on DbUp and the GitHub Action workflows.

Goals

There are a number of goals we are aiming for:

We want it to be simple
We want it to be repeatable
We want to use the same process for dev, QA and production deployments of our changes

DbUp

At its core, DbUp is a script runner. Changes made to the database are done via a script:

Script001_AddTableX.sql
Script002_AddColumnFirstPortIdToTableX.sql
Script003_AddColumnCustomerIdToTableX.sql

DbUp runs through a console application you write yourself, so you control which options to use, and you don’t need a lot of code.

You bundle those scripts and tell DbUp to run them. It compares that list against a list stored in the destination database. Any scripts not in that destination’s database list will be run. The scripts are executed in alphabetical order, and the results of each script are displayed on the console. Very simple to implement and understand.

Checking whether journal table exists..
Journal table does not exist
Is upgrade required: True
Beginning database upgrade
Checking whether journal table exists..
Journal table does not exist
Executing Database Server script 'DbUpLeaseExtract.BeforeDeploymentScripts.001_CreateLeaseExtractSchemaIfNotExists.sql'
Checking whether journal table exists..
Creating the [SchemaVersions] table
The [SchemaVersions] table has been created
Upgrade successful
Success!

That works great when you’re deploying to a development or test environment. At FirstPort we prefer our DBAs to approve scripts before going to production. Maybe a staging or pre-production environment as well. This approval process is essential, especially when you first start deploying databases.

HTML report

Migration scripts are a double-edged sword. You have total control, which gives you great power. However, it’s also easy to mess up. It all depends on the type of change being done and the SQL skills of the writer. The DBA's trust in the process will be low when inexperienced C# developers are writing these migration scripts.

At FirstPort we added some code to generate a HTML report. It is an extension method where you give it the path of the report you want to generate. That means this section goes from:

                var result = upgrader.PerformUpgrade();

                // Display the result
                if (result.Successful)
                {
                    Console.ForegroundColor = ConsoleColor.Green;
                    Console.WriteLine("Success!");
                }
                else
                {
                    Console.ForegroundColor = ConsoleColor.Red;
                    Console.WriteLine(result.Error);
                    Console.WriteLine("Failed!");
                }

To:

            if (args.Any(a => a.StartsWith("--PreviewReportPath", StringComparison.InvariantCultureIgnoreCase)))
            {
                // Generate a preview file so GitHub Actions can generate an artifact for approvals
                var report = args.FirstOrDefault(x => x.StartsWith("--PreviewReportPath", StringComparison.OrdinalIgnoreCase));
                report = report.Substring(report.IndexOf("=") + 1).Replace(@"""", string.Empty);

                var fullReportPath = Path.Combine(report, "UpgradeReport.html");

                Console.WriteLine($"Generating the report at {fullReportPath}");

                upgrader.GenerateUpgradeHtmlReport(fullReportPath);
            }
            else
            {
                var result = upgrader.PerformUpgrade();

                // Display the result
                if (result.Successful)
                {
                    Console.ForegroundColor = ConsoleColor.Green;
                    Console.WriteLine("Success!");
                }
                else
                {
                    Console.ForegroundColor = ConsoleColor.Red;
                    Console.WriteLine(result.Error);
                    Console.WriteLine("Failed!");
                }
            }
        }

This code will generate a report containing all the scripts that will be run.

Create the DbUp console application

With the above features, we put together a .NET Core DbUp console application to deploy to Azure SQL. Then we will put together a process in GitHub Actions to run that console application.

I chose .NET Core over .NET Framework because it could be built and run anywhere. DbUp is a .NET Standard library. DbUp will work just as well in a .NET Framework application.

Let’s fire up our IDE of choice and create a .NET Core console application. I am using VSCode to build this console application. I prefer it over full blown Visual Studio.

The console application needs some scripts to deploy. I’m going to add three folders and populate them with some script files:

I recommend you add a prefix, such as 001, 002, etc., to the start of your script file name. DbUp runs the scripts in alphabetical order, and that prefix helps ensure the scripts are run in the correct order.

By default, .NET will not include those scripts files when the console application is built, and we want to include those script files as embedded resources. Thankfully, we can easily add a reference to those files by including this code in the .csproj file:

    <ItemGroup>
        <EmbeddedResource Include="BeforeDeploymentScripts\*.sql" />
        <EmbeddedResource Include="DeploymentScripts\*.sql" />
        <EmbeddedResource Include="PostDeploymentScripts\*.sql" />
    </ItemGroup>

The entire file looks like this:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net5.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
        <EmbeddedResource Include="BeforeDeploymentScripts\*.sql" />
        <EmbeddedResource Include="DeploymentScripts\*.sql" />
        <EmbeddedResource Include="PostDeploymentScripts\*.sql" />
    </ItemGroup>

    <ItemGroup>
      <PackageReference Include="dbup-sqlserver" Version="4.5.0" />
    </ItemGroup>

</Project>

Program.cs file

The final step to get this application going is to add in the necessary code in the Program.cs to call DbUp. The application accepts parameters from the command-line, and GitHub Actions will be configured to send in the following parameters:

ConnectionString: For this demo, we are sending this as a parameter instead of storing it in the config file.
PreviewReportPath: The full path to save the preview report. The full path parameter is optional. When it is sent in we generate a preview HTML report for GitHub Actions to upload to Azure Blob storage. When it is not sent in, the code will do the actual deployment.
Let’s start by pulling the connection string from the command-line argument:

         static void Main(string[] args)
        {
            var connectionString = args.FirstOrDefault(x => x.StartsWith("--ConnectionString", StringComparison.OrdinalIgnoreCase));

            connectionString = connectionString.Substring(connectionString.IndexOf("=") + 1).Replace(@"""", string.Empty);

DbUp uses a fluent API. We need to tell it about our folders, the type of script each folder is, and the order we want to run scripts in. If you use the Scripts Embedded In Assembly option with a StartsWith search, you need to supply the full NameSpace in your search.

            var upgradeEngineBuilder = DeployChanges.To
                .SqlDatabase(connectionString, null)
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.BeforeDeploymentScripts."), new SqlScriptOptions { ScriptType = ScriptType.RunAlways, RunGroupOrder = 0 })
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.DeploymentScripts"), new SqlScriptOptions { ScriptType = ScriptType.RunOnce, RunGroupOrder = 1 })
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.PostDeploymentScripts."), new SqlScriptOptions { ScriptType = ScriptType.RunAlways, RunGroupOrder = 2 })
                .WithTransactionPerScript()
                .LogToConsole();

            var upgrader = upgradeEngineBuilder.Build();

            Console.WriteLine("Is upgrade required: " + upgrader.IsUpgradeRequired());

The upgrader has been built, and it is ready to run. This section is where we inject the check for the upgrade report parameter. If that parameter is set, do not run the upgrade. Instead, generate a report for GitHub Actions to upload to Azure Blob storage:

            if (args.Any(a => a.StartsWith("--PreviewReportPath", StringComparison.InvariantCultureIgnoreCase)))
            {
                // Generate a preview file so GitHub Actions can generate an artifact for approvals
                var report = args.FirstOrDefault(x => x.StartsWith("--PreviewReportPath", StringComparison.OrdinalIgnoreCase));
                report = report.Substring(report.IndexOf("=") + 1).Replace(@"""", string.Empty);

                var fullReportPath = Path.Combine(report, "UpgradeReport.html");

                Console.WriteLine($"Generating the report at {fullReportPath}");

                upgrader.GenerateUpgradeHtmlReport(fullReportPath);
            }
            else
            {
                var result = upgrader.PerformUpgrade();

                // Display the result
                if (result.Successful)
                {
                    Console.ForegroundColor = ConsoleColor.Green;
                    Console.WriteLine("Success!");
                }
                else
                {
                    Console.ForegroundColor = ConsoleColor.Red;
                    Console.WriteLine(result.Error);
                    Console.WriteLine("Failed!");
                }
            }

When we put it all together, it looks like this:

using System;
using System.IO;
using System.Linq;
using System.Reflection;
using DbUp;
using DbUp.Engine;
using DbUp.Helpers;
using DbUp.Support;

namespace DbUpLeaseExtract
{
    class Program
    {
        static void Main(string[] args)
        {
            var connectionString = args.FirstOrDefault(x => x.StartsWith("--ConnectionString", StringComparison.OrdinalIgnoreCase));

            connectionString = connectionString.Substring(connectionString.IndexOf("=") + 1).Replace(@"""", string.Empty);

            var upgradeEngineBuilder = DeployChanges.To
                .SqlDatabase(connectionString, null)
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.BeforeDeploymentScripts."), new SqlScriptOptions { ScriptType = ScriptType.RunAlways, RunGroupOrder = 0 })
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.DeploymentScripts"), new SqlScriptOptions { ScriptType = ScriptType.RunOnce, RunGroupOrder = 1 })
                .WithScriptsEmbeddedInAssembly(Assembly.GetExecutingAssembly(), x => x.StartsWith("DbUpLeaseExtract.PostDeploymentScripts."), new SqlScriptOptions { ScriptType = ScriptType.RunAlways, RunGroupOrder = 2 })
                .WithTransactionPerScript()
                .LogToConsole();

            var upgrader = upgradeEngineBuilder.Build();

            Console.WriteLine("Is upgrade required: " + upgrader.IsUpgradeRequired());

            if (args.Any(a => a.StartsWith("--PreviewReportPath", StringComparison.InvariantCultureIgnoreCase)))
            {
                // Generate a preview file so GitHub Actions can generate an artifact for approvals
                var report = args.FirstOrDefault(x => x.StartsWith("--PreviewReportPath", StringComparison.OrdinalIgnoreCase));
                report = report.Substring(report.IndexOf("=") + 1).Replace(@"""", string.Empty);

                var fullReportPath = Path.Combine(report, "UpgradeReport.html");

                Console.WriteLine($"Generating the report at {fullReportPath}");

                upgrader.GenerateUpgradeHtmlReport(fullReportPath);
            }
            else
            {
                var result = upgrader.PerformUpgrade();

                // Display the result
                if (result.Successful)
                {
                    Console.ForegroundColor = ConsoleColor.Green;
                    Console.WriteLine("Success!");
                }
                else
                {
                    Console.ForegroundColor = ConsoleColor.Red;
                    Console.WriteLine(result.Error);
                    Console.WriteLine("Failed!");
                }
            }
        }
    }
}

GitHub Actions Configuration

We have a couple of different workflows. One runs on Pull Request to generate the HTML Report and another on merge to run the actual database scripts against the target Azure SQL instance.

First we have this to ensure it only runs on pull requests for changes within the db-deploy directory:

name: Create DB Delta Report
on:
  pull_request:
    branches:
      - develop
    paths:
      - 'db-deploy/**'

Next we checkout the code and lint using super-linter :

jobs:
  db-delta-report:
    name: db-delta-report
    runs-on: ubuntu-latest

    steps:

      - name: Checkout
        uses: actions/checkout@master

      - name: Lint Code Base
        uses: github/super-linter@master
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          VALIDATE_ALL_CODEBASE: true
          VALIDATE_MD: true
          VALIDATE_CSHARP: true
          VALIDATE_SQL: true

Next we setup .NET core and build the project:

      - name: Setup .NET Core
        uses: actions/setup-dotnet@main
        with:
          dotnet-version: '5.0.x'

      - name: Cache Packages
        uses: actions/cache@v2
        with:
          path: ~/.nuget/packages
          key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
          restore-keys: |
            ${{ runner.os }}-nuget

      - name: Restore dependencies 
        working-directory: db-deploy/lease_extract
        run: dotnet restore

      - name: Build Console App
        working-directory: db-deploy/lease_extract
        run: dotnet publish --no-restore --output DbUpLeaseExtract

This next step calls a PowerShell script that runs the console app. We utilise encrypted secrets to pass in the database connection string:

      - name: Create DB Delta Report
        env: 
          LEASE_EXTRACT_DB_CONNECTION_STRING_DEV: ${{ secrets.LEASE_EXTRACT_DB_CONNECTION_STRING_DEV }}
        run: ./db-deploy/scripts/db-delta-report-dev.ps1
        shell: pwsh

This is the PowerShell script it is calling:

$packagePath = "db-deploy/lease_extract/DbUpLeaseExtract"
$connectionString = $Env:LEASE_EXTRACT_DB_CONNECTION_STRING_DEV
$reportPath = "db-deploy/lease_extract/DbUpLeaseExtract"
$dllToRun = "$packagePath/DbUpLeaseExtract.dll"
$generatedReport = "$reportPath/UpgradeReport.html"

if ((test-path $reportPath) -eq $false){
    New-Item $reportPath -ItemType "directory"
}

dotnet $dllToRun --ConnectionString="$connectionString" --PreviewReportPath="$reportPath"

Currently the GitHub API has no way of attaching a file to a PR comments, so as a workaround I have decided to upload the HTML report to Azure Blob storage and link to it in the PR comment:

      - name: Upload DB Delta Report to Azure Blob
        uses: azure/powershell@v1
        with:
          inlineScript: |
            az storage blob upload --account-name storageaccountname --container-name '$web' --file "db-deploy/lease_extract/DbUpLeaseExtract/UpgradeReport.html" --name UpgradeReport.html
          azPSVersion: "latest"

      - name: Comment on PR
        uses: unsplash/comment-on-pr@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          msg: "Please review the [DB Delta Report](https://storageaccountname.z33.web.core.windows.net/)"

Once this has been reviewed by our DBA's and the pull request is merged. A different workflow is triggered:

name: DB Upgrade
on:
  push:
    branches:
      - develop
    paths:
      - 'db-deploy/**'

Instead of running the HTML report, its runs an upgrade on the database by calling a different script:

      - name: Deploy DB Upgrade
        env: 
          LEASE_EXTRACT_DB_CONNECTION_STRING_DEV: ${{ secrets.LEASE_EXTRACT_DB_CONNECTION_STRING_DEV }}
        run: ./db-deploy/scripts/db-upgrade-dev.ps1
        shell: pwsh

The only thing different about this script is that the PreviewReportPath switch is missing:

$packagePath = "db-deploy/lease_extract/DbUpLeaseExtract"
$connectionString = $Env:LEASE_EXTRACT_DB_CONNECTION_STRING_DEV
$reportPath = "db-deploy/lease_extract/DbUpLeaseExtract"
$dllToRun = "$packagePath/DbUpLeaseExtract.dll"
$generatedReport = "$reportPath/UpgradeReport.html"

if ((test-path $reportPath) -eq $false){
    New-Item $reportPath -ItemType "directory"
}

dotnet $dllToRun --ConnectionString="$connectionString"

As a final step, we track all of our deployments in Code Climate Velocity - If you aren't using it yet, I highly recommend you check it out:

      - name: Send Deployment to Code Climate
        run: curl -d "token=${{ secrets.VELOCITY_DEPLOYMENT_TOKEN }}" -d "revision=${GITHUB_SHA}" -d "repository_url=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" -d "branch=develop" -d "environment=db-dev" -d "version=${GITHUB_RUN_NUMBER}" https://velocity.codeclimate.com/deploys

This same convention would be ran for dev, QA & prod etc with branches aligned to each environment.

Summary

DbUp has really helped FirstPort create a robust deployment pipeline for databases. Now DBA's (and others) can review changes via GitHub Actions before they are deployed. Having the ability to review the changes should help build trust in the process and help speed up the adoption.

In this post I demonstrated one technique to achieving automated database deployments using GitHub Actions. There are plenty of other solutions, and if you are using Entity Framework or similar these tools have migration support built in, but the core approach will be the same.

I hope I could help you learn something new today, and share how we do things here at FirstPort.

Any questions, get in touch on Twitter

// Detect dark theme var iframe = document.getElementById('tweet-1190197872404377600-86'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1190197872404377600&theme=dark" }