GitHub Action for Registering a Machine Learning Model in Azure

Deprecation notice

This Action is deprecated. Instead, consider using the CLI (v2) to manage and interact with Azure Machine Learning models in GitHub Actions.

Important: The CLI (v2) is not recommended for production use while in preview.

Usage

The Register Machine Learning Models with Azure action will deploy your model on Azure Machine Learning using GitHub Actions.

Get started today with a free Azure account!

This repository contains a GitHub Action for registering Machine Learning Models with Azure Machine Learning model registry for use in deployment and testing. This action is designed to register models that may or may not have been trained using Azure Machine Learning. If they are not trained using Azure Machine Learning, we expect the model to be present in your GitHub Repository.

Additionally, this action also supports model comparison, if the model has been created by an Azure Machine Learning (pipeline) run and is not stored in your repository. This GitHub Action allows you to define metrics that will be compared with the latest model that is registered under the same name and the newly trained model will only be registered, if it performs better for all specified metrics. For more details look in the parameters_file section below.

Dependencies on other GitHub Actions

• Checkout Checkout your Git repository content into GitHub Actions agent.
• aml-workspace This action requires an Azure Machine Learning workspace to be present. You can either create a new one or re-use an existing one using the action.

Utilize GitHub Actions and Azure Machine Learning to train and deploy a machine learning model

This action is one in a series of actions that can be used to setup an ML Ops process. We suggest getting started with one of our template repositories, which will allow you to create an ML Ops process in less than 5 minutes.

1. Simple template repository: ml-template-azure

   Go to this template and follow the getting started guide to setup an ML Ops process within minutes and learn how to use the Azure Machine Learning GitHub Actions in combination. This template demonstrates a very simple process for training and deploying machine learning models.

2. Advanced template repository: mlops-enterprise-template

   This template demonstrates how the actions can be extended to include the normal pull request approval process and how training and deployment workflows can be split. More enhancements will be added to this template in the future to make it more enterprise ready.

Example workflow for registering a Machine Learning Model in Azure

name: My Workflow
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - name: Check Out Repository
      id: checkout_repository
      uses: actions/checkout@v2

    # AML Workspace Action
    - uses: Azure/aml-workspace
      id: aml_workspace
      with:
        azure_credentials: ${{ secrets.AZURE_CREDENTIALS }}

    # AML Run Action
    - uses: Azure/aml-run@v1
      id: aml_run
      with:
        azure_credentials: ${{ secrets.AZURE_CREDENTIALS }}

    # AML Register Model Action
    - uses: Azure/aml-registermodel@v1
      id: aml_registermodel
      with:
        # required inputs
        azure_credentials: ${{ secrets.AZURE_CREDENTIALS }}
        run_id:  ${{ steps.aml_run.outputs.run_id }}
        experiment_name: ${{ steps.aml_run.outputs.experiment_name }}
        # optional inputs
        parameters_file: "registermodel.json"

Inputs

azure_credential (Azure Credentials)

Azure credentials are required to connect to your Azure Machine Learning Workspace. These may have been created for an action you are already using in your repository, if so, you can skip the steps below.

Install the Azure CLI on your computer or use the Cloud CLI and execute the following command to generate the required credentials:

# Replace {service-principal-name}, {subscription-id} and {resource-group} with your Azure subscription id and resource group name and any name for your service principle
az ad sp create-for-rbac --name {service-principal-name} \
                         --role contributor \
                         --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group} \
                         --sdk-auth

This will generate the following JSON output:

{
  "clientId": "<GUID>",
  "clientSecret": "<GUID>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>",
  (...)
}

Add this JSON output as a secret with the name AZURE_CREDENTIALS in your GitHub repository.

experiment_name (Experiment Name)

This action input defines the experiment name to which the run with the ID run_id belongs to. This run must have created a model file with the name model_file_name (defined in the input file). The model file will be registered in the model registry in Azure Machine Learning by this action. If this input is not defined, the action will try to find a model file with the name model_file_name (defined in the parameters file) in your GitHub repository. If the model file is available in your repository, it will be registered in the Azure Machine Learning model registry.

run_id (Run ID)

This action input defines the run, which created a model file with the name model_file_name (defined in the parameters file). The model file will be registered in the model registry in Azure Machine Learning by this action. If this input is not defined, the action will try to find a model file with the name model_file_name (defined in the parameters file) in your GitHub repository. If the model file is available in your repository, it will be registered in the Azure Machine Learning model registry.

parameters_file (Parameters File)

The action tries to load a JSON file in the .cloud/.azure folder in your repository, which specifies details for the model registration to your Azure Machine Learning Workspace. By default, the action is looking for a file with the name registermodel.json. If your JSON file has a different name, you can specify it with this parameter. Note that none of these values are required and in the absence, defaults will be used.

A sample file can be found in this repository in the folder .cloud/.azure. The JSON file can include the following parameters:

Please visit this website for more details.

Outputs

Other Azure Machine Learning Actions

• aml-workspace - Connects to or creates a new workspace
• aml-compute - Connects to or creates a new compute target in Azure Machine Learning
• aml-run - Submits a ScriptRun, an Estimator or a Pipeline to Azure Machine Learning
• aml-registermodel - Registers a model to Azure Machine Learning
• aml-deploy - Deploys a model and creates an endpoint for the model

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.