Background

Our environment consisted of a load balancer distributing traffic to several Windows servers hosting IIS. These servers (EC2 instances) were spun up via CloudFormation, each automatically registering a GitHub self-hosted runner. In essence, every server became a target for GitHub Actions workflows.

To deploy across the entire group of servers with the same tag (for example, all IIS-Server machines), we needed the workflow to run on each of them, not just on a single available runner. While setting runs-on: [self-hosted, <label>] directs GitHub Actions to run the job on a runner matching that label, it does not instruct it to execute on all such servers simultaneously.

As documented by GitHub, runs-on selects only one matching runner; to execute a job on multiple machines, you need to use a matrix strategy.

Hard-coding runner names would defeat our goal of dynamic scaling, since servers could be added or removed without updating the workflow.

We looked for an approach that would adapt dynamically as servers joined or left our environment. Azure DevOps offered “deployment groups”, but GitHub Actions does not include a direct equivalent. Instead, we needed to leverage the GitHub API to query our organization’s runners at runtime, filter them by environment labels, and build a dynamic matrix of targets for our workflow. This blog post describes the story of how we achieved that goal.

Gathering Runner Information

The first obstacle we encountered was obtaining an authentication token capable of listing all self-hosted runners in our organization. The default GITHUB_TOKEN provided to workflows only has repository scope, so it cannot retrieve organization-wide runner details. Our solution was to create a GitHub App with “Read access to organization self hosted runners”, then install it on our repository. By storing the App’s ID and private key as repository secrets (RUNNER_TOKEN_APP_ID and RUNNER_TOKEN_APP_PRIVATE_KEY), we could exchange these credentials for a short-lived token that the GitHub CLI (gh) could use to query the runners API.

Below is the YAML snippet for the determine-runners job. It runs on ubuntu-latest, invokes a third-party action to fetch an application token, then uses gh api and jq to filter runners with a specific environment label (e.g., staging or production) and a fixed label (e.g., IIS-Server):

jobs:
  determine-runners:
    name: Determine target runners
    runs-on: ubuntu-latest
    outputs:
      runners_json: $
    env:
      ORG_NAME: $
      TARGET_ENV_LABEL: $
      REQUIRED_LABEL_1: IIS-Server
    steps:
      - name: Get Organization API Token
        id: get_workflow_token
        uses: peter-murray/workflow-application-token-action@v4
        with:
          application_id: $
          application_private_key: $
          organization: $

      - name: Get matching runners (including offline)
        id: get_runners
        run: |
          # Retrieve all runners for the organization (up to 100 per page)
          runners_data=$(gh api "orgs/$/actions/runners?per_page=100" --jq '.runners[]')

          # Filter runners by both the fixed label and environment label
          matching_runners=$(echo "$runners_data" | jq -c \
            --arg label1 "$" \
            --arg label2 "$" \
            'select(.labels | map(.name) | (contains([$label1]) and contains([$label2])))'
          )

          # Build a JSON array of runner names
          runners_json=$(echo "$matching_runners" | jq -cs '[.[].name]')

          if [ -z "$runners_json" ] || [ "$runners_json" == "[]" ]; then
            echo "::error::No runners found with labels: '$' and '$'."
            exit 1
          else
            echo "runners_json=$runners_json" >> $GITHUB_OUTPUT
          fi
        env:
          GH_TOKEN: $

Building the Deployment Matrix

Once we had a JSON list of runner names in the output variable runners_json, we could construct a dynamic matrix for our deployment job. The second job, deployment-web-app, depends on determine-runners. It uses fromJson(...) to transform the JSON string into an array for the matrix. Each array element corresponds to a runner name, resulting in one parallel job per server.

  deployment-web-app:
    name: Deploy to $ on $
    environment: $
    needs: [determine-runners]
    runs-on: $
    strategy:
      fail-fast: false
      matrix:
        runner: $
    steps:
      - name: Clean Workspace Folder
        run: Remove-Item -Recurse -Force $\*

      - name: Download artifact
        uses: actions/download-artifact@v4

      # Additional steps to deploy the IIS website go here

In our case, deploying to IIS involved copying build artifacts, stopping the IIS site, replacing the files, and restarting the service. By running these steps on each runner in parallel, we reduced total deployment time and avoided manual coordination.

Lessons Learned

When we first set out, we worried that this dynamic approach would introduce more complexity than it solved. However, by automating the discovery of runners, we created a resilient pipeline that adapts as servers come online or go offline. Below are some key takeaways:

• Use Labels Strategically
  By combining environment labels (e.g., staging, production) with a fixed label (e.g., IIS-Server), we narrowed down the runner list precisely. Labels become powerful selectors when applied consistently.

• Manage GitHub App Credentials Carefully
  The process requires a GitHub App with appropriate permissions. You must secure its private key and ensure it remains installed on your repository. Losing this App or its credentials would break the token exchange and halt deployments.

• CLI Tools Preinstalled
  We used a GitHub-hosted runner to run this workflow, which already has gh and jq installed by default.

• Account for Pagination
  Our example handles only the first 100 runners. If your organization has more, implement pagination logic by iterating over pages until no runners remain.

• Embrace Parallelism
  Running deployments in parallel saved us time and reduced the risk of inconsistent state. We could also monitor each runner’s status separately, making troubleshooting easier.

Conclusion

GitHub Actions does not natively support a construct like deployment groups. By querying the GitHub API, filtering runners with jq, and building a dynamic matrix, we created a solution that scales automatically as servers change. Although it requires extra setup, a GitHub App, additional CLI tools, and careful label management, the result is a more flexible, resilient deployment pipeline.

