Skip to content

engsys_workflows_and_skills.md

Latest commit

 

History

History
37 lines (25 loc) · 4.95 KB

engsys_workflows_and_skills.md

File metadata and controls

37 lines (25 loc) · 4.95 KB

Engineering System Workflows and Skills

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.

The .github/skills directory contains common copilot skills used in azure-sdk, azure-sdk-tools and the azure-sdk languages repositories, as well as skills local to azure-sdk-tools.

Updating

Any updates to files in the .github/workflows directory should be made in the azure-sdk-tools repo.

Any updates to directories matching the pattern .github/skills/azsdk-common-* should be made in the 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 and skills directories 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 their corresponding directories in the azure-sdk-tools repository.

Workflow

When you create a PR against azure-sdk-tools repo that changes contents of the .github/workflows directory or .github/skills/azsdk-common-*, the PR triggers an tools - sync-.github pipeline that will mirror all changes the corresponding directories 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 or .github/skills/azsdk-common-* directories.
  2. The tools - sync-.github 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 directory 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 Directory) of the pipeline sync-.github.yml file, 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 sync-.github.yml file. 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 and resolve any open review conversations. For some repos (C and C++) you might need to frequently use the Update Branch button to get the checks green.
    • You can mass approve and mark AI-generated PR reviews as resolved with this script: <repo root>/eng/scripts/Approve-Sync-PRs.ps1 <tools sync PR>
    • This script will also approve the next stage in the sync pipeline (CreateSyncPRs or VerifyAndMerge) so it can proceed.
  8. Sign Off on the VerifyAndMerge stage. 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).

The pipeline link needs to be updated once the pipeline is created