Skip to content

Commit ace8a58

Browse files
dlepowdlepow
committed
wip
1 parent b9c5e06 commit ace8a58

File tree

4 files changed

+159
-39
lines changed

4 files changed

+159
-39
lines changed

‎.github/workflows/register-api.yml

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Register API Definition to Azure API Center
2+
on:
3+
workflow_dispatch:
4+
5+
permissions:
6+
id-token: write
7+
contents: read
8+
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
# Please configure the environment name required in federated identity credential
13+
# https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment
14+
environment: production
15+
steps:
16+
- uses: actions/checkout@v2
17+
18+
# https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure
19+
# https://github.com/marketplace/actions/azure-login#login-with-openid-connect-oidc-recommended
20+
- name: Azure login
21+
uses: azure/login@v1
22+
with:
23+
client-id: ${{ secrets.AZURE_CLIENT_ID }}
24+
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
25+
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
26+
enable-AzPSSession: true
27+
28+
# Please create following environment variables to deploy to azure resource: RESOURCE_GROUP, RESOURCE_NAME, FILE_LOCATION
29+
# RESOURCE_GROUP: Azure Resource Group name, please ensure the resource group already created.
30+
# RESOURCE_NAME: Azure API Center resource name, please ensure the API Center resource already created.
31+
# FILE_LOCATION: API Definition file location
32+
# https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository
33+
- name: Deploy to API Center
34+
uses: azure/CLI@v2
35+
with:
36+
azcliversion: latest
37+
inlineScript: |
38+
az apic api register -g ${{ vars.RESOURCE_GROUP }} -s ${{ vars.RESOURCE_NAME }} --api-location ${{ vars.FILE_LOCATION }}

‎articles/api-center/media/register-apis-github-actions/api-registered-api-center.png

61.4 KB
Loading

‎articles/api-center/media/register-apis-github-actions/workflow-action.png

92.5 KB
Loading

‎articles/api-center/register-apis-github-actions.md

Lines changed: 121 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
title: Register APIs using GitHub Actions - Azure API Center
3-
description: TBD...
3+
description: Learn how to automate the registration of APIs in your API center using a CI/CD workflow based on GitHub Actions.
44
ms.service: api-center
55
ms.topic: how-to
6-
ms.date: 07/18/2024
6+
ms.date: 07/19/2024
77
ms.author: danlep
88
author: dlepow
99
ms.custom: devx-track-azurecli
@@ -12,10 +12,10 @@ ms.custom: devx-track-azurecli
1212

1313
# Register APIs in your API center using GitHub Actions
1414

15-
This article shows how to set up a GitHub Actions workflow to register APIs in your organization's [API center](overview.md). [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions) is ...
15+
This article shows how to set up a basic GitHub Actions workflow to register an API in your organization's [API center](overview.md) when an API specification file is added to a GitHub repository. [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions) is a CI/CD platform that automates software workflows, enabling you to build, test, and deploy your code right from GitHub.
1616

1717

18-
General configuration steps are similar to those in [Deploy to App Service using GitHub Actions](../app-service/deploy-github-actions).
18+
General configuration steps are similar to those in [Deploy to App Service using GitHub Actions](../app-service/deploy-github-actions), which provides more detail.
1919

2020
**Benefits of using GitHub Actions to register APIs in your API center:**
2121
* Save time and reduces manual effort
@@ -28,53 +28,52 @@ GitHub Actions provides:
2828

2929

3030
<!-- Add Video link? -->
31+
## Prerequisites
3132

32-
## Scenario overview
33+
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
34+
* Permissions to create a service principal in the tenant
35+
* A GitHub account and a GitHub repo in which you can configure secrets and GitHub Actions workflows
36+
* For Azure CLI:
37+
[!INCLUDE [include](~/reusable-content/azure-cli/azure-cli-prepare-your-environment-no-header.md)]
3338

34-
In this scenario, you ...
35-
The following diagram shows the steps to register APIs in your API center using GitHub Actions.
39+
[!INCLUDE [install-apic-extension](includes/install-apic-extension.md)]
3640

41+
> [!NOTE]
42+
> Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.
3743
44+
## Scenario overview
45+
46+
The following diagram shows how API registration in your API center can be automated using GitHub Actions.
3847

3948
:::image type="content" source="media/register-apis-github-actions/scenario-overview.svg" alt-text="Diagram showing a GitHub actions workflow to register API in an Azure API center.":::
4049