While this post uses IIS server deployments as the example, the same technique can be applied to any deployment scenario. By defining tags or labels on your runners and building a dynamic matrix, you can select machines based on any condition, such as environment, role, or geographic region, and run workflows in parallel across them.

It’s no secret that finding true “full-stack” engineers is difficult. Most developers lean towards one area—be it backend, frontend, cloud, or pipelines—and that’s okay. But in this case, the organization needed engineers who understood the big picture. They had to be able to contribute meaningfully across the board in a small team setup, where there’s no room to say, “That’s someone else’s job.”

The Process: Lengthy, But Effective

For this reason, we committed to lengthy interviews, typically lasting 1.5 to 2 hours. It’s time-consuming, both for the candidates and for us, but it allowed us to truly assess whether someone could fit the team’s needs.

The interview structure was straightforward:

1. Introductions: We started with casual conversation—interests, hobbies, passions—to get a sense of the candidate as a person. This also helped build rapport and gave us an early impression of their communication skills.
2. Problem Discussion: I presented a simple but open-ended problem: designing an API to serve products. The task wasn’t about writing code; it was about having a meaningful conversation.

The Flow: From Idea to Production

The exercise mimicked how the team worked internally: starting with a vague business problem and analyzing it to build a working system. The candidate’s job was to walk through each stage of the process with me, while I m drawing on a whiteboard:

• Understanding the Problem: Did they ask the right questions to clarify the requirements and constraints?
• API Design: Could they explain HTTP verbs, REST principles, and how to handle authentication (e.g., what a JWT is and why it’s secure)?
• Coding: How would they implement this API? What language, framework, or libraries would they use? How would they structure the code and how to ensure quality? Did they consider testing and if so, what kind?
• Database Considerations: Did they think about indexes or the implications of their schema design?
• Production Readiness: How would they host the API? Did they mention pipelines, monitoring, or scalability? And how to get the code from their machine to production?

The goal wasn’t to see how many buzzwords they could throw out or whether they knew every detail of every tool. Instead, we focused on their reasoning, communication, and ability to problem-solve collaboratively.

The Results: The Good, the Bad, and the Lessons Learned

Out of all the interviews, we only passed three candidates to the next round. Here’s what set them apart:

1. They Could Have a Conversation: These candidates were curious, asked great questions, and actively participated in the discussion. Even when they didn’t know everything, they admitted it honestly and showed an understanding of the broader picture. For example, they recognized the need for hosting, securing, and monitoring the API—even if they weren’t experts in every tool.
2. They Thought Beyond the Immediate Problem: One standout candidate designed the system with cost optimization and scalability in mind, leveraging PaaS solutions to keep it efficient. This kind of forward-thinking demonstrated a level of maturity and ownership we rarely see.
3. They Showed Accountability: In small teams, everyone needs to pitch in across the lifecycle. These candidates understood the importance of being able to handle a variety of tasks. By contrast, many other candidates relied too heavily on the idea of separate teams handling pipelines, quality control, or rollouts.

Unfortunately, we also encountered several candidates with impressive CVs who struggled to articulate their understanding of the concepts they claimed to know. Some couldn’t design any part of the system or explain the reasoning behind their choices. Others had limited exposure to the end-to-end development lifecycle because they worked in large organizations where tasks were heavily siloed.

The Takeaway: Real Conversations Trump CVs

While resumes and buzzwords can get candidates through the door, they rarely tell the full story. A collaborative, problem-solving interview process, though exhausting, gave us the confidence to hire engineers who could truly add value to the team.

For the candidates, the process also served as a preview of the company’s expectations. By focusing on real-world problems and reasoning, we ensured alignment between the team’s needs and the candidate’s strengths.

Ultimately, hiring isn’t just about filling a role—it’s about finding the right person who can thrive in the unique environment of your organization.

In the realm of helpdesk and ticketing systems, the market is brimming with options. From Zohodesk and Freshdesk to Zendesk and Jira, the choices are many, some even offering enticing free entry points. However, a common catch with these platforms is the pricing model, which typically scales based on the number of agents, leading to a significant cost increase over time. This challenge became evident in a recent customer project I was involved in. While we successfully implemented Freshdesk as the support system for the customer’s SaaS application, our internal requirements painted a different picture.

Our needs revolved around internal operations like account management, onboarding/offboarding procedures, addressing hardware issues, and managing licenses—tasks distinctly separate from customer interactions and not fitting neatly into the development team’s responsibilities. Adding to the complexity was the customer’s ISO certification, necessitating meticulous tracking of changes and actions. This scenario required a separate system from the customer-facing helpdesk, yet something that was both minimalistic and easy to manage.

The solution lay closer than we thought. With all team members already well-versed in GitHub, leveraging its environment was a logical step. GitHub Issues, when combined with customized workflows and templates, presented a unique opportunity. It offered a familiar platform that was both cost-effective and adaptable to our specific internal needs. In this post, I’ll guide you through the process of setting up GitHub Issues as an efficient, internal helpdesk system, elucidating how it can be tailored to streamline your organizational processes, just as it did for ours.

Laying the Foundations: Initial Setup of Your GitHub Helpdesk

In the journey of transforming GitHub into an effective internal helpdesk, the initial setup plays a crucial role. GitHub offers two distinct systems for tracking activities: Issues and Discussions. Understanding the nuances of each is key to leveraging them effectively.

Issues vs. Discussions

