Developing applications that require secure storage of sensitive data is difficult but it’s the perfect use-case for Azure Key Vault. From API keys to entire certificates you can protect your sensitive data from being breached by opting for a battle-tested security product, but it can be a bit of a nightmare to develop an application for locally.

In a dev environment, currently, you need to have a real Azure Key Vault resource deployed and potentially being paid for in an active Azure subscription. If you’re like me and work for a fairly large company then the security policies around accessing these resources can be tough to navigate, meaning long delays during onboarding and potentially longer delays caused by multiple developers overwriting each other’s secure values.

Microsoft have put significant effort into making the cloud development experience easier with .NET and have released emulators for products that face the same issue. The Azure Service Bus now has an official Emulator to solve that problem for example, sadly Azure Key Vault does not have a similar alternative.

Or should I say… did not.

Dramatic pause.

The first stable release of the Azure Key Vault Emulator has shipped and is now available for public consumption. Here’s a quick rundown of what’s available:

• Full support for the Azure SDK Key Vault Clients, meaning you can use the official SecretClient, KeyClient and CertificateClient when using the Emulator and simply switch the VaultURI in production.
• Native .NET Aspire support for both the hosting and client application. Using the Emulator prevents any provisioning of a real Azure Key Vault and doesn’t require any configuration to use, it Just Works™. Using .NET Aspire is not a requirement for the Emulator.
• Session or persistent storage of secure data, meaning you can destroy all secure values when your application is finished running or keep them around if you don’t want to run any initialisation code.
• No new dependencies because the Emulator is hosted externally to your main application (unless you use the handy Client library, more below).

If you use, and like, the Emulator please make sure to ⭐ the repository. This engagement (amongst other criteria) is used to validate project applications for .NET Foundation membership which will guarantee long term support for the project. Thank you!

Getting started With the Emulator

The first run of the Emulator will prompt you to install a localhost SSL certificate - this is unique to your machine and is required for the Azure SDK to work correctly, click here if you want to learn more or provide your own certificates.

The Emulator runs as a container on your local machine and can be accessed by setting your VaultUri to https://localhost:4997.

If you’re using .NET Aspire there’s now built-in support for the emulator, meaning you can optionally override your IResourceBuilder<AzureKeyVaultResource> to use the emulator.

First install the AzureKeyVaultEmulator.Aspire.Hosting package (.NET 8 or 9 only):

dotnet add package AzureKeyVaultEmulator.Aspire.Hosting

Then add to or update your AppHost to run the Emulator:

var keyVaultResourceName = "keyvault";

// With existing resource
var keyVault = builder
    .AddAzureKeyVault(keyVaultResourceName)
    .RunAsEmulator(); // Add this line

// Or directly add the emulator as a resource, no configuration required
var keyVault = builder.AddAzureKeyVaultEmulator(keyVaultResourceName);

var webApi = builder
    .AddProject<Projects.MyApi>("api")
    .WithReference(keyVault); // reference as normal

This will inject the environment variable ConnectionStrings__keyvault, where keyvault is whatever value you assigned to keyVaultResourceName above.

When using .RunAsEmulator() the resource will no longer attempt to provision in your Azure subscription; the Aspire team specifically made this change to support the Azure Key Vault Emulator which blew my mind.

One of the limitations of the Emulator is that it doesn’t pass the ChallengeBasedAuthenticationPolicy within the Azure SDK without changing your hosts file, this is due to the URL of the container not meeting the schema https://{vault-name}.vault.azure.net/.

You need to disable that check like so:

var vaultUri = new Uri("https:://localhost:4997"); // or get it from your configuration, env vars etc.

var options = new SecretClientOptions
{
    DisableChallengeResourceVerification = true
};

var secretClient = new SecretClient(vaultUri, new DefaultAzureCredential(), options);

var secret = await secretClient.GetSecretAsync("myPassword");

To make this even easier the AzureKeyVaultEmulator.Client library is also available (netstandard2.0):

// Injected by Aspire using the name "keyvault".
var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;

// Basic Secrets only implementation
builder.Services.AddAzureKeyVaultEmulator(vaultUri);

You can also optionally inject a KeyClient and CertificateClient like so:

