Baseline C# Objects to Populate Jira DevInfo Pt. 1

Jira has this great “Development Information” (DevInfo) that can be associated with your work items. Which has an API described here. The information provided in the development tabs are for Branches, Commits, Pull Requests, Builds, Deployments and Feature Flags. Which is a way to have visibility into all the development/code activity that is related to a particular work item. It’s a great way to connect everything together.

It really is great, but there are some pieces of the puzzle that can be improved. For example:

• Currently, github also associates code commits, pull requests, and build/action information into an issues history. But, github’s layout intermingles those changes within the history of an issue to create a timeline. This allows for a reviewer of an issue, to visually see when a change was made, what the context was surrounding that change. Maybe there was a compelling argument made by a team member half way through an issue being worked on. And, that argument resulted in 5 files changing; you can see that in the github history.
  
  But, Jira’s history won’t show you that because the conversation history (Jira Comments) do not intermingle the code commits, pull requests, builds or deployments to create a timeline history.
  
  That would be a really nice improvement. And, on a personal note, if would make reviewing my coworkers work items a lot easier.
  
• The Commits display (screenshot above) has a weird little bug in it. The Files Count Column (right side) should be able to display a count of all the files within a commit. The File Details Display, the list of files associated with a commit (“MODIFIED  PullRequest/Send-AzDPRStatusUpdates.ps1/” in the screenshot), will only show the first 10 files from the commit. But the File Count Column isn’t showing the total count of files, it only showing the count of files in the File Details Display that number (“1 file” in the screenshot). This seems to be a bug, but I haven’t reported it yet.
  
  (PS. Why is there a ‘/’ on the end of “PullRequest/Send-AzDPRStatusUpdates.ps1/”? The information submitted to the API did not have a slash on the end.)
  
• The Documentation is REALLY CONFUSING when it comes urls. All of the examples in the documentation present url structures that look like this:
  
  https://your-domain.atlassian.net/rest/devinfo/0.10/bulk
  
  Except, that’s not the right url!!
  
  All the APIs have an “Authorization” section in their documentation, which has a link to Integrate JSW Cloud with On-Premise Tools. And BURIED in that documentation is this quick note:
  
  The root URL for OAuth 2.0 operations is: https://api.atlassian.com/jira/<entity type>/0.1/cloud/<cloud ID>/

Note that this URL is different to the URLs used in the documentation. However, you easily translate from one to the other. For example, POST /rest/builds/0.1/bulk translates to POST https://api.atlassian.com/jira/builds/0.1/cloud/<cloud ID>/bulk.

And I agree that it’s easy to translate. But, you have to first know that you need to translate it. Maybe, an alternative direction to take is to update the OAuth 2.0 APIs documentation to use the correct urls? Or, explicitly state it on all the API documentation, so that you don’t have to find it in a separate page?


Atlassian/Jira does provide this really great C# SDK for working/reading Jira issues. But, the SDK doesn’t contain any objects/code to work with the “DevInfo”. So, I want to post a couple baseline objects which can be used in an aspnetcore/netstandard application to push information to the DevInfo endpoint in Atlassian/Jira Cloud …

But, before doing that, this post will be of a few baseline objects to authenticate with the Atlassian/Jira OAuth 2.0 endpoint.

The next post will contain objects to use with the “DevInfo” API.

Powershell for working with AzureDevOps Web Hooks

Recently, I was working with the AzureDevOps Web Hooks infrastructure and I really enjoyed the tooling that they had provided. In particular, I liked the interface they provide which shows:

• The number of successful and failed requests sent to a web hook/service,
• The history of those requests,
• And the details of what was actually sent and received (the payloads)

This visibility provided by the tooling was tremendously helpful in developing, debugging and monitoring.

There’s also a fair amount of documentation put together by the AzureDevOps team to make using these services easier.

• Integrate with service hooks
• Create a service hooks subscription programmatically
• Web Hooks
• .NET Client Libraries for Azure DevOps and TFS
• Azure DevOps Services REST API Reference

However, I have two gripes about the documentation.

