Skip to content

main.md

Latest commit

 

History

History
143 lines (120 loc) · 6.84 KB

main.md

File metadata and controls

143 lines (120 loc) · 6.84 KB

GitHub Developer Experience(DevEx) Accelerator

Overview

The GitHub Developer Experience (DevEx) Accelerator is an application designed to enhance the developer experience on GitHub, by providing a set of self-service mechanisms and features to streamline the onboarding and compliance of your repositories within your GitHub organizations.
This application is built using .NET Core. It supports multiple data stores, including SQL Server and CosmosDB, and integrates with Azure Key Vault for secure storage of sensitive information.

Getting started

Prerequisites

  • .NET Core 9
  • A Sql Server instance or CosmosDB account
  • Azure Key Vault to store the private PEM key certificate
  • Have a properly setup GitHub App with the necessary permissions. See GitHub setup for more details.

AppSettings.json Configuration

Key Type Description
Logging:LogLevel:Default String Specifies the default log level.
Logging:LogLevel:Microsoft.AspNetCore String Log level for Microsoft.AspNetCore namespace.
AllowedHosts String Comma-separated list of allowed hosts.
AllowedOrigins Array List of allowed origins for CORS. Example: https://localhost:8000
AppLocale String Application locale, optional, defaults to "en" (English).
GitHub:AppId String GitHub App ID.
GitHub:WebhookSecret String Secret for GitHub webhooks.
GitHub:RepoOnboarding String Repository for onboarding.
GitHub:RepoInventory String Repository for inventory.
GitHub:RepoPolicy String Repository for policy.
Azure:KeyVaultName String Name of the Azure Key Vault.
Azure:KeyName String Name of the key in Azure Key Vault.
Azure:AzureMonitor:EnableTelemetry String Whether to enable telemetry or not.
Azure:AzureMonitor:UseEntraIdAuthentication String When telemetry is enabled, whether to use entra for authentication vs Instrumentation Key.
DataStore:Type String Type of data store (FileSystem, CosmosDb, SqlServer).
DataStore:FileSystem:FilePath String File path for file system data store. This is a directory.
DataStore:CosmosDb:Database String Database name for Cosmos DB.
DataStore:CosmosDb:ConnectionString String Connection string for Cosmos DB.
DataStore:CosmosDb:GitHubWebhooksContainer String Container for GitHub webhooks in Cosmos DB.
DataStore:SqlServer:ConnectionString String Connection string for SQL Server.

Example

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  // Filter for hostnames app can bind to
  "AllowedHosts": "*",
  "AllowedOrigins": [],
  // optional, defaults to en (english)
  "AppLocale": "",
  "GitHub": {
    "AppId": "",
    "WebhookSecret": "",
    "RepoOnboarding": "",
    "RepoInventory": "",
    "RepoPolicy": "",
  },
  "Azure": {
    "KeyVaultName": "",
    "KeyName": "",
    "AzureMonitor": {
      "EnableTelemetry": true,
      "UseEntraIdAuthentication": false
    }
  },
  "DataStore": {
    // FileSystem, CosmosDb, SqlServer
    "Type": "",
    "FileSystem": {
      "FilePath": ""
    },
    "CosmosDb": {
      "Database": "",
      "ConnectionString": "",
      // Each container requires a specific partition key. Ensure these are set correctly in your CosmosDB instance.
      "GitHubWebhooksContainer": ""
    },
    "SqlServer": {
      "ConnectionString": ""
    }
  }
}

GitHub setup

Before you can use the GitHub DevEx Accelerator, you need to set up a GitHub App and configure it with the necessary permissions. Please follow the guide here to do so.

You will also need to create 3 repositories in your organization:

  • <onboarding-repository-name>: This repository will be used for onboarding. It should contain the issue templates that will be used for onboarding.
  • <inventory-repository-name>: This repository will be used for inventory. It will contain the inventory metadata.
  • <policy-repository-name>: This repository will be used for the policies. It will contain the policies metadata.

Running the application

You will need a proxy such as dev tunnels or something such as Smee to route the requests from the GitHub platform to your computer

To run the application locally, you can use the following command in the terminal:

If you plan on using dev tunnels:

Run the following once:

dotnet dev-certs https --trust

Then run the application with the HTTPS profile:

dotnet run --launch-profile https

If you plan on using a third-party proxy such as Smee, you will need to export the ASP.NET Core development certificate:

Run the following once:

dotnet dev-certs https --trust --export-path /path/to/aspnetcoredevcert.pfx --password YourPassword --format pfx

Then run the application with the HTTPS profile:

dotnet run --launch-profile https

If you are using Smee, you will need to export your certificate to a CER file (a binary X.509 certificate)

openssl pkcs12 -in /path/to/aspnetcoredevcert.pfx -clcerts -nokeys -out /path/to/aspnetcoredevcert.cer

and use export it

export NODE_EXTRA_CA_CERTS=/path/to/aspnetcoredevcert.cer

or in PowerShell:

$Env:NODE_EXTRA_CA_CERTS="/path/to/aspnetcoredevcert.cer"

The localhost endpoint for Smee to use will be https://localhost:7135/api/github/webhook