• Issues: This feature in GitHub is straightforward. Each issue comprises a title, a descriptive body, optional labels, and assignments. It’s the go-to choice for tracking specific tasks, bugs, or requests.
• Discussions: In contrast, Discussions provide a forum-like environment. They’re ideal for cases where you want to engage in a broader conversation before possibly converting the discussion into a more formal issue. Not everything that crops up is immediately an issue, and Discussions provide the flexibility to explore topics more broadly.

For the purpose of an internal helpdesk, where submissions are likely to be direct issues, focusing on the Issues feature is the most practical approach.

Setting Up Your Repository

1. Create a New Repository: Start with a fresh slate by setting up a new repository within your organization. A simple and descriptive name like ‘servicedesk’ or ‘helpdesk’ works well. Remember to keep it internal/private to maintain confidentiality.
2. Craft Your README.md: The README.md file is the first point of contact for users visiting your repository. It’s a Markdown file that can be used to provide essential instructions and guidelines. Here’s how you can structure it:

Introduction: Briefly describe the purpose of the helpdesk and what types of issues should be submitted here.

How to Submit an Issue: Give clear, step-by-step instructions on how to create a new issue, including guidance on writing a good title and description.

Label Usage: Explain how labels are used within the repository to categorize and prioritize issues.

Response Times and Process: Outline what users can expect in terms of response times and the process their issues will go through.

For example, here’s a sample README.md file:

# Service Desk

Service Desk system for X.

## What is this?

This repository can be used to record issue requests to the service organisation operated by Y. Like requesting access to or gaining new accounts, having issues with hardware, or have problems with your workstation or phone.

This is not for software production issues; that is for the devteam, reachable in [Slack](link to slack).

Customers having questions or problems with the usage of Z, will need to go to [Freshdesk](link to freshdesk).

## How does it work?

