Skip to content

API Review Hub Onboarding

Jump to bottom
Travis Prescott edited this page Oct 15, 2026 · 8 revisions

Onboarding a Language to API Review Hub

Use this guide to connect an SDK language repository to API Review Hub (ARH), implement its artifact-generation templates, and test the integration.

Prerequisites

You need:

  • A fork or branch of the language repository.
  • A branch of Azure/azure-sdk-tools when the shared dispatcher or base templates must change.
  • Access to the azure-sdk-engineering-system GitHub organization.

1. Install the GitHub Apps

You only need to do this if working on a fork of a repo. If working on the Azure-owned repo, this should already be done for you.

Open the Azure SDK Engineering System GitHub App settings and install both apps in the repository:

  • API Review Hub coordinates API reviews and approval labels.
  • Azure SDK Automation performs repository actions for the review process.

For a Microsoft-owned repository, follow the GitHub App approval process. A fork owner can normally approve installation under Settings > GitHub Apps.

Contact trprescott@microsoft.com if approval or installation is blocked.

2. Register the Repository

Ask the ARH maintainers to register the repository. Provide:

  • Repository full name, such as Azure/azure-sdk-for-python.

  • GitHub repository ID:

    gh api repos/{OWNER}/{REPO} --jq .id

  • Approval inheritance policy:

    • Pre-release to pre-release (default: yes).
    • Patch update (default: yes).
    • Pre-release to stable (default: no).
    • Minor update (default: no).
    • Major update (default: no).

  • Review policy:

    • Data-plane first beta release (default: no).
    • Data-plane subsequent beta release (default: no).
    • Data-plane stable release (default: yes).
    • Management-plane first beta release (default: no).
    • Management-plane subsequent beta release (default: no).
    • Management-plane stable release (default: no).

As part of registration, the ARH maintainers update eng/pipelines/handle-apireview-hub-request.yml in Azure/azure-sdk-tools to:

  • Add the language to the language parameter values, if needed.
  • Add the language repository resource.

As a maintainer webhook check:

  1. Create or open an issue in the repository.
  2. Add sdk-api-review-approved.
  3. Confirm Azure SDK Automation removes the label and explains that ARH controls it.

If the check fails, the maintainers should verify both GitHub App installations, repository registration, and webhook delivery.

3. Add the ARCHITECTS File

ARH uses .github/ARCHITECTS to determine who may approve an API review. The file follows CODEOWNERS pattern syntax.

# Catch all SDK packages
/sdk/ @your-github-team-or-user

Commit the file to the repository's default branch. See the Python ARCHITECTS file for a larger example.

4. Implement the Pipeline Templates

ARH queues eng/pipelines/handle-apireview-hub-request.yml from Azure/azure-sdk-tools. The dispatcher builds a self-contained tooling artifact once, then runs independent base and target artifact-generation jobs. Each generation job clones only the requested package source ref and downloads the same bin artifact.

The language repository owns:

  1. One required build-tools wrapper that packages all required tooling and scripts into $(BinOutputDirectory).
  2. One required artifact-generation wrapper which will be used on the base and target refs.

The shared base templates own checkouts, artifact transfer, publishing, and ARH callbacks. Language templates must not duplicate that orchestration.

%%{init: {"flowchart": {"defaultRenderer": "elk"}}}%%
flowchart LR
    subgraph Build["Build Tools Job"]
        direction TB
        BT["apireview-hub-build-tools-{language}.yml"]
        BTB["apireview-hub-build-tools-base.yml"]
        BIN[("bin artifacts")]

        BT -->|"wraps and supplies<br/>build steps"| BTB
        BTB -->|"publishes"| BIN
    end

    subgraph Generate["Generate Artifacts Job"]
        direction TB
        AG["apireview-hub-generate-artifact-{language}.yml"]
        AGB["apireview-hub-generate-artifact-base.yml"]

        AG -->|"wraps and supplies<br/>generation steps"| AGB
    end

    BT --> AG
    BIN -->|"used by"| AGB

    classDef language fill:#0ea5e9,stroke:#075985,color:#ffffff
    classDef shared fill:#ea6a2a,stroke:#9a3412,color:#ffffff
    classDef artifact fill:#0e7490,stroke:#164e63,color:#ffffff
    class BT,AG language
    class BTB,AGB shared
    class BIN artifact
    style Build fill:transparent,stroke:#0070c0,stroke-width:3px
    style Generate fill:transparent,stroke:#3f7f35,stroke-width:3px
Loading

Build-tools wrapper

Create:

eng/pipelines/templates/jobs/apireview-hub-build-tools-{language}.yml

Declare and explicitly forward the shared parameters:

parameters:
  - name: languageRepoResource
    type: string
  - name: toolsRef
    type: string
  - name: languageToolsRef
    type: string

jobs:
  - template: /eng/common/pipelines/templates/jobs/apireview-hub-build-tools-base.yml
    parameters:
      languageRepoResource: ${{ parameters.languageRepoResource }}
      toolsRef: ${{ parameters.toolsRef }}
      languageToolsRef: ${{ parameters.languageToolsRef }}
      stepList:
        # Language-owned build steps.

Declare and forward any supported pool or image override in the same way.

The language-specific build steps have these directories available:

  • $(ToolsSourceDirectory): shared azure-sdk-tools/eng sources at toolsRef.
  • $(LanguageToolsSourceDirectory): language repository sources at languageToolsRef; also, an alias of $(Build.SourcesDirectory) and $(Pipeline.Workspace)/s.
  • $(BinOutputDirectory): destination for every script, binary, configuration file, and other tool required by generation jobs.

