Skip to content

Commit a359bd8

Browse files
v-albemiv-albemi
authored
Merge pull request #100836 from jpconnock/github-action
First draft of new GitHub Actions
2 parents 066033c + a8ca255 commit a359bd8

File tree

4 files changed

+199
-0
lines changed

4 files changed

+199
-0
lines changed

‎articles/azure-app-configuration/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@
6363
href: concept-point-time-snapshot.md
6464
- name: Feature management
6565
href: concept-feature-management.md
66+
- name: Sync using GitHub Actions
67+
href: concept-github-action.md
6668
- name: Event handling
6769
href: concept-app-configuration-event.md
6870
- name: High availability

‎articles/azure-app-configuration/concept-github-action.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Use GitHub Actions with Azure App Configuration Sync
3+
description: Use GitHub Actions to trigger an update to your App Configuration instance when defined actions are performed on a GitHub repository
4+
author: jpconnock
5+
6+
ms.author: jeconnoc
7+
ms.date: 01/14/2020
8+
ms.topic: conceptual
9+
ms.service: azure-app-configuration
10+
11+
---
12+
# Sync your App Configuration Instance using GitHub Actions
13+
Azure App Configuration uses GitHub Actions to update an App Configuration instance when triggered by an action performed on a GitHub repository. You can leverage GitHub workflows to update app configuration, enabling the integration of app configuration updates into the same workflow used to update app code.
14+
15+
A GitHub Actions [workflow](https://help.github.com/articles/about-github-actions#workflow) is an automated process defined in your GitHub repository. This process tells GitHub how to build and deploy your GitHub project. Azure App Configuration provides the *Azure App Configuration Sync* Action to enable updates to an App Configuration instance when changes are made to the source repository.
16+
17+
A workflow is defined by a YAML (.yml) file found in the `/.github/workflows/` path of your repository. This definition contains the various steps and parameters that define the workflow.
18+
19+
GitHub events, such as a push to a repository, can trigger a GitHub Action workflow. Azure provides the *Azure App Configuration Sync* action to enable you to trigger an update of an App Configuration instance when a specified GitHub action occurs. This allows teams to leverage GitHub's core features when pushing, reviewing, or branching app configuration files just as they do with app code.
20+
21+
The GitHub [documentation](https://help.github.com/actions/automating-your-workflow-with-github-actions/configuring-a-workflow) provides in-depth view of GitHub workflows and actions.
22+
23+
## Enable GitHub Actions in your repository
24+
To start using this GitHub action, go to your repository and select the **Actions** tab. Find and select the GitHub action in the marketplace by searching for "Azure App Configuration Sync".
25+
26+
> [!div class="mx-imgBorder"]
27+
> ![Select the Action tab](media/find-github-action.png)
28+
29+
> [!div class="mx-imgBorder"]
30+
> ![Select the app configuration syn Action](media/app-configuration-sync-action.png)
31+
32+
## Sync configuration files after a push
33+
This action syncs Azure App Configuration files when a change is pushed to `appsettings.json`. When a developer makes and pushes a change to `appsettings.json`, the App Configuration Sync action updates the App Configuration instance with the new values.
34+
35+
The first section of this workflow specifies that the action triggers *on* a *push* containing `appsettings.json` to the *master* branch. The second section lists the jobs run once the action is triggered. The action checks out the relevant files and updates the App Configuration instance using the connection string stored as a secret in the repository. For more information about using secrets in Github, see [this article](https://help.github.com/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets) about creating and using encrypted secrets.
36+
37+
```json
38+
on:
39+
push:
40+
branches:
41+
- 'master'
42+
paths:
43+
- 'appsettings.json'
44+
45+
jobs:
46+
syncconfig:
47+
runs-on: ubuntu-latest
48+
steps:
49+
# checkout done so that files in the repo can be read by the sync
50+
- uses: actions/checkout@v1
51+
- uses: azure/appconfiguration-sync@v1
52+
with:
53+
configurationFile: 'appsettings.json'
54+
format: 'json'
55+
# Replace <ConnectionString> with the name of the secret in your
56+
# repository
57+
connectionString: ${{ secrets.<ConnectionString> }}
58+
separator: ':'
59+
```
60+
61+
## Use a dynamic label on sync
62+
The previous action simply updated the App Configuration instance whenever `appsettings.json` is updated. This action inserts a dynamic label on each sync, ensuring that each sync can be uniquely identified. This allows code changes to quickly be mapped to config changes.
63+
64+
The first section of this workflow specifies that the action triggers *on* a *push* containing `appsettings.json` to the *master* branch. The second section runs a job which creates a unique label for the config update based on the commit hash. The job then updates the App Configuration instance with the new values and the unique label for this update.
65+
66+
```json
67+
on:
68+
push:
69+
branches:
70+
- 'master'
71+
paths:
72+
- 'appsettings.json'
73+
74+
jobs:
75+
syncconfig:
76+
runs-on: ubuntu-latest
77+
steps:
78+
# Creates a label based on the branch name and the first 8 characters
79+
# of the commit hash
80+
- id: determine_label
81+
run: echo ::set-output name=LABEL::"${GITHUB_REF#refs/*/}/${GITHUB_SHA:0:8}"
82+
# checkout done so that files in the repo can be read by the sync
83+
- uses: actions/checkout@v1
84+
- uses: azure/appconfiguration-sync@v1
85+
with:
86+
configurationFile: 'appsettings.json'
87+
format: 'json'
88+
# Replace <ConnectionString> with the name of the secret in your
89+
# repository
90+
connectionString: ${{ secrets.<ConnectionString> }}
91+
separator: ':'
92+
label: ${{ steps.determine_label.outputs.LABEL }}
93+
```
94+
95+
## Use strict sync
96+
When strict mode is enabled, the sync ensures that the App Configuration instance matches the configuration file for the given prefix and label exactly. Key-value pairs with the same prefix and label that are not in the configuration file are deleted.
97+
98+
If strict mode is not enabled, the sync will only set key-values from the configuration file. No key-value pairs will be deleted.
99+
100+
```json
101+
on:
102+
push:
103+
branches:
104+
- 'master'
105+
paths:
106+
- 'appsettings.json'
107+
108+
jobs:
109+
syncconfig:
110+
runs-on: ubuntu-latest
111+
steps:
112+
# checkout done so that files in the repo can be read by the sync
113+
- uses: actions/checkout@v1
114+
- uses: azure/appconfiguration-sync@v1
115+
with:
116+
configurationFile: 'appsettings.json'
117+
format: 'json'
118+
# Replace <ConnectionString> with the name of the secret in your
119+
# repository
120+
connectionString: ${{ secrets.<ConnectionString> }}
121+
separator: ':'
122+
label: 'Label'
123+
prefix: 'Prefix:'
124+
strict: true
125+
```
126+
127+
## Use max depth to limit GitHub Action
128+
The default behavior for nested JSON attributes is to flatten the entire object. The JSON below defines this key-value pair:
129+
130+
| Key | Value |
131+
| --- | --- |
132+
| Object:Inner:InnerKey | InnerValue |
133+
134+
```json
135+
{ "Object":
136+
{ "Inner":
137+
{
138+
"InnerKey": "InnerValue"
139+
}
140+
}
141+
}
142+
```
143+
If the nested object is intended to be the value pushed to the Configuration instance, you can use the *depth* value to stop the flattening at the appropriate depth.
144+
145+
```json
146+
on:
147+
push:
148+
branches:
149+
- 'master'
150+
paths:
151+
- 'appsettings.json'
152+
153+
jobs:
154+
syncconfig:
155+
runs-on: ubuntu-latest
156+
steps:
157+
# checkout done so that files in the repo can be read by the sync
158+
- uses: actions/checkout@v1
159+
- uses: azure/appconfiguration-sync@v1
160+
with:
161+
configurationFile: 'appsettings.json'
162+
format: 'json'
163+
# Replace <ConnectionString> with the name of the secret in your
164+
# repository
165+
connectionString: ${{ secrets.<ConnectionString> }}
166+
separator: ':'
167+
depth: 2
168+
```
169+
170+
Given a depth of 2, the example above now returns the following key:value pair:
171+
172+
| Key | Value |
173+
| --- | --- |
174+
| Object:Inner | {"InnerKey":"InnerValue"} |
175+
176+
## Understand Action Inputs
177+
Input parameters specify data used by the action during runtime. The following table contains input parameters accepted by App Configuration Sync and the expected values for each. For more information about action inputs for GitHub Actions, see GitHub's [documentation](https://help.github.com/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions#inputs).
178+
179+
> [!Note]
180+
> Input IDs are case insensitive.
181+
182+
183+
| Input Name | Required? | Value |
184+
|----|----|----|
185+
| configurationFile | Yes | Path to the configuration file in the repository, relative to the root of the repository. Glob patterns are supported and can include multiple files. |
186+
| format | Yes | File format of the configuration file. Valid formats are: JSON, YAML, properties. |
187+
| connectionString | Yes | Connection string for the App Configuration instance. The connection string should be stored as a secret in the GitHub repository, and only the secret name should be used in the workflow. |
188+
| separator | Yes | Separator used when flattening the configuration file to key-value pairs. Valid values are: . , ; : - _ __ / |
189+
| prefix | No | Prefix to be added to the start of keys. |
190+
| label | No | Label used when setting key-value pairs. If unspecified, a null label is used. |
191+
| strict | No | A boolean value that determines whether strict mode is enabled. The default value is false. |
192+
| depth | No | Max depth for flattening the configuration file. Depth must be a positive number. The default will have no max depth. |
193+
| tags | No | Specifies the tag set on key-value pairs. The expected format is a stringified form of a JSON object of the following shape: { [propertyName: string]: string; } Each property name-value becomes a tag. |
194+
195+
## Next steps
196+
197+
In this article, you learned about the App Configuration Sync GitHub Action and how it can be used to automate updates to your App Configuration instance. To learn how Azure App Configuration reacts to changes in key-value pairs, continue to the next [article](./concept-app-configuration-event.md).

‎articles/azure-app-configuration/media/app-configuration-sync-action.png

54.3 KB
Loading

‎articles/azure-app-configuration/media/find-github-action.png

25 KB
Loading

0 commit comments

Comments
 (0)