When you want to register an item, create a [new issue](https://github.com/yourorg/yourrepo/issues/new/choose) and use the most applicable template. 

The issue will be automatically assigned to the service team at Y and they will react via the issue. 

Creating this foundational setup ensures a streamlined experience for both those managing the helpdesk and those using it, setting the stage for efficient internal support management.

Optimizing Issue Reporting: Implementing Issue Templates

A common challenge in issue tracking is receiving submissions that lack essential information. This often leads to a back-and-forth to gather the necessary details, causing delays and inefficiencies. To address this, GitHub offers a powerful tool: issue templates.

Creating Issue Templates

1. Template Files: Start by creating your issue templates. These templates are files that reside in the .github/ISSUE_TEMPLATE folder of your repository. You can create multiple files here to cater to different types of requests or issues.

2. Design Your Templates: Each template should be designed to collect specific data pertinent to the type of issue it represents. This structured approach ensures that when a user submits an issue, they provide all the necessary information upfront.

An example of a template for requesting a new account:

name: Accounts
description: Onboarding or offboarding, getting access to a system
title: "[Account]: "
labels: ["account", "triage"]
assignees:
  - userx
  - usery
body:
  - type: markdown
    attributes:
      value: |
        Use this template to request access to a system, onboard or offboard an employee or ask for a change in permissions. 
  - type: input
    id: person
    attributes:
      label: Contact Details
      description: For who is the change intended?
      placeholder: ex. email@example.net
    validations:
      required: true
  - type: textarea
    id: what-need-to-change
    attributes:
      label: What need to change?
      description: What is the action that needs to be taken?
      placeholder: Tell us what needs to be done
      value: "This person need access to..."
    validations:
      required: true
  - type: input
    id: when
    attributes:
      label: When
      description: When does it need to be done?
      placeholder: Leave empty for ASAP or specify a date
    validations:
      required: false
  

Or for hardware issues:

name: Hardware
description: Issues with hardware, like replacing, defects
title: "[Hardware]: "
labels: ["hardware", "triage"]
assignees:
  - userx
  - usery
body:
  - type: markdown
    attributes:
      value: |
        Use this template to request support on anykind of hardware you have; broken phone, PC not working, lost mouse, use this to get us involved.
  - type: input
    id: person
    attributes:
      label: Contact Details
      description: Who has issues with the hardware
      placeholder: ex. email@example.net
    validations:
      required: true

  - type: dropdown
    id: area
    attributes:
      label: Area
      options:
        - Desktop
        - Phone  
      description: Indicate which area is impacted 
  - type: textarea
    id: what-need-to-change
    attributes:
      label: What need to change?
      description: What is the action that needs to be taken?
      placeholder: Tell us what needs to be done
      value: "This piece of equipement is no longer working..."
    validations:
      required: true    
  - type: input
    id: when
    attributes:
      label: When
      description: When does it need to be done?
      placeholder: Leave empty for ASAP or specify a date
    validations:
      required: false

Enhancing Clarity with Emoticons in Titles

• Visual Differentiation: Incorporating emoticons in issue template titles can significantly aid in distinguishing between different types of issues, especially in a helpdesk context.
• Examples:
  • Use a 💻 emoji for hardware-related issues.
  • A 🔑 emoji could denote account-related problems.
• Immediate Recognition: Emoticons allow team members to quickly recognize the category of an issue, aiding in the swift identification and prioritization of tasks.
• Consistency: Maintain consistency in the use of emoticons across all templates to ensure clarity and prevent confusion.

By integrating emoticons into your issue titles, you bring an element of visual distinction to your GitHub helpdesk system. This not only makes the issue list more engaging but also enhances the efficiency and intuitiveness of issue categorization and management.

Configuring the Template Selector

Create a config.yml File: This file goes in the same .github/ISSUE_TEMPLATE folder. It’s used to configure how users select an issue template. For example, here’s a sample config.yml file:

blank_issues_enabled: true
contact_links:
  - name: Freshdesk
    url: https://support.x.nl/a/dashboard/default
    about: For customer issues.

Configuration Options:

• blank_issues_enabled: true - This setting allows users to still create blank issues. However, disabling this feature means users can only use your predefined templates.
• Contact Links: These are additional options you can provide for users. For example:
  • Freshdesk for customer issues with a direct link to your Freshdesk dashboard.
  • Slack for devteam issues with a direct link to your Slack workspace.

  These links not only guide users to the right resources but also help in segregating different types of issues efficiently.

By implementing these templates and configuration settings, you streamline the issue submission process. Users are guided to provide all necessary information, reducing the need for follow-up and speeding up the resolution process. To direct users to the template selector, use a URL like https://github.com/yourorg/yourrepo/issues/new/choose. This ensures a more organized and efficient approach to managing internal helpdesk requests.

Effective Issue Management: Workflows and Automation

As the number of issues in your GitHub helpdesk repository grows, effective management and maintenance become crucial. To ensure efficiency and order, we utilize a combination of GitHub workflows and Probot actions.

Preventing Empty Issues

Request-Info Bot: One of the common frustrations in issue tracking is receiving issues with a title but no descriptive content. To address this, we implement the Request-Info bot (Request Info Probot). This bot is configured to prompt for more information on such issues. Install it in your helpdesk repository and create a .github/config.yml file with the following contents:

# Configuration for request-info - https://github.com/behaviorbot/request-info

# *Required* Comment to reply with
requestInfoReplyComment: >
  We would appreciate it if you could provide us with more info about this issue!

# *OPTIONAL* default titles to check against for lack of descriptiveness
# MUST BE ALL LOWERCASE
requestInfoDefaultTitles:
  - update readme.md
  - updates

# *OPTIONAL* Label to be added to Issues and Pull Requests with insufficient information given
requestInfoLabelToAdd: needs-more-info

Automated Assignment of Issues

Auto-Assign Issue Action: To ensure issues are promptly addressed, we use the Auto-Assign Issue Action. This action automatically assigns new issues to the responsible team members. While issue templates allow for assigning users, this action covers scenarios where blank issues are created.

Labeling for Triage

Triage-New-Issues App: Apply a ‘Triage’ label to new issues using the Triage New Issues App. This helps in quickly identifying and categorizing new submissions for further action.

Managing Stale Issues

Stale Issue Workflow: Keeping issues open for too long without activity can clutter your helpdesk. To manage this, we implement a workflow to mark stale issues:

   name: 'Close stale issues and PRs'
   on:
     schedule:
       - cron: '30 1 * * *'

   jobs:
     stale:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/stale@v9
           with:
             stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
             days-before-stale: 30
             days-before-close: 5

This workflow runs daily, identifying issues open for more than 30 days and marking them as stale. This process helps maintain a cleaner, more manageable issue list and ensures issues don’t linger unresolved. You do want to consider the impact of closing stale issues, however. For example, if an issue is still relevant, you might want to keep it open, even if it’s stale. However, this can help with SLA compliance and ensure issues are addressed in a timely manner.

By integrating these tools and workflows, you create a dynamic and responsive helpdesk system within GitHub, capable of handling issues efficiently and ensuring nothing falls through the cracks.

Harnessing Data: Implementing Analytics in Your GitHub Helpdesk

One of the advantages of professional helpdesk systems is their capability to provide analytics, such as resolution times and the duration for which issues remain open. While GitHub might not offer these features out-of-the-box, we can achieve similar analytics through a custom workflow.

Setting Up Monthly Issue Metrics

This workflow is designed to run monthly and collect data on issues created and resolved within that period, providing valuable insights into the performance of your helpdesk system.

Workflow Configuration:

name: Monthly issue metrics
on:
  workflow_dispatch:
  schedule:
    - cron: '3 2 1 * *'

jobs:
  build:
    name: issue metrics
    runs-on: ubuntu-latest
    permissions:
      actions: read
      issues: write
    steps:

    - name: Get dates for last month
      shell: bash
      run: |
        # Script to calculate date range of the previous month
        [Date calculation script here]

    - name: Run issue-metrics tool
      uses: github/issue-metrics@v2
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SEARCH_QUERY: 'repo:yourrepo/servicedesk is:issue created:${{ env.last_month }} -reason:"not planned"'

    - name: Create issue
      uses: peter-evans/create-issue-from-file@v4
      with:
        title: Monthly issue metrics report
        content-filepath: ./issue_metrics.md
        assignees: mivano

Key Components:

• Date Calculation: The workflow begins by calculating the date range for the previous month. This range is used to filter the issues for the metrics report.
• Issue Metrics Tool: Utilizing the ‘github/issue-metrics@v2’ action, the workflow gathers data on issues created within the specified date range.
• Report Creation: An issue is automatically created containing the metrics, which can then be labeled, assigned, and reviewed like any other issue.

This workflow transforms GitHub into a more robust helpdesk tool, providing monthly analytics similar to those offered by specialized helpdesk systems. The generated report gives a clear picture of helpdesk performance, helping identify areas for improvement. More information on this action and its capabilities can be found on the GitHub Blog. By incorporating this workflow, you enhance the functionality of your GitHub helpdesk, leveraging data to drive efficiency and effectiveness.

Automating Recurring Tasks: Workflow for Scheduled Issues

In the management of any helpdesk or support system, certain tasks are bound to recur regularly. These can range from routine checks to periodic backups. To handle such recurring issues efficiently within GitHub, we can leverage the power of automated workflows. This approach ensures that these tasks are consistently addressed without fail.

Creating a Workflow for Recurring Issues

Here’s an example of a workflow designed to create a new issue for quarterly checks of users and authorizations:

Workflow Definition:

name: Quarterly check users and authorisations
on:
  workflow_dispatch:    
  schedule:
    - cron: 0 12 1 */3 *

jobs:
  create_issue:
    name: Create issue - Quarterly check users and authorisations
    runs-on: ubuntu-latest
    steps:
      - name: Create issue 
        run: |
          new_issue_url=$(gh issue create \
            --title "$TITLE" \
            --label "$LABELS" \
            --body "$BODY" \
            --assignee "$ASSIGNEE")
        env:
          GITHUB_TOKEN: $
          GH_REPO: $
          TITLE: Quarterly check users and authorisations
          LABELS: iso
          ASSIGNEE: userX,userY
          BODY: |
            Perform the quarterly checks for users and the authorisations. See the ISMS for more details.
          PINNED: false

Key Components:

• Cron Schedule: Set to trigger quarterly (0 12 1 */3 *). This timing can be adjusted based on the frequency needed for the particular task.
• Issue Creation Step: Automates the creation of a new GitHub issue with specific details like title, labels, body content, and assignees.

Expanding the Workflow

The beauty of this system lies in its flexibility. By modifying the trigger and the content of the issue, and saving it as a new file in the .github/workflows folder, you can create workflows for various other recurring issues. This method is not only efficient but also ensures consistency and reliability in performing routine tasks that are crucial for your organization.

Implementing such automated workflows for recurring issues in your GitHub helpdesk repository aids in maintaining regularity and ensures that important tasks are not overlooked. This level of automation brings a new dimension of efficiency to your internal helpdesk operations.

Conclusion: GitHub as an Ideal Internal Helpdesk Solution

In conclusion, leveraging GitHub for your internal helpdesk system offers numerous advantages, especially when considering the ecosystem and tooling already familiar to many teams. This approach not only streamlines internal support processes but also adds a layer of efficiency and integration that traditional helpdesk tools may not provide.

Key Advantages of Using GitHub for Internal Helpdesk:

1. Unified Ecosystem: Staying within GitHub means no need to juggle between different platforms, reducing the learning curve and integration complexities.

2. Cost-Effective: Eliminates the additional costs associated with third-party helpdesk tools, as GitHub already forms part of many organizations’ toolsets.

3. Robust Issue Tracking Features: Utilize GitHub’s native issue features like templates, formatting options, attachments, mentions, and cross-referencing, enhancing communication and tracking efficiency.

4. Customizable Workflows and Apps: The ability to add workflows and apps further tailors the experience to your organization’s specific needs.

5. Project Boards for Visualization: Employ GitHub’s project boards for a visual representation of tasks, allowing you to effortlessly manage and move items through to completion.

However, it’s important to note a key aspect regarding issue visibility.

Visibility of Issues:

• In GitHub, issues in a repository are visible to all team members with write access, as this access level is required to create issues.
• Consequently, all tickets are visible to these team members. While this promotes transparency and team collaboration, it also means sensitive information could potentially be exposed to a wider internal audience.
• Remember, as this is an internal system, it’s generally expected that confidential or sensitive information should not be shared in these tickets. Nonetheless, it’s vital to consider this aspect of visibility.

Securing Your Helpdesk:

• If complete privacy for issues is a priority, consider securing the repository. This adds a layer of confidentiality but requires alternative methods for issue creation.
• One such method is using email integrations for issue creation, like the solution offered by scitor.io. This allows for a more controlled and private submission of issues while still benefiting from GitHub’s issue management capabilities.

By adding these considerations into your strategy, you can tailor your GitHub helpdesk to meet both the operational and privacy needs of your organization. This enhanced approach ensures that you not only leverage GitHub for its efficiency and familiarity but also maintain the necessary level of security and privacy for internal operations.

External Use Considerations:

While GitHub excels for internal use, there are challenges when considering external helpdesk applications. Non-GitHub users cannot create issues, and external access to a private helpdesk repository is not advisable. Additionally, GitHub doesn’t natively handle email-based ticket creation or manage attachments from external sources effectively.

Solution for External Use: Scitor.io

For those seeking to extend GitHub’s capabilities to an external audience, Scitor.io offers a solution. It transforms GitHub into a more traditional helpdesk system, bridging the gap for external user interactions.

Wrapping Up

For internal team use, GitHub stands out as a practical, cost-effective, and efficient tool for helpdesk management. It consolidates various aspects of issue tracking and resolution into a single, integrated platform, familiar to most developers and IT professionals. By following the outlined steps and considerations, you can effectively transform GitHub into a powerful tool for managing your internal helpdesk needs, harnessing its full potential to streamline and enhance your support processes.

Photo by CDC on Unsplash

To speed up the process, you can cache the NuGet packages. This will make sure that the next time you run a build, the NuGet packages will be restored from the cache instead of the NuGet website. To make sure that the cache is invalidated when a new version of a NuGet package is referenced, you can use the hash of the project files as part of the cache key. This will make sure that the cache is invalidated when changes are made to the project files.

For completness sake, I have included a full example of a workflow file that uses caching to speed up the build process. GitHub will automatically add a post step to store the files in the cache.

By setting the NUGET_PACKAGES environment variable, you can make sure that the NuGet packages are restored to the same location as the cache. This will make sure that the cache is used when restoring the NuGet packages.

name: Build Services
on:
  push:

jobs:
  build:
    runs-on: windows-latest
    name: Build services
    permissions:
      packages: write
      contents: read
    env:
      NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: 7.0.x

      - uses: actions/cache@v3
        with:
          path: ${{ github.workspace }}\.nuget\packages
          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj') }} #hash of project files
          restore-keys: |
            ${{ runner.os }}-nuget-

      - name: Restore dependencies
        run:  dotnet restore solution.sln 

      - name: Build
        run: dotnet build solution.sln  --no-restore
        
      - name: Test
        run: dotnet test solution.sln  --no-build --verbosity normal
      
      - name: Publish
        run: | 
          dotnet publish solution.sln -c Release --no-restore  -o publish 

      - name: Upload a Build Artifact
        uses: actions/upload-artifact@v3
        with:
          name: services
          path: publish/**
          if-no-files-found: error 

This workflow will restore, build, test and package the solution. The resulting package will be uploaded as an artifact and can be deployed in subsequent steps.

Do use the logs to verify that the cache is used and validate if the amount of time that is used is worthwhile.

In the modern SaaS landscape, flexibility is key. One commonly sought-after feature in Helpdesk and similar software is the ability to send emails on behalf of a different domain—your customer’s domain, for instance. However, spam prevention and domain authentication can make this tricky. If you’re building a SaaS solution that deals with email services, like my current project Scitor, this blog post is for you. In it, I’ll explain how I implemented a secure way to send emails from my customer’s domain, using SendGrid and .NET.

The Problem

When implementing Scitor, a Helpdesk SaaS that accepts emails and converts them into GitHub discussions, I ran into a challenge. The solution needed to send replies back to the original recipient’s email address, and many customers wanted those emails to come from their own domain.

However, due to spam prevention measures, you can’t simply send emails from a domain you don’t own or haven’t authenticated. This is not only bad for your spam reputation; SendGrid explicitly forbids it unless the ‘from’ email address has been verified.

The Solution: Domain Authentication

I found a way to allow customers to authenticate their domain without giving them access to my SendGrid account. I also did not have a GUI or admin interface for my solution, so I needed to automate the process as much as possible within the GitHub discussion.

Step 1: The /authenticate-domain Command

The first step is to create a command—/authenticate-domain that customers can use to begin the domain authentication process. When a customer issues this command by adding it to a comment in the discussions, the following code creates a domain registration at SendGrid via the StrongGrid library:

public async Task<DomainRegistrationResult> CreateDomain(string domain)
{
    var result = await _strongGridClient.SenderAuthentication.CreateDomainAsync(domain);

    return new DomainRegistrationResult(
        result.Id,
        result.IsValid,
        new DNSRecordResult(result.DNS.Dkim1.Data, result.DNS.Dkim1.Type, result.DNS.Dkim1.Host),
        new DNSRecordResult(result.DNS.Dkim2.Data, result.DNS.Dkim2.Type, result.DNS.Dkim2.Host),
        new DNSRecordResult(result.DNS.MailCName.Data, result.DNS.MailCName.Type, result.DNS.MailCName.Host)
    );
}

public record DomainRegistrationResult(long DomainId, bool IsValid, DNSRecordResult Dkim1, DNSRecordResult Dkim2, DNSRecordResult CName);

public record DNSRecordResult(string Data, string Type, string Host);

The function returns DNS records that the customer needs to configure on their end.

Step 2: Configuring DNS Settings

I output these DNS settings into the GitHub discussion as an additional comment. The customer is then responsible for adding these DNS records, a process that can take some time and differ per DNS provider.

Step 3: The /verify-domain Command

Once the customer has configured their DNS settings, they issue the /verify-domain command. This function verifies the domain using SendGrid’s API:

public async Task<DomainValidationResult> VerifyDomain(long domainId)
{
    var result = await _strongGridClient.SenderAuthentication.ValidateDomainAsync(domainId);
    return new DomainValidationResult(
        result.DomainId,
        result.IsValid,
        new DNSRecordValidationResult(result.ValidationResults.Dkim1.IsValid,
            result.ValidationResults.Dkim1.Reason),
        new DNSRecordValidationResult(result.ValidationResults.Dkim2.IsValid,
            result.ValidationResults.Dkim2.Reason),
        new DNSRecordValidationResult(result.ValidationResults.Mail.IsValid,
            result.ValidationResults.Mail.Reason)
    );
}

public record DomainValidationResult(long DomainId, bool IsValid, DNSRecordValidationResult Dkim1, DNSRecordValidationResult Dkim2, DNSRecordValidationResult CName);

public record DNSRecordValidationResult(bool IsValid, string Reason);

When all records are validated successfully, the customer can start using their own domain as the sender. If not, I list the problems that still need to be fixed.

I do store the returned domainId in my database, so I can use it to remove the domain later if needed and check if the verification has been completed or not. There is also an explicit /delete-domain command that customers can use to remove the domain from my SendGrid account.

Conclusion

Domain authentication may sound complex, but with a bit of code and the help of SendGrid’s StrongGrid library, it can be automated to a large extent, even for customers who don’t have direct access to your SendGrid account. This ensures that your SaaS can send emails from different domains while maintaining good spam reputation and adhering to SendGrid’s rules.

Unreliable Network and Rate Limitations

When making requests to an API, calls can fail for various reasons ranging from network unreliability to server-side rate limits. Repeated retries, lengthy waiting periods, or disregard for server-specified limitations can lead to inefficiencies or even service denial.

Polly - .NET Resilience Library

To address these challenges, Polly, a .NET resilience and transient-fault-handling library, was employed. It enables developers to define policies like Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback, thereby increasing the resilience of API calls.

Defining a Resilient Policy with Polly

The core of this approach lies in defining a resilient policy that combines a wait-and-retry policy with a timeout policy. Below is the code snippet that showcases this process:

public static class PollyPolicyExtensions
{
    public static IAsyncPolicy<HttpResponseMessage> GetRetryAfterPolicy()
    {
        // Define WaitAndRetry policy
        var waitAndRetryPolicy = Policy.HandleResult<HttpResponseMessage>(msg => 
                msg.StatusCode == HttpStatusCode.TooManyRequests)
            .WaitAndRetryAsync(
                retryCount: 5,
                sleepDurationProvider: (_, response, _) => {
                    var headers = response.Result?.Headers;
                    if (headers != null)
                    {
                        foreach (var header in headers)
                        {
                            if (header.Key.ToLower().Contains("retry-after") && header.Value != null)
                            {
                                if (int.TryParse(header.Value.First(), out int seconds))
                                {
                                    return TimeSpan.FromSeconds(seconds);
                                }
                            }
                        }
                    }
                    // If no header with a retry-after value is found, fall back to 2 seconds.
                    return TimeSpan.FromSeconds(2);
                },
                onRetryAsync: (msg, time, retries, context) => Task.CompletedTask
            );

        // Define Timeout policy
        var timeoutPolicy = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(60));

        // Wrap WaitAndRetry with Timeout
        var resilientPolicy = Policy.WrapAsync(timeoutPolicy, waitAndRetryPolicy);

        return resilientPolicy;
    }
}

This policy intelligently handles HTTP 429 (Too Many Requests) responses by parsing the “retry-after” header and waiting for the specified duration before retrying, up to five times. If the header isn’t found, it falls back to a two-second wait time. Additionally, a timeout policy ensures that calls do not wait longer than 60 seconds.

Applying the Policy

The defined policy is then applied to the HTTP client, as shown below:

registrations.AddHttpClient("CostApi", client =>
{
  client.BaseAddress = new Uri("https://management.azure.com/");
  client.DefaultRequestHeaders.Add("Accept", "application/json");
}).AddPolicyHandler(PollyPolicyExtensions.GetRetryAfterPolicy());

This registration is placed in the ConfigureServices method of the Startup class, ensuring that the policy is applied to all HTTP calls made by the application when they request this CostApi httpclient from the factory.

Conclusion

The combination of Polly’s features offers a robust and scalable solution to the common challenges faced when making resilient API calls. By leveraging this method, developers can create a more stable and efficient communication with the Azure Cost API, providing a seamless experience even in unpredictable network conditions.

For those looking to enhance their API interactions, exploring Polly and the resilient policies it supports can be a game-changer. The flexibility and reliability it offers make it an essential tool for modern developers navigating the complexities of network communication.

Default Subscription ID

The Azure CLI allows users to set a default subscription ID, and mimicking this behavior in the Azure Cost CLI tool brings in alignment and familiarity. The question was, how could this be achieved programmatically?

Executing the AZ Command

The solution lay in executing the Azure CLI’s az account show command, which returns information about the current account, including the active subscription ID.

The following C# code is used to execute the command and extract the subscription ID:

public static class AzCommand
{
    public static string GetDefaultAzureSubscriptionId()
    {
        var startInfo = new ProcessStartInfo
        {
            FileName = "az",
            Arguments = "account show",
            RedirectStandardOutput = true,
            RedirectStandardError = true,
            UseShellExecute = false,
            CreateNoWindow = true
        };

        using (var process = new Process { StartInfo = startInfo })
        {
            process.Start();
            string output = process.StandardOutput.ReadToEnd();
            process.WaitForExit();

            if (process.ExitCode != 0)
            {
                string error = process.StandardError.ReadToEnd();
                throw new Exception($"Error executing 'az account show': {error}");
            }

            using (var jsonDocument = JsonDocument.Parse(output))
            {
                JsonElement root = jsonDocument.RootElement;
                if (root.TryGetProperty("id", out JsonElement idElement))
                {
                    string subscriptionId = idElement.GetString();
                    return subscriptionId;
                }
                else
                {
                    throw new Exception("Unable to find the 'id' property in the JSON output.");
                }
            }
        }
    }
}

Here’s what the code does, step by step:

1. Creating Process Start Information: A ProcessStartInfo object is initialized with the required command and settings.
2. Executing the Process: A new process is started to execute the command, and the standard output is read.
3. Error Handling: If the command execution fails, an error is thrown with the details.
4. Parsing the Output: The JSON output is parsed to retrieve the id property, which holds the subscription ID.

Seamless Integration

The above code snippet integrates seamlessly into the Azure Cost CLI tool, providing an efficient and consistent way to retrieve the current active Azure subscription ID. By leveraging existing CLI commands and C# process management, developers can easily obtain context-specific information.

This example further illustrates how familiar tools and libraries can be used to build sophisticated features, bridging gaps between different systems and providing a cohesive user experience.

Authentication Complexity

Obtaining a token to access the Azure Cost API without burdening users with usernames, passwords, or the creation of service accounts was a challenging issue. The need for a straightforward application that could retrieve the account information directly from the environment necessitated a unique approach.

Utilizing DefaultAzureCredentials

The answer was found in DefaultAzureCredentials. This functionality attempts various credential providers to find a valid one, offering a seamless way to authenticate. The approach enabled the retrieval of a token without adding complex authentication steps.

ChainedTokenCredential with AzureCliCredential

To refine the process, a new ChainedTokenCredential was created, placing the AzureCliCredential at the start and then falling back to the default options if necessary. Below is the code snippet that encapsulates this elegant solution:

// Get the token by using the DefaultAzureCredential, but try the AzureCliCredential first
var tokenCredential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new DefaultAzureCredential());

// Fetch the token and ask explicitly for the Azure Cost API scope
var token = await tokenCredential.GetTokenAsync(new TokenRequestContext(new[]
    { $"https://management.azure.com/.default" }));

// Set the resulting token as the bearer token for the HTTP client
_client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);

Simplicity and Flexibility

This method’s success lies in its simplicity and flexibility, enhancing user experience and leveraging existing Azure CLI setups across different environments.

Conclusion

The Azure Cost CLI tool is more than a utility; it represents a thoughtful response to a real-world problem. By innovatively combining ChainedTokenCredential with AzureCliCredential, a solution was crafted that is not only efficient and secure but also simple to use.

For developers and administrators seeking a user-friendly way to interact with the Azure Cost API, this approach provides a practical and elegant path forward.

In a recent conversation with a senior colleague, I jokingly referred to myself not as a full stack developer, but as a “full circle developer”. While it started as a humorous remark, the more I thought about it, the more the concept resonated with me. In the fast-evolving world of technology, we often find ourselves coming full circle, revisiting the same technologies and challenges we thought we had left behind.

The Reality of Being a Full Stack Developer

The term “full stack developer” implies a mastery of everything from front-end interfaces to back-end infrastructure, databases, cloud services, and beyond. It’s an attractive idea but often an unrealistic one. Our field has become so complex that mastering every aspect is virtually impossible. And yet, there’s an underlying continuity to the work we do, a cyclical nature that reveals itself in surprising ways.

Full Circle: Back to Basics

Currently, I find myself working on a project that has brought me back to where I started 20 years ago. I’m working with an IIS server, installing Windows Services, and communicating with MS SQL server — things I hoped I wouldn’t be doing anymore with the advent of cloud technology.

Despite all the advances in our field, the cutting-edge tools, and the cloud-first approach that dominates today’s landscape, some things remain surprisingly constant. The technologies I thought were relics of the past are still very much alive, still solving problems, still serving a purpose.

The Full Circle Developer: Embracing the Past, Present, and Future

As a Full Circle Developer, I’ve learned to embrace this cyclical nature. I value not only the latest trends and tools but also the lessons learned from decades of software development history. I understand that trends come and go, but underlying principles endure. I see the connections between past and present and draw on that broad perspective to solve problems and innovate.

This approach is not about clinging to the past or rejecting the new. It’s about recognizing that the old and the new are often two sides of the same coin. It’s about being adaptable, forward-looking, and yet grounded in the enduring truths of our craft.

Conclusion

The concept of the Full Circle Developer offers a balanced and sustainable approach to a career in software development. It acknowledges the complexity and diversity of our field while emphasizing the timeless principles that make us effective, regardless of the current trends.

So as I find myself working with technologies I used 20 years ago, I don’t see it as a step back but as a reminder of the continuity and resilience of our field. The tools may change, but the craft remains the same.

What about you? Do you see yourself as a Full Stack Developer, a Full Circle Developer, or something else entirely? How has your perspective on your career evolved over time? I’d love to hear your thoughts.

I have set the container to be a public one, and by generating random file names, I have some obfuscation so that iterating over them becomes complicated, but the URL is still sharable. These GUIDs also allow me to avoid name collisions as it is user input where I have no saying in what they upload.

But when you now want to retrieve the file, you get that random file name and not the original one it was uploaded with.

I can download the file to my server first and then return it with a correct name, but this will bring the additional IO to my system. I rather have people directly hit the Azure infrastructure.

Luckily you can set the content-disposition header. This header tells the client what to do with the file, like showing it inline or downloading it, and what the filename needs to be. This property is in there for some years, so you can set this directly using the SDK when you create a file:

 var blobName = $"{cId}/{rId}/{Guid.NewGuid():N}.{extension}";
 
 BlobClient blobClient = containerClient.GetBlobClient(blobName);

 // Upload a byte[] to a blob
 await blobClient.UploadAsync(
 new MemoryStream(attachmentContent),
 new BlobHttpHeaders
 {
 ContentType = attachmentType,
 ContentDisposition = $"attachment; filename=\"{attachmentName}\""
 });

 string downloadUrl = blobClient.Uri.AbsoluteUri;

However, when I now used the public URL, I still got the long GUID-like name back, and the content-disposition header was missing. It appears that you need to specify the x-ms-version: 2019-12-12 header as well. This is a bit annoying to set on a GET request in a browser as you cannot specify any headers, so we need to force the storage account to always use this version.

There is no easy dropdown in the portal, and as it is a once-off action, you can use the Cloud Shell (with Powershell) to do this:

$ctx = New-AzureStorageContext -StorageAccountName name-of-storageaccount -StorageAccountKey your-access-key
Update-AzureStorageServiceProperty -ServiceType Blob -DefaultServiceVersion 2019-12-12 -Context $ctx

When you now fetch the file using the public url, you get the header included and as such the correct filename. But it took me some while to figure out that this is not the default behaviour of the storage account, so make sure to check the DefaultServiceVersion.