• It took me a while to find the documentation because I didn’t know the exact search terms to look for. A generalized search for “azuredevops api .net client” will land you in the “Integrate Application” area of the documentation, rather than the desired “Service hooks” area.
• When it got down to the details of which libraries to use and how to use them, the documentation became a bit thin. For example, the AzureDevOps website has a really cool piece of functionality where they hide the “git” event types when the project has no git repositories within it. So, I was thinking about “querying the possible input values” on a particular project to see if the response limited the values similarly. To do that, I originally looked in the .NET API browser for a ServiceHooks*HttpClient object. But, that doesn’t exist. So, I looked at the Publishers – Query Input Values api from the REST documentation. And, the first property I should put in the request body is “currentValues”, which is of type object (what are the details on that?), and has no description given. If I’m trying to query for the current values, what should I put in for “currentValues” and in what format? It becomes apparent that the request and response are using the same object, and that property is only used in the response. So you can ignore that property on the request. But, why doesn’t the documentation state that?

Enough with my tribulations, here’s the results:

• These are a set of functions for working with Web Hooks (even though it’s misnamed as ServiceHook).
• These Web Hooks are created for the very specific needs that I wanted. Which were to create Web Hook integrations with a webservice I built for analyzing code commits, pull requests, and builds.
• The powershell is a wrapper aroound the .NET Client library (nuget) Microsoft.VisualStudio.Service.ServiceHooks.WebApi version 15.131.1, which isn’t the latest version. Since it’s not the latest version of the library, that difference might account for the documentation on the .NET Client libraries not lining up with it. For example, the ServiceHooksPublisherHttpClient does not exist in the .NET API browser.

Record Request Body in ASP.NET Core 3.0

Application Insights is a great tool, but it doesn’t record the body of a request by default. This is for good reason, payloads can be large and can sometimes contain sensitive information. But … sometimes you just need to record them.

When you do a google search there’s a great StackOverflow post (View POST request body in Application Insights) which gives you a lot of hope that it can be setup easily. But, with all the advancements in ASP.NET Core 3.0, it’s not quiet as easy as that post makes it look.

Here’s the obstacles you may need to overcome:

• In ASP.NET Core 3.0, the request’s Body is no longer available to be read after a particular point in the application pipeline. You will need to create a middleware component to “EnableBuffering”. (This was done for purposes of speed as the underlying layers of the stack were replaced with Span’s. There’s a new Request.BodyReader that works with the spans for high performance, but it’s also not available to be read after a particular point in the application pipeline.)
  
• The ITelemetryInitializer runs after a request completes. This means that the request’s body is disposed of by the time the initializer runs and records the event. You will have to record the body somewhere after “EnableBuffering” is enabled and before the Action completes. Like inside of an IActionFilter.
  
• You may not want to record the body of everything that flows through your website, so an ActionFilterAttribute can make it easy to select which action you would like to record.

So, here’s some code that can help accomplish that:

What’s an Andon Cord?

I’ve seen a couple of great explanations of an Andon Cord, but I feel like there’s another side to them. Something that hasn’t already been written about in John Willis’ The Andon Cord, Six Sigma Daily’s The Andon Cord: A Way to Stop Work While Boosting Productivity, or even Amazon’s Andon Cord for their distributed supply chain (example 1, 2).

Personally, I’ve heard two descriptions of the Andon Cord and one of them makes a lot of sense to me, and the other one is the popular definition. The popular definition is that an Andon Cord is the capability to pause/halt any manufacturing line in order to ensure quality control and understanding. Anyone can pull the Andon Cord and review a product that they are unsure about. Which intuitively makes sense.

The second definition I heard was from Mike Rother’s book, Toyota Kata, and wasn’t so much of a definition as a small glimpse into the history the Andon Cord. The concept that we know today started at Toyota before they made cars. This was back when they were making sewing machines. And, you need to imagine that the sewing machine manufacturing line was modeled off of Henry Ford’s Model T production lines. So there was a belt that ran across the factory floor and in between stations that people worked at. The Sewing Machines would be mounted to the line and would move from one station to the next on a timed interval (lets say every 5 minutes). So, each person would be working at their station and they would have 5 minutes to complete the work of their station; which was usually installing a part and then some sort of testing. If the person on the line felt that they couldn’t complete their work on time, then they should pull the Andon Cord to freeze the line. This ensured that no defective part/installation continued on down the factory line. The underlying purpose of not having a bad part go down the line is that disassembling and reassembling a machine to replace a defective part is very expensive compared to stopping the line and fixing it while the machine is at the proper assembly level. This makes complete sense to me.

The second definition makes a lot more sense to me than the first because of one unspoken thing:

Anyone on the assembly line can pull the Andon Cord. The Andon Cord can be pulled by anyone, but it’s supposed to be for the people who are actually on the assembly and have expert knowledge about their step within the overall process. It’s their experience and knowledge on that particular product line which makes them the correct person to pull the cord. It’s not for people from other product lines to come over and pull their lines cord.