41-
<!-- Explain steps here -->
4250

43-
1. Set up a GitHub Actions workflow in your repository.
51+
1. Set up a GitHub Actions workflow in your repository that triggers when a pull request that adds an API definition file is merged.
4452
1. Create a branch from the main branch in your GitHub repository.
45-
1. Commit changes and push them to the new branch.
53+
1. Add an API definition file, commit the changes, and push them to the new branch.
4654
1. Create a pull request to merge the new branch into the main branch.
4755
1. Merge the pull request.
4856
1. The merge triggers a GitHub Actions workflow that registers the APIs in your API center.
4957

50-
51-
## Prerequisites
52-
53-
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
54-
* Permissions to create a service principal in the tenant (--check--)
55-
* A GitHub account and a GitHub repo
56-
* For Azure CLI:
57-
[!INCLUDE [include](~/reusable-content/azure-cli/azure-cli-prepare-your-environment-no-header.md)]
58-
59-
[!INCLUDE [install-apic-extension](includes/install-apic-extension.md)]
60-
61-
> [!NOTE]
62-
> Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.
63-
6458
## Set up a GitHub Actions workflow
6559

60+
In this section, you set up the GitHub Actions workflow for this scenario:
6661

62+
* Create an Azure service principal to use for configuring credentials for the GitHub Actions workflow.
63+
* Add the credentials as a secret in your GitHub repository.
64+
* Configure a GitHub Actions workflow that triggers when a pull request adding an API definition file is merged. The workflow YAML file includes a step that uses the Azure CLI to register the API in your API center from the definition file.
6765

6866

