将 GitHub 存储库同步到应用程序配置Sync your GitHub repository to App Configuration

如果团队要继续使用自己现有的源代码管理做法,可以使用 GitHub Actions 自动将自己的 GitHub 存储库与其应用程序配置存储同步。Teams that want to continue using their existing source control practices can use GitHub Actions to automatically sync their GitHub repository with their App Configuration store. 这样,可以照常对配置文件进行更改,同时获得应用程序配置优势,比如:This allows you to make changes to your config files as you normally would, while getting App Configuration benefits like:
    • 在代码之外集中配置    • Centralized configuration outside of your code
    • 更新配置,而无需重新部署整个应用    • Updating configuration without redeploying your entire app
    • 与 Azure 应用服务和 Azure Functions 等服务集成。    • Integration with services like Azure App Service and Functions.

GitHub Actions 工作流在 GitHub 存储库中定义自动化流程。A GitHub Actions workflow defines an automated process in a GitHub repository. “Azure 应用程序配置同步”操作在源存储库有更改后,触发更新应用程序配置实例。The Azure App Configuration Sync Action triggers updates to an App Configuration instance when changes are made to the source repository. 它使用存储库的 /.github/workflows/ 路径中的 YAML (.yml) 文件来定义步骤和参数。It uses a YAML (.yml) file found in the /.github/workflows/ path of your repository to define the steps and parameters. 可以在推送、审阅应用程序配置文件或设置其分支后触发配置更新,就像对应用代码所做的那样。You can trigger configuration updates when pushing, reviewing, or branching app configuration files just as you do with app code.

若要深入了解 GitHub 工作流和操作,请参阅这篇 GitHub 文档The GitHub documentation provides in-depth view of GitHub workflows and actions.

在存储库中启用 GitHub ActionsEnable GitHub Actions in your repository

若要开始使用此 GitHub 操作,请转到存储库,然后选择“操作”选项卡。选择“新建工作流”,然后“自己设置工作流” 。To start using this GitHub action, go to your repository and select the Actions tab. Select New workflow, then Set up a workflow yourself. 最后,在市场中搜索“Azure 应用程序配置同步”。Finally, search the marketplace for “Azure App Configuration Sync.”

选择“操作”选项卡Select the Action tab

选择“应用程序配置同步”操作Select the app configuration sync Action

在推送后同步配置文件Sync configuration files after a push

此操作在有更改推送到 appsettings.json 后同步 Azure 应用程序配置文件。This action syncs Azure App Configuration files when a change is pushed to appsettings.json. 在开发人员将更改推送到 appsettings.json 后,“应用程序配置同步”操作使用新值来更新应用程序配置实例。When a developer pushes a change to appsettings.json, the App Configuration Sync action updates the App Configuration instance with the new values.

此工作流的第一部分指定这一操作在包含 appsettings.json 的推送推送到主分支后触发 。The first section of this workflow specifies that the action triggers on a push containing appsettings.json to the main 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. 若要详细了解如何在 GitHub 中使用机密,请参阅这篇关于如何创建和使用加密机密的 GitHub 文章For more information about using secrets in GitHub, see GitHub's article about creating and using encrypted secrets.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your                        
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }} 
          separator: ':' 

使用严格同步Use strict sync

默认情况下,GitHub 操作没有启用严格模式;也就是说,同步只会将配置文件中的键值添加到应用程序配置实例(而不会删除键值对)。By default the GitHub action does not enable strict mode, meaning that the sync will only add key-values from the configuration file to the App Configuration instance (no key-value pairs will be deleted). 启用严格模式意味着,从应用程序配置实例中删除配置文件中没有的键值对,以便与配置文件保持一致。Enabling strict mode will mean key-value pairs that aren't in the configuration file are deleted from the App Configuration instance, so that it matches the configuration file. 若要从多个源进行同步,或结合使用 Azure Key Vault 与应用程序配置,不妨使用不同的前缀或标签来进行严格同步,以免擦除掉其他文件的中配置设置(见下面的示例)。If you are syncing from multiple sources or using Azure Key Vault with App Configuration, you'll want to use different prefixes or labels with strict sync to avoid wiping out configuration settings from other files (see samples below).

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          label: 'Label' 
          prefix: 'Prefix:' 
          strict: true 

在一个操作中同步多个文件Sync multiple files in one action

如果配置位于多个文件中,可以使用下面的模式,以在任何一个文件被修改时触发同步。If your configuration is in multiple files, you can use the pattern below to trigger a sync when either file is modified. 此模式使用 glob 库 https://www.npmjs.com/package/globThis pattern uses the glob library https://www.npmjs.com/package/glob . 请注意,如果你的配置文件名称包含逗号,则可以使用反斜杠来转义逗号。Note that if your config file name contains a comma, you can use a backslash to escape the comma.

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'
      - 'appsettings2.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: '{appsettings.json,appsettings2.json}'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'

按前缀或标签同步Sync by prefix or label

如果在同步操作中指定前缀或标签,则只会同步特定集。Specifying prefixes or labels in your sync action will sync only that particular set. 这对于对多个文件使用严格同步非常重要。This is important for using strict sync with multiple files. 根据配置的设置方式,可以将前缀或标签与每个文件关联,然后可以分别同步每个前缀或标签,这样就不会覆盖任何内容。Depending on how the configuration is set up, either a prefix or a label can be associated with each file and then each prefix or label can be synced separately so that nothing is overwritten. 通常,前缀用于不同的应用程序或服务,标签用于不同的环境。Typically prefixes are used for different applications or services and labels are used for different environments.

