Eng workflows sync and branch cleanup additions (#6061)

2023-05-04 15:20:53 -07:00 · 2023-05-04 15:20:53 -07:00 · c971ac6c1c
--- a/doc/workflows/engsys_workflows.md
+++ b/doc/workflows/engsys_workflows.md
@ -0,0 +1,30 @@
+# Engineering System Workflows
+
+The `.github/workflows` directory contains the common GitHub actions and scheduled events yml files used in azure-sdk, azure-sdk-tools and the azure-sdk languages repositories. It should only contain YML files.
+
+## Updating
+
+Any updates to files in the `.github/workflows` directory should be made in the [azure-sdk-tools](https://github.com/azure/azure-sdk-tools) repo.
+All changes made will cause a PR to be created in all subscribed azure-sdk language repos which will blindly replace all contents of the `.github/workflows` directory in that repo. For that reason do **NOT** make changes to files in this directory in the azure-sdk or individual azure-sdk languages repos as they will be overwritten the next time an update is taken from the common `.github/workflows` in the azure-sdk-tools repo.
+
+## Workflow
+
+When you create a PR against `azure-sdk-tools` repo that changes contents of the `.github/workflows` directory, the PR
+triggers an [`azure-sdk-tools - sync - eng-workflows` pipeline][pipeline] that will mirror all changes in the `azure-sdk-tools .github/workflows` directory to the corresponding `.github/workflows` dirs in the language repositories. The pipeline also triggers language-repository-specific tests for you to review. This process of mirroring involves multiple stages and requires your manual reviews & approvals before the changes are fully reflected to the language repositories. Your approval is needed first to allow automatic creation of PRs, then to allow them being merged on your behalf.
+
+This process is set up in such a way to make it easier for changes to be tested in azure-sdk and each individual language repo before merging the changes in the `azure-sdk-tools` repo. The workflow is explained below:
+
+1. You create a PR (let's call it here the **Tools PR**) in the `azure-sdk-tools` repo with changes to the `.github/workflows` directory.
+2. The [`azure-sdk-tools - sync - eng-workflows` pipeline][pipeline] is automatically triggered for the **Tools PR**.
+3. That pipeline creates branches mirroring your changes, one branch in azure-sdk and one per each language repository to whose `.github/workflows` dir the changes are mirrored. You can use these branches to run your tests on these repos. The pipeline also queues test runs for template pipelines for each repo. These help you test your changes in the **Tools PR**.  All of this is done in `Create Sync` stage (display name: `Sync .github/workflows Directory`) [of the pipeline eng-workflows-sync.yml file][yml], specifically, the logic lives in `template: ./templates/steps/sync-directory.yml`.
+4. If you make additional changes to your **Tools PR** repeat steps 1 - 3 until you have completed the necessary testing of your changes. This includes full releases of the template package, if necessary.
+5. Once you reviewed all the test runs and did any of additional ad-hoc tests from the created branches in language repositories, you must manually approve in your pipeline execution instance the next stage - creation of PRs.
+6. Once approved, the pipeline proceeds to the next stage, named `CreateSyncPRs` in the [eng-workflows-sync.yml file][yml]. This stage creates one pull request for each language repository, merging changes from the branch created in step 3 into the default (usually `main`) branch. We call these PRs here **Sync PRs**. A link to each of the **Sync PRs** will show up in the **Tools PR** for you to click and review.
+7. Review and approve each of your **Sync PRs**. For some repos (C and C++) you might need to frequently use the `Update Branch` button to get the checks green.
+8. Sign Off on the [`VerifyAndMerge` stage][yml]. This will merge any remaining open **Sync PR** and also append `auto-merge` to the **Tools PR**.
+   - If a **Sync PR** has any failing checks, it will need to be manually merged, even if `/check-enforcer override` has been run ([azure-sdk-tools#1147](https://github.com/Azure/azure-sdk-tools/issues/1147)).
+
+### The pipeline link needs to be updated once the pipeline is created
+
+[pipeline]: https://dev.azure.com/azure-sdk/internal/_build?definitionId=1372&_a=summary
+[yml]: https://github.com/Azure/azure-sdk-tools/blob/main/eng/pipelines/eng-workflows-sync.yml
--- a/eng/common/pipelines/templates/steps/eng-common-workflow-enforcer.yml
+++ b/eng/common/pipelines/templates/steps/eng-common-workflow-enforcer.yml
@ -19,5 +19,15 @@ steps:
            exit 1
          }
        }
-      displayName: Prevent changes to eng/common outside of azure-sdk-tools repo
+        if ((!"$(System.PullRequest.SourceBranch)".StartsWith("sync-.github/workflows")) -and "$(System.PullRequest.TargetBranch)" -match "^(refs/heads/)?$(DefaultBranch)$")
+        {
+          $filesInCommonDir  = & "eng/common/scripts/get-changedfiles.ps1" -DiffPath '.github/workflows/*'
+          if (($LASTEXITCODE -eq 0) -and ($filesInCommonDir.Count -gt 0))
+          {
+            Write-Host "##vso[task.LogIssue type=error;]Changes to files under '.github/workflows' directory should not be made in this Repo`n${filesInCommonDir}"
+            Write-Host "##vso[task.LogIssue type=error;]Please follow workflow at https://github.com/Azure/azure-sdk-tools/blob/main/doc/workflows/engsys_workflows.md"
+            exit 1
+          }
+        }
+      displayName: Prevent changes to eng/common and .github/workflows outside of azure-sdk-tools repo
      condition: and(succeeded(), ne(variables['Skip.EngCommonWorkflowEnforcer'], 'true'), not(endsWith(variables['Build.Repository.Name'], '-pr')))
--- a/eng/common/scripts/Delete-RemoteBranches.ps1
+++ b/eng/common/scripts/Delete-RemoteBranches.ps1
@ -10,6 +10,7 @@ param(
  $CentralRepoId,
  # We start from the sync PRs, use the branch name to get the PR number of central repo. E.g. sync-eng/common-(<branchName>)-(<PrNumber>). Have group name on PR number.
  # For sync-eng/common work, we use regex as "^sync-eng/common.*-(?<PrNumber>\d+).*$".
+  # For sync-.github/workflows work, we use regex as "^sync-.github/workflows.*-(?<PrNumber>\d+).*$".
  $BranchRegex,
  # Date format: e.g. Tuesday, April 12, 2022 1:36:02 PM. Allow to use other date format.
  [AllowNull()]
@ -69,7 +70,7 @@ foreach ($res in $responses)
      LogError "No PR number found in the branch name. Please check the branch name [ $branchName ]. Skipping..."
      continue
    }
-      
+
    try {
      $centralPR = Get-GitHubPullRequest -RepoId $CentralRepoId -PullRequestNumber $pullRequestNumber -AuthToken $AuthToken
      LogDebug "Found central PR pull request: $($centralPR.html_url)"
@ -78,7 +79,7 @@ foreach ($res in $responses)
        continue
      }
    }
-    catch 
+    catch
    {
      # If there is no central PR for the PR number, log error and skip.
      LogError "Get-GitHubPullRequests failed with exception:`n$_"
@ -107,15 +108,15 @@ foreach ($res in $responses)
        LogDebug "The branch $branch last commit date [ $commitDate ] is newer than the date $LastCommitOlderThan. Skipping."
        continue
      }
-      
+
      LogDebug "Branch [ $branchName ] in repo [ $RepoId ] has a last commit date [ $commitDate ] that is older than $LastCommitOlderThan. "
    }
    catch {
      LogError "Get-GithubReferenceCommitDate failed with exception:`n$_"
      exit 1
    }
-  } 
-  
+  }
+
  try {
    if ($PSCmdlet.ShouldProcess("[ $branchName ] in [ $RepoId ]", "Deleting branches on cleanup script")) {
      Remove-GitHubSourceReferences -RepoId $RepoId -Ref $branch -AuthToken $AuthToken
--- a/eng/pipelines/branch-cleanup.yml
+++ b/eng/pipelines/branch-cleanup.yml
@ -5,6 +5,7 @@ parameters:
 - name: Repos
  type: object
  default:
+    - Azure/azure-sdk
    - Azure/azure-sdk-for-android
    - Azure/azure-sdk-for-c
    - Azure/azure-sdk-for-cpp
@ -49,14 +50,28 @@ jobs:
            workingDirectory: $(System.DefaultWorkingDirectory)
            filePath: $(System.DefaultWorkingDirectory)/eng/common/scripts/Delete-RemoteBranches.ps1
            arguments: >
-              -RepoId ${{ repo }} 
+              -RepoId ${{ repo }}
              -CentralRepoId "Azure/azure-sdk-tools"
              -BranchRegex "^sync-eng/common.*-(?<PrNumber>\d+).*$"
              -AuthToken $(azuresdk-github-pat)
              -WhatIf:$${{parameters.WhatIfPreference}}
+        - task: PowerShell@2
+          displayName: Clean Up ${{ repo }} Sync Workflows Branches
+          condition: succeededOrFailed()
+          continueOnError: true
+          inputs:
+            pwsh: true
+            workingDirectory: $(System.DefaultWorkingDirectory)
+            filePath: $(System.DefaultWorkingDirectory)/eng/common/scripts/Delete-RemoteBranches.ps1
+            arguments: >
+              -RepoId ${{ repo }}
+              -CentralRepoId "Azure/azure-sdk-tools"
+              -BranchRegex "^sync-.github/workflows.*-(?<PrNumber>\d+).*$"
+              -AuthToken $(azuresdk-github-pat)
+              -WhatIf:$${{parameters.WhatIfPreference}}
      - ${{ each repo in parameters.SDKPrivate }}:
        - task: PowerShell@2
-          displayName: Clean Up ${{ repo }} swagger private SDK PR and branches 
+          displayName: Clean Up ${{ repo }} swagger private SDK PR and branches
          condition: succeededOrFailed()
          continueOnError: true
          inputs:
@ -81,5 +96,5 @@ jobs:
              -RepoId ${{ repo }}
              -BranchRegex "^daily"
              -LastCommitOlderThan ((Get-Date).AddDays(-7))
-              -AuthToken $(azuresdk-github-pat) 
+              -AuthToken $(azuresdk-github-pat)
              -WhatIf:$${{parameters.WhatIfPreference}}
--- a/eng/pipelines/eng-workflows-sync.yml
+++ b/eng/pipelines/eng-workflows-sync.yml
@ -0,0 +1,37 @@
+# Mirror the .github/workflows folder to all subscribed repos.
+#
+# For more information on this file, please see:
+# doc/common/common_engsys.md
+parameters:
+- name: DirectoryToSync
+  type: string
+  default: .github/workflows
+- name: Repos
+  type: object
+  default:
+    - azure-sdk
+    - azure-sdk-for-android
+    - azure-sdk-for-c
+    - azure-sdk-for-cpp
+    - azure-sdk-for-go
+    - azure-sdk-for-ios
+    - azure-sdk-for-java
+    - azure-sdk-for-js
+    - azure-sdk-for-net
+    - azure-sdk-for-python
+
+trigger: none
+
+pr:
+  branches:
+    include:
+      - main
+  paths:
+    include:
+      - .github/workflows
+
+extends:
+  template: /eng/pipelines/templates/stages/archetype-sdk-tool-repo-sync.yml
+  parameters:
+    DirectoryToSync: ${{ parameters.DirectoryToSync }}
+    Repos: ${{ parameters.Repos }}