// Or configure which clients you need to use
builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, keys: true, certificates: false);

Now you can create your application as normal, using the Azure Key Vault clients you injected at runtime:

private SecretClient _secretClient;

public SecretsController(SecretClient secretClient)
{
    _secretClient = secretClient;
}

public async Task<string> GetSecretValue(string name)
{
    var secret = await _secretClient.GetSecretAsync(name);

    return secret.Value;
}

It’s highly recommended to check the execution environment at startup to prevent using the Azure Key Vault Emulator in production, for example if you’re using the Client library:

var vaultUri = builder.Configuration.GetConnectionString("keyvault") ?? string.Empty;

if(builder.Environment.IsDevelopment())
    builder.Services.AddAzureKeyVaultEmulator(vaultUri, secrets: true, certificates: true, keys: true);
else
    builder.Services.AddAzureClients(client =>
    {
        var asUri = new Uri(vaultUri);

        client.AddSecretClient(asUri);
        client.AddKeyClient(asUri);
        client.AddCertificateClient(asUri);
    });

My PR into the main Aspire.Azure.Security.Client package which adds support for the KeyClient and CertificateClient is almost through peer review and expected to be in the .NET Aspire 9.3 release - until then you’ll need to use the usual Azure SDK For .NET if you need those clients.

Final remarks

I want to thank Basis Theory for the original repository/codebase of which the Emulator then grew into its’ current form. When trying to find a suitable emulator myself I stumbled across it but was sad to see it only supported a few operations and was archived.

Prior to the stable release I got in touch with them to make sure that they were happy with the copyright retention and attribution back, but also to potentially add a redirect link from their archived repository to the now active one. They’ve been incredibly kind and communicative, so thank you to all of the team 💖.

Now, the future.

The Open Source .NET landscape has changed recently with largely adopted packages opting to move towards a commercial license for future updates, with prior releases keeping their OSS license but receiving no further support.

I fully back developers being paid for their work, and when large companies make money from their free labour it’s only fair that they get a piece of the pie too. However this makes introducing new open source dependencies into your workflow a little more risky, or at least more people are now aware of the risk.

That said, Azure Key Vault is not an ever changing product (and by proxy the Emulator); by design the functionality rarely changes to ensure that no security regressions creep in. The Emulator will continue to receive bug fixes, API updates (if available) and general maintenance work but it is stable and will not demand 1000s of hours of continued work. It will never be commercialised (I’d be sued into an early grave if I tried anyway) and with the prospect of .NET Foundation membership on the horizon my own personal bus factor decreases too.

If you make use of the Azure Key Vault Emulator please be sure to ⭐ the repository as it’s one of many metrics that the .NET Foundation uses to validate project membership applications.

Also number go up = happy ape brain.

Thanks for reading and I hope you enjoy the Emulator!

James

dotnet test --verbosity minimal

but due to the tests requiring SSL connections my tests were failing with:

   System.Net.Http.HttpRequestException : The SSL connection could not be established, see inner exception.
---- System.Security.Authentication.AuthenticationException : The remote certificate is invalid because of errors in the certificate chain: UntrustedRoot

I tried a few solutions, including asking ChatGPT who dumped out a load of completely unworking code, but the following Just Worked™:

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '9.0.x'

      - name: Install SSL Certificates
        run: |
          dotnet dev-certs https --trust

      - name: Run Integration Tests
        run: |
          dotnet test --verbosity minimal

Super simple, you just need to:

• Set up the .NET action uses: actions/setup-dotnet@v3
• Use the dev-certs CLI tool to create and trust an SSL cert: dotnet dev-certs https --trust
• Then run your tests dotnet test --verbosity minimal

One of the cool things is I can write pure markdown for these blog posts, append a language option to the triple backticks and set the highlighting:

```csharp
// Code here
```

The only issue is that the defaults look terrible:

So let’s fix that.

Other solutions

I tried a whole heap of solutions to get this working in a nice way, including but not limited to:

• Writing my own Ruby plugin to render differently
• Manually tweaking the syntax.css file I use for highlighting
• Installing bloody Rust to try and make use of kramdown Tree Sitter
• Giving up and going to bed.

None of these actually came out looking anything close to what Visual Studio shows you, which is mostly a limitation of the Rouge CSharp lexer.