按前缀同步:Sync by prefix:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          prefix: 'Prefix::'

按标签同步:Sync by label:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          label: 'Label'

使用动态标签同步Use a dynamic label on sync

下面的操作在每个同步中插入一个动态标签,以确保每个同步都能被唯一标识,并可便于代码更改映射到配置更改。The following action inserts a dynamic label on each sync, ensuring that each sync can be uniquely identified and allowing code changes to be mapped to config changes.

此工作流的第一部分指定这一操作在包含 appsettings.json 的推送推送到主分支后触发 。The first section of this workflow specifies that the action triggers on a push containing appsettings.json to the main branch. 第二部分运行作业,以根据提交哈希为配置更新创建唯一标签。The second section runs a job that 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.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # Creates a label based on the branch name and the first 8 characters          
      # of the commit hash 
      - id: determine_label 
        run: echo ::set-output name=LABEL::"${GITHUB_REF#refs/*/}/${GITHUB_SHA:0:8}" 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          label: ${{ steps.determine_label.outputs.LABEL }} 

结合使用 Azure Key Vault 与 GitHub 操作Use Azure Key Vault with GitHub Action

如果结合使用 Azure Key Vault 与 AppConfiguration,开发人员应使用两个单独的文件,它们通常是 appsettings.json 和 secretreferences.json。Developers using Azure Key Vault with AppConfiguration should use two separate files, typically an appsettings.json and a secretreferences.json. secretreferences.json 包含密钥保管库机密的 URL。The secretreferences.json will contain the url to the key vault secret.

{ "mySecret": "{"uri":"https://myKeyVault.vault.azure.cn/secrets/mySecret"}" }{ "mySecret": "{"uri":"https://myKeyVault.vault.azure.cn/secrets/mySecret"}" }

然后,可以将 GitHub 操作配置为,对 appsettings.json 执行严格同步,随后对 secretreferences.json 执行非严格同步。The GitHub Action can then be configured to do a strict sync on the appsettings.json, followed by a non-strict sync on secretreferences.json. 下面的示例在任何一个文件更新时触发同步:The following sample will trigger a sync when either file is updated:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'
      - 'secretreferences.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          strict: true
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'secretreferences.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          contentType: 'application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8'

使用最大深度限制 GitHub 操作Use max depth to limit GitHub Action

嵌套 JSON 特性的默认行为是平展整个对象。The default behavior for nested JSON attributes is to flatten the entire object. 下面的 JSON 定义了此键值对:The JSON below defines this key-value pair:

密钥Key Value
Object:Inner:InnerKeyObject:Inner:InnerKey InnerValueInnerValue
{ "Object": 
    { "Inner":
        {
        "InnerKey": "InnerValue"
        }
    }
}

若要将嵌套对象作为推送到配置实例的值,可以使用 depth 值在适当的深度处停止平展。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.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          depth: 2 

假设 depth 值为 2,上面的示例现在返回以下键值对:Given a depth of 2, the example above now returns the following key-value pair:

密钥Key Value
Object:InnerObject:Inner {"InnerKey":"InnerValue"}{"InnerKey":"InnerValue"}

了解操作输入Understand action inputs

输入参数指定了操作在运行时期间使用的数据。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. 若要详细了解 GitHub Actions 操作输入,请参阅这篇 GitHub 文档For more information about action inputs for GitHub Actions, see GitHub's documentation.

备注

输入 ID 不区分大小写。Input IDs are case insensitive.

输入名称Input name 必需?Required? Value
configurationFileconfigurationFile Yes 存储库中配置文件的相对路径。Relative path to the configuration file in the repository. glob 模式受支持,并且可以包含多个文件。Glob patterns are supported and can include multiple files.
formatformat Yes 配置文件的文件格式。File format of the configuration file. 有效格式为:JSON、YAML、属性。Valid formats are: JSON, YAML, properties.
connectionStringconnectionString Yes 应用程序配置实例的连接字符串。Connection string for the App Configuration instance. 连接字符串应作为机密存储在 GitHub 存储库中,并且只有机密名称才能在工作流中使用。The connection string should be stored as a secret in the GitHub repository, and only the secret name should be used in the workflow.
separatorseparator Yes 将配置文件平展为键值对时使用的分隔符。Separator used when flattening the configuration file to key-value pairs. 有效值为:.Valid values are: . , ; : - _ __ /, ; : - _ __ /
前缀prefix No 要添加到键的开头的前缀。Prefix to be added to the start of keys.
labellabel No 设置键值对时使用的标签。Label used when setting key-value pairs. 如果没有指定,则使用 null 标签。If unspecified, a null label is used.
strictstrict No 确定是否启用严格模式的布尔值。A boolean value that determines whether strict mode is enabled. 默认值是 False。The default value is false.
depthdepth No 平展配置文件的最大深度。Max depth for flattening the configuration file. depth 必须为正数。Depth must be a positive number. 默认没有最大深度。The default will have no max depth.
标记tags No 指定在键值对上设置的标记。Specifies the tag set on key-value pairs. 格式应为以下形状的 JSON 对象的字符串化形式:{ [propertyName: string]: string; }。每个属性名/值对都变成一个标记。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.

后续步骤Next steps

在本文中,你学习了 GitHub 操作“应用程序配置同步”,以及如何使用此操作来自动更新应用程序配置实例。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. 若要了解 Azure 应用程序配置如何响应键值对更改,请继续阅读下一篇文章To learn how Azure App Configuration reacts to changes in key-value pairs, continue to the next article.