69-
### Set up the Azure login action with a service principal secret
70-
71-
See [steps](../app-service/deploy-github-actions?tabs=openid%2Caspnetcore#1-generate-deployment-credentials) to generate deployment credentials for your repository.
67+
### Set up a service principal secret
7268

69+
In the following steps, create a Microsoft Entra service principal to use for configuring credentials for the GitHub Actions workflow. The service principal is used to authenticate with Azure to register the API.
7370

7471
> [!NOTE]
75-
> he recommended way to authenticate with Azure API Center for GitHub Actions is with OpenID Connect. This is an authentication method that uses short-lived tokens. Setting up OpenID Connect with GitHub Actions is more complex but offers hardened security.
72+
> Configuring a service principal is shown for demonstration purposes. The recommended way to authenticate with Azure for GitHub Actions is with OpenID Connect, an authentication method that uses short-lived tokens. Setting up OpenID Connect with GitHub Actions is more complex but offers hardened security. See [steps](../app-service/deploy-github-actions?tabs=openid%2Caspnetcore#1-generate-deployment-credentials).
73+
74+
Create a service principal using the [az ad sp create-for-rbac](/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) command. The following example first uses the [az apic show](/cli/azure/az/apic#az-apic-show) command to retrieve the resource ID of the API center. The service principal is then created with the Contributor role for the API center.
7675

77-
For example, create a service principal using the [az ad sp create-for-rbac](/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) command:
76+
```bash
7877

7978
```azurecli
8079
apiCenter=<api-center-name>
@@ -87,7 +86,7 @@ az ad sp create-for-rbac --name $spName --role Contributor --scopes $apicResourc
8786
8887
```
8988

90-
Copy the JSON output to a secure location. The output should look similar to the following:
89+
Copy the JSON output, which should look similar to the following:
9190

9291
```json
9392
{
@@ -107,29 +106,112 @@ Copy the JSON output to a secure location. The output should look similar to the
107106

108107
### Add the workflow file to your GitHub repository
109108

110-
# Please create following environment variables to deploy to azure resource: RESOURCE_GROUP, SERVICE_NAME, FILE_LOCATION
111-
# RESOURCE_GROUP: Azure Resource Group name, please ensure the resource group already created.
112-
# SERVICE_NAME: Azure API Center resource name, please ensure the API Center resource already created.
113-
# FILE_LOCATION: API Definition file location
114-
# https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository
109+
A GitHub Actions workflow is represented by a YAML (.yml) definition file. This definition contains the various steps and parameters that make up the workflow. [Learn more](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
115110

116-
```yml
111+
The following is a basic workflow file for this example that you can use or modify.
112+
113+
In this example:
114+
* the workflow is triggered when a pull request that adds a specified JSON definition is closed on the main branch
115+
* The Azure credentials saved in your repo are used to sign into the Azure CLI
116+
* The [az apic register](/cli/azure/apic/api#az-apic-api-register) command registers the API in the API center specified in the environment variables
117+
118+
To configure the workflow file:
119+
120+
1. Copy and save the file under a name such as `register-api.yml`.
121+
1. Update the values for the environment variables to match your API center in Azure.
122+
1. Update the expected path where you'll add the definition file in the repository.
123+
1. Add this file in the `/.github/workflows/` path in your GitHub repository.
117124
125+
> [!TIP]
126+
> If you use the [Visual Studio Code extension](use-vscode-extension.md) for Azure API Center, you can create a starting workflow file from the extension which you can then modify for your scenario. In the Command Palette, select **Azure API Center: Register APIs**. Select **CI/CD** > **GitHub**.
118127
128+
```yml
129+
name: Register API Definition to Azure API Center
130+
on:
131+
pull_request:
132+
types: [closed]
133+
branches:
134+
- main
135+
136+
permissions:
137+
id-token: write
138+
contents: read
139+
140+
env:
141+
# Set this to your Azure API Center resource group name
142+
RESOURCE_GROUP: <YOUR_RESOURCE_GROUP>
143+
# Set this to your Azure API Center service name
144+
SERVICE_NAME: <YOUR_API_CENTER>
145+
# Set this to the location of your API definition file
146+
# Example: ./APIs/catfacts-api/07-15-2024.json
147+
API_FILE_LOCATION: <YOUR_PATH_TO_API_DEFINITION>
148+
149+
jobs:
150+
register:
151+
runs-on: ubuntu-latest
152+
environment: production
153+
steps:
154+
- uses: actions/checkout@v2
155+
- name: Azure login
156+
uses: azure/login@v1
157+
with:
158+
creds: ${{ secrets.AZURE_CREDENTIALS }}
159+
160+
- name: Register to API Center
161+
uses: azure/CLI@v2
162+
with:
163+
azcliversion: latest
164+
inlineScript: |
165+
az apic api register -g ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}
119166
```
120167
121168
169+
## Add API definition file to the repository
170+
171+
Test the workflow by adding an API definition file to the repository. Follow these high-level steps, which are typical of a development workflow. For details on working with GitHub branches, see the [GitHub documentation](https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models).
172+
173+
1. Create a new branch from the main branch in your repository.
174+
1. Add the API definition file to the repository at the path specified in the workflow file (for example, `./APIs/catfacts-api/07-15-2024.json`).
175+
1. Commit the changes and push them to the new branch.
176+
1. Create a pull request to merge the new branch into the main branch.
177+
1. After review, merge the pull request. The merge triggers the GitHub Actions workflow that registers the API in your API center.
178+
179+
:::image type="content" source="media/register-apis-github-actions/workflow-action.png" alt-text="Screenshot showing successful workflow run in GitHub.":::
122180
123-
## Add API specification to the repository
181+
## Verify the API registration
124182
183+
Verify that the API is registered in your API center.
125184
185+
1. In the [Azure portal](https://portal.azure.com), navigate to your API center.
186+
1. In the left menu, under **Assets**, select **APIs**.
187+
1. The newly registered API should appear in the list of APIs.
126188
127189
190+
:::image type="content" source="media/register-apis-github-actions/api-registered-api-center.png" alt-text="Screenshot of API registered in API Center after workflow.":::
191+
192+
## Extend the scenario
193+
194+
The following sections provide suggestions for extending the scenario to meet your specific requirements.
195+
196+
## Add a new version to existing API
197+
198+
To add a new API version to an API that's already registered in your API center:
199+
200+
1. Update the workflow file to specify the new API definition file at an existing path in the repository. Example: `./APIs/catfacts-api/07-16-2024.json`.
201+
1. Change to your existing working branch in the repository.
202+
1. Add the new API definition file to the repository at the specified path.
203+
1. Follow typical steps to create a pull request to merge the changes into the main branch, and merge the pull request.
204+
1. The GitHub Actions workflow triggers and registers the new API version in the existing API in your API center.
205+
206+
207+
## Add metadata to the API registration
208+
209+
You can add metadata for the API registration, defined using the [metadata schema](metadata.md) in your API center. For example
210+
128211

129212

130213

131214
## Related content
132215

133216
* [Using secrets in a GitHub Actions](https://docs.github.com/en/actions/reference/encrypted-secrets)
134-
135-
<!-- TBD- >
217+
* [Creating configuration variables for a repository](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

0 commit comments

Comments
 (0)