I don’t, and won’t, complain about people providing solutions to problems for free in the open source world. I can’t thank people enough for doing it because the modern internet wouldn’t be the same without it.

That said, it didn’t work for me. Time to fix it.

The final solution

I relented and asked ChatGPT what I should do in this situation who presented The Chosen One™:

We’re going to be making use of Prism.js instead, which looks significantly better. In a common .html file for your blog include the following:

<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>

<!--language support-->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-csharp.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-yaml.min.js"></script>

Next find a good theme that you like here. I personally chose VS Code Dark.

Download that css and place it into a .css file inside your assets/css folder. Reference the new css file in your common file above like so:

<link rel="stylesheet" href="/assets/css/prismjs-vs.css" />

And finally, in a file exclusively used by your posts, add this to the bottom of the file before the </html> tag:

  <script>
    document.addEventListener("DOMContentLoaded", function () {
        Prism.highlightAll();
    });
  </script>

and there we go! Here’s the newly highlighted code above, but looking as close as I could possibly get it to Visual Studio:

namespace AzureKeyVaultEmulator.Shared.Constants
{
    public class AspireConstants
    {
        public const string EmulatorServiceName = "keyVaultEmulatorApi";
    }
}

namespace AzureKeyVaultEmulator.IntegrationTests.SetupHelper
{
    public static void ExampleReference()
    {
        var referencedString = AspireConstants.EmulatorServiceName;
    }
}

and another example of a method block with various keywords:

public sealed class TestingFixture : IAsyncLifetime
{
    private DistributedApplication? _app;
    private ResourceNotificationService? _notificationService;

    public async Task InitializeAsync()
    {
        var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.AzureKeyVaultEmulator_AppHost>();

        builder.Services.ConfigureHttpClientDefaults(c =>
        {
            c.AddStandardResilienceHandler();
        });

        _app = await builder.BuildAsync();

        _notificationService = _app.Services.GetService<ResourceNotificationService>();

        await _app.StartAsync();
    }

    public async Task DisposeAsync()
    {
        if (_app is not null)
            await _app.DisposeAsync().ConfigureAwait(false);
    }
}

One of my main gripes with Microsoft is their documentation. If you’re starting something from scratch you’ll naturally Google around for it, find the docs and the example code looks super simple; then you get into the nitty gritty and suddenly you’re riding solo.

I’ve decided to fork the Azure KeyVault Emulator, which has been archived as of October 2024, because the functionality is really quite desirable. Aspire has allowed us to create local cloud environments at dev-time without needing to actually host or deploy resources, nor configure RBAC access (shudders). Key Vault is one of those services that doesn’t have support in Aspire (yet?) and you need to have a real instance of it hosted on Azure. With the emulator, and my future development/extensions, this won’t be required.

I wanted to create integration tests for the API to ensure it met the acceptance criteria for public consumption - naturally I googled “.NET Aspire Integration Testing” and this was the first link I saw, from Microsoft themselves!

I use XUnit for all my testing purposes (mainly from habit) and .NET Aspire has a handy XUnit template you can just create a project from and now you have integration testing support!

Right? No. Why else would I be writing this?

Setting up correctly

We’ll be creating a new .NET Aspire XUnit Project from Visual Studio:

Next step is to add a reference to your AppHost project in your new XUnit project:

This will allow your new IntegrationTesting project to run the AppHost project, which in turn creates all the required resources, connection strings and so forth. Really bloody handy.

Shared/reference projects

One of the nuances of .NET Aspire is any projects referenced are classed as executables - meaning if you need a Model from your API to create an integration test from it cannot exist in the same project as your API.

Annoying, but not a hill worth dying on. I migrated the models out of the API project and into a Shared project, and referenced it as such:

<ProjectReference Include="..\AzureKeyVaultEmulator.Shared\AzureKeyVaultEmulator.Shared.csproj" IsAspireProjectResource="false"/>

The really key part here is the IsAspireProjectResource="false" which allows you to reference items from within that project like you would a normal project reference. For example:

namespace AzureKeyVaultEmulator.Shared.Constants
{
    public class AspireConstants
    {
        public const string EmulatorServiceName = "keyVaultEmulatorApi";
    }
}