The custom stepList may install a runtime, restore dependencies, compile tools, or package tools. Copy all required tooling and script files into $(BinOutputDirectory); generation jobs cannot rely on either source checkout. Do not publish artifacts or write generated output outside $(BinOutputDirectory).

Refer to the Python implementation for guidance: https://github.com/Azure/azure-sdk-for-python/blob/main/eng/pipelines/templates/jobs/apireview-hub-build-tools-python.yml

Artifact-generation wrapper

Create:

eng/pipelines/templates/jobs/apireview-hub-generate-artifact-{language}.yml

For example, the Python wrapper declares and forwards:

parameters:
  - name: kind
    type: string
  - name: repositoryOwner
    type: string
    default: Azure
  - name: ref
    type: string
  - name: packageName
    type: string
  - name: operationId
    type: string

jobs:
  - template: /eng/common/pipelines/templates/jobs/apireview-hub-generate-artifact-base.yml
    parameters:
      kind: ${{ parameters.kind }}
      language: python
      repositoryFullName: ${{ format('{0}/{1}', parameters.repositoryOwner, 'azure-sdk-for-python') }}
      ref: ${{ parameters.ref }}
      packageName: ${{ parameters.packageName }}
      operationId: ${{ parameters.operationId }}
      stepList:
        # Language-owned generation steps.

Use your language's fixed language and repository names. Declare and forward any supported pool or image override in the same way.

The shared base template provides:

  • $(Build.SourcesDirectory): language source repository at the requested base or target ref.
  • $(BinDirectory): the self-contained tooling directory downloaded from the build-tools job.
  • $(ArtifactOutputDirectory): destination for the generated review bundle.

Generation steps must:

  1. Install or activate tooling from $(BinDirectory).
  2. Locate packageName under $(Build.SourcesDirectory).
  3. Build the package when required.
  4. Generate the API review files.
  5. Copy api.md, api.metadata.yml, and any additional supplemental files into $(ArtifactOutputDirectory).

Do not clone repositories, switch refs, check out tooling sources, download or publish pipeline artifacts, call ARH, or fetch a different tooling revision.

Refer to the Python implementation for guidance: https://github.com/Azure/azure-sdk-for-python/blob/main/eng/pipelines/templates/jobs/apireview-hub-generate-artifact-python.yml

5. Emit a Valid Review Bundle

Each base or target bundle must contain:

  • api.md: the generated API surface.
  • api.metadata.yml: metadata describing the package and API surface.

api.metadata.yml requires these non-empty fields:

apiHash: 607621e4437753200b71dcdcddaddcabeaf41944273a4600713b004471117189
packageVersion: 1.2.0
packageRelativePath: sdk/example/example-package
  • apiHash is calculated using the language's configured hash algorithm and input files, typically including at least api.md and optionally other files. ARH treats it as an opaque, non-empty string and persists it unchanged without recalculating or verifying it.
  • packageVersion is the version read from the checked-out package source.
  • packageRelativePath is the package path relative to $(Build.SourcesDirectory), using / separators.

Expose the same hash calculation for reuse during the release pipeline, using the same algorithm and input-file selection. A reusable script or template is recommended so artifact generation and release checks cannot drift.

Additional language-specific metadata, such as runtime or generator versions, is allowed. Supplemental review files may also be included in the bundle.

Place the complete bundle in $(ArtifactOutputDirectory); the shared template handles validation, publishing, and notifying ARH.

6. Test with Request-scoped Refs

Develop the dispatcher, shared templates, and language templates on branches.

Pass the development refs in the create-review request, most commonly using the AzSDK CLI:

  • pipelineRef: azure-sdk-tools ref containing the dispatcher to queue. Set environment variable: AZSDK_API_REVIEW_PIPELINE_REF
  • toolsRef: azure-sdk-tools ref containing shared tools and base templates. Set environment variable: AZSDK_API_REVIEW_TOOLS_REF
  • languageToolsRef: language repository ref containing its tools and wrappers. Set environment variable: AZSDK_API_REVIEW_LANGUAGE_TOOLS_REF

Any omitted ref defaults to main.

These refs are independent of the package source refs. baseTag and targetBranch.name select the package revisions; the three tooling refs select the pipeline and tooling used to generate both bundles.

Example request body:

{
  "language": "python",
  "packageName": "azure-keyvault-keys",
  "packageType": "client",
  "baseTag": "azure-keyvault-keys_4.10.0",
  "targetBranch": {
    "owner": "your-fork",
    "repo": "azure-sdk-for-python",
    "name": "feature/api-change"
  },
  "pipelineRef": "feature/arh-language-onboarding",
  "toolsRef": "feature/arh-language-onboarding",
  "languageToolsRef": "feature/arh-language-onboarding"
}

Use the equivalent options when invoking azsdk api-review create directly or through the Azure SDK CLI. Confirm that the proposed command includes the three development refs before approving it.

For an existing package, packageType may be omitted. A new package must provide it. If supplied for an existing package, it must match the registered value.

7. Verify the End-to-end Flow

Request a review using the development refs from Step 6 and confirm that ARH successfully creates the review pull request with the expected API changes. If it fails, share the operation ID with the ARH maintainers.

8. Merge and Retest from main

Merge the language-repository templates and any required azure-sdk-tools dispatcher or base-template changes. Then repeat the create-review test without pipelineRef, toolsRef, or languageToolsRef; all three default to main.

No shared configuration change or temporary dispatcher edit needs to be reverted.

9. Integrate the Release Gate

Update the language repository's release pipeline to submit the package name, version, and generated apiHash to the ARH release check before publishing a release that requires API approval. Coordinate this step with the ARH maintainers until the language-specific release integration is documented.

Clone this wiki locally