diff --git a/WhatsNew.Cli/README.md b/WhatsNew.Cli/README.md index f19c847..75adbf7 100644 --- a/WhatsNew.Cli/README.md +++ b/WhatsNew.Cli/README.md @@ -21,6 +21,10 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs] ## Usage +You can use the tool from the command line, or as a GitHub action. If you run on the command line, the tool generates the changes for a new article on your machine. If you run as a GitHub action, the action opens a PR for you. THe only functional difference in the output is that the GitHub action filters Microsoft FTEs from the contributor list. The command line version doesn't due to access rights. + +To use the tool as a command line executable: + 1. Clone the `dotnet/docs-tools` repository. 1. Generate a PAT per the instructions at [Creating a token](https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token). When selecting scopes for the PAT, check the following boxes: - For private repos: @@ -31,17 +35,8 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs] - **admin:org** > **read:org** 1. For private repos in the *MicrosoftDocs* GitHub organization, after generating the PAT, select **Enable SSO** and choose **Authorize** for the **MicrosoftDocs**. 1. Store the PAT in an environment variable named `GitHubKey`. -1. Set up an OSPO personal access token - > This step is required for versions 2.0 and above. - - The OSPO personal access token is required to access the OSPO API. This API determines community contributors and Microsoft employee and vendor contributors. -1. Request a token at [Visual Studio Online](https://ossmsft.visualstudio.com/_usersSettings/tokens). You can disable all scopes *except* read:user profile. -1. Store the token in an environment variable named "OspoKey". **If you are using the GitHub Action to generate the PR automatically**, add the key as a secret in your repository: - - Go to **Settings** on your repo. - - Select **Secrets** - - Add "OSPO_KEY" as a **Repository Secret**. -1. Install the [.NET SDK 7.0](https://dotnet.microsoft.com/download/dotnet) or later. -1. build and publish the tool. The `WhatsNew.Cli` folder is at the root of the repository you closed in step 1. By default, this builds the *Debug* configuration. +1. Install the [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet) or later. +1. build and publish the tool. The `WhatsNew.Cli` folder is at the root of the repository you closed in step 1. By default, this builds the *Debug* configuration. ```bash cd ./WhatsNew.Cli @@ -56,6 +51,12 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs] dotnet ../docs-tools/WhatsNew.Cli/bin/Debug/net7.0/publish/WhatsNew.dll --owner MicrosoftDocs --repo visualstudio-docs-pr --savefile ./docs/ide/whats-new-visual-studio-docs.md ``` +To use the tool as an action: + +1. Configure the registered `CLIENT_ID`, `TENANT_ID` and `OSMP_API_AUDIENCE` keys in your repository. Ask the "what's new" admins for the values. +1. Request app registration for your repo / branch pair. +1. A the `whats-new.yml` file in the `.github/Workflows` folder of your repo. The file should generally follow the form in the [dotnet/docs](https://github.com/dotnet/docs/blob/main/.github/workflows/whats-new.yml) version. + ### Examples **Display the help menu:** diff --git a/actions/sequester/README.md b/actions/sequester/README.md index 13b2611..a714483 100644 --- a/actions/sequester/README.md +++ b/actions/sequester/README.md @@ -23,12 +23,15 @@ To install the GitHub actions: - **SEQUESTER_APPID**: This is the app ID for the Sequester Action. Get this from one of the App admins (Bill or Immo). - **SEQUESTER_PRIVATEKEY**: This is the private key to authorize sequester. Get this from one of the App admins (Bill or Immo). - - **OSPO_KEY**: Generate a PAT at [OSSMSFT](https://ossmsft.visualstudio.com/_usersSettings/tokens) with the following permissions: - - *UserProfile*: Read - **QUEST_KEY**: Generate a PAT at [MSFT-SKILLING](https://dev.azure.com/msft-skilling/_usersSettings/tokens) with the following permissions: - *Identity*: Read - *Project & Team*: Read/Write - *WorkItems*: Read/Write + - **CLIENT_ID**: The client ID used for secretless authentication + - **TENANT_ID**: The Tenant ID used for secretless authentication + - **OSMP_API_AUDIENCE**: The audience resource ID used for secretless authentication + + > **Note:** To configure GitHub Action secrets, see [GitHub Docs: Encrypted secrets](https://docs.github.com/actions/security-guides/encrypted-secrets). 1. ***Start applying labels*** - Add the trigger label to any issue, and it will be imported into Quest. @@ -38,11 +41,7 @@ To install the GitHub actions: ## Suggestions for future releases - [ ] Populate the "GitHub Repo" field in Azure DevOps to make reporting by repository easier. -- [X] Add Epics (configurable) as a parent of user stories on import. -- [X] Update the label block in Quest when an issue is closed. That way, any "OKR" labels get added when the work item is completed. This would be a simplified version of updating all labels when labels are added or removed. - [ ] Integrate with Repoman. That tool already performs a number of actions on different events in the repo. The code underlying these events could be ported there. -- [ ] Encapsulate services into their own projects/packages, and share them as needed. -- [X] Use DI where applicable, enabling `IHttpClientFactory`, Polly (for transient fault handling), `IOptions` pattern, and easier testing. ## Triggers @@ -77,22 +76,9 @@ The consuming repository would ideally define the config file. As an example, it } ``` -This config file would override the defaults, enabling consuming repositories to do as they please. In addition to this JSON config, there would need to be three environment variables set: - -- `ImportOptions__ApiKeys__GitHubToken` -- `ImportOptions__ApiKeys__OSPOKey` -- `ImportOptions__ApiKeys__QuestKey` - -These env vars would be assigned to from the consuming repository secrets, as follows (likely in a workflow file named _quest-import.yml_): - -```yaml -env: - ImportOptions__ApiKeys__GitHubToken: ${{ secrets.GITHUB_TOKEN }} - ImportOptions__ApiKeys__OSPOKey: ${{ secrets.OSPO_API_KEY }} - ImportOptions__ApiKeys__QuestKey: ${{ secrets.QUEST_API_KEY }} -``` +## Workflow files -> **Note:** To configure GitHub Action secrets, see [GitHub Docs: Encrypted secrets](https://docs.github.com/actions/security-guides/encrypted-secrets). +Create a PR that adds two workflows into your repository: One to sequester a single issue on demand; the other to bulk import all issues modified in the last N days. In almost all cases, you can copy the versions of [quest.yml](https://github.com/dotnet/docs-tools/blob/main/.github/workflows/quest.yml) and [quest-bulk.yml](https://github.com/dotnet/docs-tools/blob/main/.github/workflows/quest-bulk.yml) files. These files are stored in your repositories `.github/workflows` folder. ## Field mapping