namespace AzureKeyVaultEmulator.IntegrationTests.SetupHelper
{
    public static void ExampleReference()
    {
        var referencedString = AspireConstants.EmulatorServiceName;
    }
}

I personally recommend encapsulating any names for applications into a const string like above because it allows for cleaner code and reusability.

…or I’m just lazy and can’t be bothered to update 3 strings when I make a change.

Create your testing environment

Now you’re finally ready to create your testing environment! Let’s get cracking.

First off we’re going to need a Fixture, which encapsulates the environment for your actual test cases. This fixture will make use of the reference to your AppHost, creating an instance of it per test class, and then using its’ exposed endpoints/services to execute tests.

You don’t strictly need to do this, but you really should. If you’re writing more than a single integration test then you’ll save a load of time writing/copying the same code per test case, and any faults that crop up can be fixed in a single area.

Again, reusability! It’s important - and this is why the MS documentation kind of sucks sometimes.

Create a basic, minimal Fixture inside of your IntegrationTesting project (ideally in a suitably named folder):

public sealed class TestingFixture : IAsyncLifetime
{
    private DistributedApplication? _app;
    private ResourceNotificationService? _notificationService;

    public async Task InitializeAsync()
    {
        var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.AzureKeyVaultEmulator_AppHost>();

        builder.Services.ConfigureHttpClientDefaults(c =>
        {
            c.AddStandardResilienceHandler();
        });

        _app = await builder.BuildAsync();

        _notificationService = _app.Services.GetService<ResourceNotificationService>();

        await _app.StartAsync();
    }

    public async Task DisposeAsync()
    {
        if (_app is not null)
            await _app.DisposeAsync().ConfigureAwait(false);
    }
}

Let’s go over the important bits here:

• InitialiseAsync() creates our DistrubutedApplication - ie the AppHost. We want to keep a higher scoped reference to that for the future: _app.
• ResourceNotificationService allows us to WaitAsync() for resources that .NET Aspire is creating before trying to use them; essentially the testing version of WaitFor(xxx).
• DisposeAsync() cleans up the DistributedApplication on a per-class basis. Without this you will have lingering resources/ports should your tests throw an Exception and bottom out.

We’re trying to test an API, so we need a HttpClient which points to our localhost:XXXX resource.

Unless we hardcode the port we need to look this up. The Microsoft docs tell you to create these on a per-test basis, gah, which is not ideal.

Let’s create, and expose, a HttpClient from our Fixture by extending its’ functionality:

private HttpClient? _testingClient; // Placed below _notificationService

public async Task<HttpClient> CreateHttpClient(string applicationName = AspireConstants.EmulatorServiceName)
{
    if (_testingClient is not null)
        return _testingClient;

    _testingClient = _app!.CreateHttpClient(applicationName);

    await _notificationService!.WaitForResourceAsync(applicationName, KnownResourceStates.Running).WaitAsync(TimeSpan.FromSeconds(30));

    return _testingClient;
}

We’re now using the CreateHttpClient("MyApiProject") method which under the hood uses IHttpClientFactory as you can see here. No need to worry about hardcoding the IP and Port for your application, delegate the work to .NET Aspire.

Next we’re making use of our ResourceNotificationService to wait for the API to be alive. This is near-instant once the AppHost has launched but extremely useful if you have a slow start-up (such as waiting for a database server).

We’re also making use of your AspireConstants.EmulatorServiceName here to keep our code clean too! I will keep beating the reusability drum.

Create your integration test(s)

Okay, finally, we can start writing tests in a way that is easy to maintain.

First off create a new TestClass for a particular Controller, Endpoint, whatever you want to test:

public class GetSecretTests(TestingFixture fixture) : IClassFixture<TestingFixture>
{

}

The IClassFixture<TestingFixture> tells our class that we’re a testing class specifically, and exposes the TestingFixture to it.

We’re using the new Primary Constructor syntax - which my eyes/brain still haven’t gotten used to.

Now let’s add a test and call into our API:

[Fact]
public async Task GetSecretsBlocksRequestWithoutBearerTokenTest()
{
    var client = await fixture.CreateHttpClient();

    var response = await client.GetAsync("secrets/willfail");

    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
}