This is a classic problem that I’ve run into time and again. On multiple occassions, I have seen the Ops and Management side of businesses hear that “anyone can pull the Andon Cord” and immediately start contemplating how they can use the cord to add Review Periods into process lines and allow anyone to put the brakes on a production deployment if anyone doesn’t understand it.

But those ideas seems counter-productive to the overall goals of DevOps. You don’t want to add a Review Period as that just delays the business value from getting to the end customer. And you don’t want to stop a release because someone who isn’t an expert on a product has a question about it; you want that person to go ask the experts, and then you want the experts on a Product Line to pull the Andon Cord.

Now, in an idealized world, all the people involved in a products deployment process would all be on the same Product Team. That team would be made up of Dev, Ops, and other team members. And all of those team members would be experts on the product line and would be the right people to pull the cord.

However, the majority of businesses I’ve talked with have separate Devs and Ops/Engineering teams. Simply because that structure has been lauded as a very cost effective way to reduce the companies expenditure on Ops and allow for their knowledge to be centralized and therefore non-redundant. But, when the Ops team is separate from the Dev team then the Ops team has a sense that they are a part of every product line; and they should have ownership over allowing any release to go to production. Even when they are not experts on the product line and have no knowledge of what a change actually does.

This sense of ownership that Ops (and to some degree Management) have often manifest in the form of asking for a review period between the time a deployment has passed all of it’s testing requirements and it actually goes out to production. This review period should start with a notification to the customers and usually end a few hours/or a day later so that Operations, Management, and Customers all have time to review the change and pull the cord if they have concerns about the change. Except, the Customer and the Product Team are the only ones on that line who are really experts on the product. And for customers that work alongside their product teams, they usually know what’s coming long before scheduling; and customers that don’t work alongside their product teams usually won’t be involved at all at this point.

So, if the above is true, then Operations (and Management) wouldn’t be experts on the product line at this point in the release process, so why would they be pulling the cord at this point?

For Management, I’m not sure. But, for Operations, they are experts on the Production environment that the deployment will be going into. Ops should be aware if there are any current issues in the production environment and be able to stop a deployment from making a bad situation worse. But, that isn’t a product line Andon Cord. That’s an Andon Cord for an entire environment (or a subsection of an environment). The Operations team should have an Andon Cord to pause/halt all deployments from going into Production if something is wrong with that environment. Once the environment has been restored to a sense of stability, then Operations should be able to release the cord and let the queued deployments roll out again. (sidenote: Many companies that are doing DevOps have communication channels setup where everyone should be aware of a Production environment problem; this should allow for “anyone” to pull the Environment Andon Cord and pause deployments for a little while.)

Finally, in the popular definition of the Andon Cord there is a lot of attention paid to human beings pulling the Andon Cord, but not a lot of explicit statements about machines pulling the Andon Cord. For me, I see it as both groups can pull the Andon Cord. It seems like everyone intuitively understands that if unit tests, or smoke tests, or a security scan fails then the process should stop and the product should go back to the developer to fix it. What I don’t think people connect is that that’s an Andon Cord pull. It’s an automated pull to stop the process and send the product back to the station that can fix the problem with the least amount of rework required. To see that though, you have to first recognize that a CI/CD automated build and deployment process is the digital transformation of a factory floors product line. Your product moves from station to station through human beings and automated tooling alike (manual commit, CI build, CI unit tests, manual code review, manual PR approval, CI merge, CI packaging, CD etc.), and at every station there is a possibility of an Andon Cord pull.

AzureDevOps PR Policies with Powershell

After tinkering with AzureDevOps Pull Request Statuses, I started thinking about automating the creation of the policies. The build policies need to be setup on an individual repository basis because it requires a build definition to be associated with it. Some policies could be moved to the Project level (like the Minimum Number of Reviewers or Merge Strategy policies). But, I’m not sure if you can override a Project level policy in an individual branch.

So, I went searching to see if anyone had already done it and Jesse Houwing had: Configuring standard policies for all repositories in Azure Repos. I really liked his approach to exploring the API and using the json created by AzureDevOps to help construct his solution. I also was really interested by the idea of using the Azure CLI to perform the updates.

However, I was still pretty enamored with how easy the .NET SDK libraries were to use and thought I could continue to use them with Powershell to perform similar updates. So, here’s some sample code which can create a simple policy like: At least one reviewer is required on a Pull Request and that reviewer can be the requestor.