As you can see the TestingFixture allows us to create a bog-standard HttpClient which we can use to interact with our API - which has been hosted by .NET Aspire.

Remember the point I made about migrating API models to a Shared project earlier? If you need to go further into validating the response, ie checking a field has been set correctly, you can do so like you would consuming a 3rd party API:

[Fact]
public async Task GetSecretsReturnsBackCorrectValueTest()
{
    var client = await fixture.CreateHttpClient();

    var response = await client.GetAsync("secrets/myPassword");

    var secret = await response.Content.ReadFromJsonAsync<SecretResponse>();

    Assert.NotEqual(string.Empty, secret?.Value);
}

And that’s it! Now you have a fully reusable Fixture and a set up integration testing environment for your API, along with all resources required by your platform to operate.

Final notes

If you’re using a versioned API and don’t want to repeat yourself endlessly (reusabili- okay I’ll stop) you can modify the CreateHttpClient method in your Fixture to do that for you. I’m using the following:

<PackageReference Include="Asp.Versioning.Http" Version="8.1.0" />
<PackageReference Include="Asp.Versioning.Http.Client" Version="8.1.0" />

And implementing them like so:

private HttpClient? _testingClient;

public async Task<HttpClient> CreateHttpClient(double version, string applicationName = AspireConstants.EmulatorServiceName)
{
    if (_testingClient is not null)
        return _testingClient;

    var opt = new ApiVersionHandler(new QueryStringApiVersionWriter(), new ApiVersion(version))
    {
        InnerHandler = new HttpClientHandler() // Make sure you add this!
    };

    var endpoint = _app!.GetEndpoint(applicationName);

    _testingClient = new HttpClient(opt)
    {
        BaseAddress = endpoint
    };

    await _notificationService!.WaitForResourceAsync(applicationName, KnownResourceStates.Running).WaitAsync(TimeSpan.FromSeconds(30));

    return _testingClient;
}

And then configure your tests to alter the API version like so:

[Theory]
[InlineData(1.0)]
[InlineData(1.1)]
public async Task GetSecretsReturnsBackCorrectValueTest(double version)
{
    var client = await fixture.CreateHttpClient(version); // Included here!

    var response = await client.GetAsync("secrets/myPassword");

    var secret = await response.Content.ReadFromJsonAsync<SecretResponse>();

    Assert.NotEqual(string.Empty, secret?.Value);
}

This implementation will append api-version={version} to the end ouf our request, where version is provided by [InlineData].

You can alter where that version goes, I was going to link the documentation as a tongue-in-cheek joke but in classic Microsoft fashion this happened:

Honestly couldn’t make it up.

Thanks for reading!

A few days prior, when I set this blog up, I wanted to shortcut a lot of the legwork with setting up a proper CI/CD pipeline to build and release out to an Azure Static Web App.

If you’re a fan of horror stories feel free to read my initial attempt here.

Some future requirements have come up which meant that I not only needed a proper build pipeline, but also a fast one.

For those unaware, Azure Devops has a free tier which includes 1800 minutes of build time per month, refreshing on the 1st of the month.

I’ve now built a true, fairly fast CI/CD pipeline to build and release this blog out and I’d like to share my findings with you, dear reader.

In case you just want the YAML and nothing else, here it is:

trigger:
- master

pool:
  vmImage: 'ubuntu-latest'

schedules:
- cron: "5 0 * * *"
  displayName: Daily release for scheduled posts
  branches:
    include: 
     - master
  always: true 

steps:
- task: UseRubyVersion@0
  inputs:
    versionSpec: '>= 2.5'

- script: |
    gem install jekyll bundler --no-rdoc
    bundle install --retry=3 --jobs=4
  displayName: 'bundle install'

- task: CmdLine@2
  inputs:
    script: bundle exec jekyll build
    displayName: 'Jekyll Build'
    
- task: AzureStaticWebApp@0
  inputs:
      app_location: '/_site'
      api_location: 'api'
      output_location: '/_site'
      azure_static_web_apps_api_token: $(deployment_token)

Let’s break it down

Let’s jump into the nitty-gritty of what this build config is doing, and why.

schedules:
- cron: "5 0 * * *"
  displayName: Daily release for scheduled posts
  branches:
    include: 
     - master
  always: true 

This is an optional include that will build the blog on a schedule, with the cron being every day at 00:05am. This is so I can schedule posts into the all_collections/_posts directory and have them release on the date of the post.

If you don’t want to schedule a build and simply want to trigger the release when you publish a new post, delete this section.

steps:
- task: UseRubyVersion@0
  inputs:
    versionSpec: '>= 2.5'

- script: |
    gem install jekyll bundler --no-rdoc
    bundle install --retry=3 --jobs=4
  displayName: 'bundle install'

This is a 2 step part which has been the majority of the time sink I’ve experienced.

First we’re specifying which version of Ruby to use, as Jekyll advises against using spec 3.0 or higher in their quickstart guide.

Next we’re pipelining two scripts to set the stage for our blog:

• gem install jekyll bundler --no-rdoc which will allow the actual build script used by Jekyll to run correctly.
• bundle install --retry=3 --jobs=4 which will then install our dependencies etc, ready for compiling the blog markdown into HTML.

Let’s take a deeper look into each.

Lightening fast?

gem install jekyll bundler --no-rdoc comprises of two parts, the command to run and the parameters.

The initital command gem install jekyll bundler typically takes around 2m30s to run on the Azure Free tier. Part of this, for whatever reason, is building documentation for the script which we, as “set-and-forget” pipeline runners, don’t care about. That’s where --no-rdoc comes in.

With this addition we skip the step where the documentation is created. This shaved around 30s off the total build time, saving our precious free minutes!

bundle install --retry=3 --jobs=4 is an important part of the process as building the Jekyll site requires the bundle to be installed. Some caching can be done here to mitigate further time, but I haven’t gotten to that yet.

The --job=4 is the key part here. Without it, we run the process on a single core. By specifying 4 we’re able to run our command on 4 cores, shaving off a bunch of time. I didn’t really notice this before, but I took it out for a trial run and it added an extra couple of minutes to the build time.

The boring stuff

- task: CmdLine@2
  inputs:
    script: bundle exec jekyll build
    displayName: 'Jekyll Build'

Now that we’ve gotten our ducks firmly in a row it’s time to build out xxx.md files into actual HTML. This is a simple command-line script which runs bundle exec jekyll build. Only takes about 1s, no point trying to optimise it.

- task: AzureStaticWebApp@0
  inputs:
      app_location: '/_site'
      api_location: 'api'
      output_location: '/_site'
      azure_static_web_apps_api_token: $(deployment_token)

At this point we’ve done all the required steps and we’re ready to publish out to our Azure Static Web App. We have a pipeline variable set called deployment_token which you can grab from the configuration blade of your Static Web App (detailed explanation on the previous post linked above).

This step takes the ready _site directory and publishes it out.

Aaaaand breathe.

Cool, we’re all set. It’s running, total time is typically just over 3 minutes which means we can run a whole bunch of these each day at 00:05 without stressing.

When deciding to build a blog there were a few options:

• A custom domain name. Medium gets on my nerves and I wouldn’t want to inflict that on somebody else.
• Easy mechanism to design and publish posts, markdown being the optimal choice.
• A theme that was minimalistic but flexible.

Initially I settled on Hashnode which allowed easy setup, 1-click themes and a free custom domain name alias.

After setting it up it was swiftly apparent how bloated the platform was. I just wanted somewhere to write up interesting topics, not participate in some global developer community where we all pass-the-upvote and #followback.

With limited knowledge in the space I stumbled across Jekyll, an open source markdown-driven platform which generates static HTML from markdown files with an associated theme. Perfect!

I got my site set up locally, got the theme installed (took some time) and got the build working so that updates I published would actually generate into the HTML.

Next step: deployment.

I’m no guru with CI/CD. I can pick apart pre-assembled YAML files and make them work, or follow a wizard to generate the tasks behind the scenes. If there’s a bug, I bin the lot off and start again. I just needed to find a way to build and publish the site to some web server every time I pushed a new post to the repository the blog sat on. Should be easy enough.

Pragmatism

I settled on an Azure Static Web App. It offers a generous free tier with an automatic SSL certificate, free domain mapping and I could easily deploy my static content manually via Kudu. I wanted to automate this step because I’m a lazy bugger, so I gave it a shot.

Frankly I won’t waste your time at this stage with waffling on about my attempts to get various ruby scripts running, with artifacts being shoved around etc. There are guides out there if you’re interested - I couldn’t make heads nor tails of them.

Here’s what I knew worked:

• Locally the blog compiled and looked fine once running with bundle exec jeykll serve.
• The _site directory compiled fully, taking new additions to the all_collections/_posts directory and building them into a HTML file.

Now, cue the super scuffed approach to deploying this blog.

Rules are meant to be completely deleted from the file

For this pragmatic guide we need to commit our first crime: remove the exclusion of _site from the .gitignore. How dreadful!

Forgive me Microsoft for I have sinned.

Here’s the dreadful YAML file to use for publishing a single post. It’s not pretty, but it works. All in the name of getting it working without too much glitter:

trigger:
  - master

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: '/_site'
      api_location: 'api'
      output_location: '/_site'
      azure_static_web_apps_api_token: $(deployment_token)

At the root of your Jeykll blog add a new file called azure-pipeline.yml and add the above as the contents.

Don’t worry about the api_location: 'api' section - it does nothing and frankly I’m scared to touch it.

Azure Devops - I’m sorry.

As a heads up I had this blog under an old alias and let the domain expire (like a fool). I’ve migrated it to this domain, so the names look a little off!

First, create the Azure Static Web App. Once it’s deployed, you should land on the dashboard for the resource:

Here you can set up your custom domain if you like - the verification for the TXT DNS addition took 3 (!) days to fully detect in the portal. We’ll skip this step for now.

Whilst on Overview, find the Manage Deployment Token button on the right hand side.

Click the button (of course), copy the token or keep the blade open for the next step.

Go to your DevOps organisation -> Project containing the blog repository -> Pipelines.

You won’t have the “Blog” pipeline there, don’t worry!

Click on new pipeline to begin sinning like me

Select the Azure Repos Git option, assuming that’s where your blog repository is stored.

Select your repository

Now that you’ve saved our sinful pipeline .yml file, select Existing Azure Pipelines YAML file

Select the azure-pipelines.yml file from the root directory. For whatever reason Jekyll builds a copy to the _site directory, be sure not to use that one. Click Continue once you’re done.

Our great functional pipeline text will load in

Now’s the time to link the pipeline to our new, shiny Azure Static Web App. Click Variables in the top right

Click New Variable

If you take a look at the bottom of our azure-pipelines file, we have a $variable called deployment_token. That’s the name of our variable. Make sure to add the token from our Static Web App blade from earlier to the value field:

You can mark it as secret if you like, I haven’t because my partner can’t even find the monitor power button let alone understand Azure Pipelines.

You should see your new variable appear in the list, click save.

Now save your pipeline by using the arrow on the Run button to show the hidden, very useful option

Awesome, your pipeline is set up. Now every time you push to master, the _site directory will deploy to your Azure Static Web App. Please clap

Building and publishing your site

Now for the fun, extra scuffed section.

Every time a new blog post gets added, we need to build the blog. This converts the .md files containing our very important ramblings into readable HTML files. How exciting!

Now I’m lazy, if you couldn’t already tell. I can’t be bothered to write nice commits for things people will never see, so I wrote a horrendous functional script to speed this part up too.

bundle exec jekyll build | git add . | git commit -m "new post" | git pull | git push

Here we’re doing a few bits:

• bundle exec jekyll build builds the .md files into .html files for the posts.
• Add all the new files to our repoitory.
• Commit them with a very descriptive commit message.
• Pull the latest changes in case we did a drunk ramble directly into DevOps (don’t judge me)
• Push the changes locally.

I threw that crap into a .ps1 PowerShell script and added it to the root of my blog.

Now, with the combined strength of our scuffed pipeline and horrendous git practices that my professors are definitely weeping at, we can write a new blog post and publish it with just a script. How far technology has come.

After thoughts

I’m aware this is an awful way of ignoring learning proper CI/CD practices. I’ll live with myself. It works, nobody else is writing to this mess of a blog and I frankly don’t care about best practices for a micro-project.

Enjoy!