From 2dbe6254db509a53e4a1ef5482f41fb360d924ab Mon Sep 17 00:00:00 2001 From: Zack Koppert Date: Thu, 20 Jul 2023 08:39:30 -0700 Subject: [PATCH 1/2] docs: enhance setup instructions fixes #53 --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3c87d0f..58f9411 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,16 @@ If you need support using this project or have questions about it, please [open ## Use as a GitHub Action -1. Create a repository to host this GitHub Action or select an existing repository. -1. Create the env values from the sample workflow below (GH_TOKEN, SEARCH_QUERY) with your information as repository secrets. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). -Note: Your GitHub token will need to have read access to the repository in the organization that you want evaluated +1. Create a repository to host this GitHub Action or select an existing repository. This is easiest if it is the same repository as the one you want to measure metrics on. +1. Select a best fit workflow file from the [examples below](#example-workflows). +1. Copy that example into your repository from step 1 into the proper directory for GItHub Actions: `/.github/workflows/metrics.yaml` +1. Edit the values (`SEARCH_QUERY`, `assignees`) from the sample workflow with your information. See the [SEARCH_QUERY](#search_query) section for more details on options. +1. If you are running metrics on a repository other than the one where the workflow file is going to be, then update the value of `GH_TOKEN` to a GitHub API token with permissions to read the repo. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). +Note: All API tokens generated will need to have read access to the repository in the organization that you want evaluated +1. If you are wanting the resulting issue with the metrics in it to appear in a different repository other than the one the workflow file runs in, update the line `token: ${{ secrets.GITHUB_TOKEN }}` without your own GITHUB API token stored as a repository secret. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). 1. Copy the below example workflow to your repository and put it in the `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/issue-metrics.yml`) +1. Commit the workflow file to the default branch (often `master` or `main`) +1. Wait for the action to trigger based on the `schedule` entry or manually trigger the workflow as shown in the [documentation](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow). ### Configuration @@ -137,7 +143,8 @@ jobs: ``` -## SEARCH_QUERY: Issues or Pull Requests? Open or closed? +## SEARCH_QUERY +Issues or Pull Requests? Open or closed? This action can be configured to run metrics on discussions, pull requests and/or issues. It is also configurable by whether they were open or closed in the specified time window. Further query options are listed in the [documentation on searching issues and pull requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) or the [documentation on searching discussions](https://docs.github.com/en/search-github/searching-on-github/searching-discussions). Here are some search query examples: Issues opened in May 2023: From f0d7ec466725a99f1f86529787365711404ebb0d Mon Sep 17 00:00:00 2001 From: Zack Koppert Date: Thu, 20 Jul 2023 12:06:07 -0700 Subject: [PATCH 2/2] Clarify token creation and storing as a repo secret --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 58f9411..291f794 100644 --- a/README.md +++ b/README.md @@ -32,12 +32,10 @@ If you need support using this project or have questions about it, please [open 1. Create a repository to host this GitHub Action or select an existing repository. This is easiest if it is the same repository as the one you want to measure metrics on. 1. Select a best fit workflow file from the [examples below](#example-workflows). -1. Copy that example into your repository from step 1 into the proper directory for GItHub Actions: `/.github/workflows/metrics.yaml` +1. Copy that example into your repository (from step 1) and into the proper directory for GitHub Actions: `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/issue-metrics.yml`) 1. Edit the values (`SEARCH_QUERY`, `assignees`) from the sample workflow with your information. See the [SEARCH_QUERY](#search_query) section for more details on options. -1. If you are running metrics on a repository other than the one where the workflow file is going to be, then update the value of `GH_TOKEN` to a GitHub API token with permissions to read the repo. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). -Note: All API tokens generated will need to have read access to the repository in the organization that you want evaluated -1. If you are wanting the resulting issue with the metrics in it to appear in a different repository other than the one the workflow file runs in, update the line `token: ${{ secrets.GITHUB_TOKEN }}` without your own GITHUB API token stored as a repository secret. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). -1. Copy the below example workflow to your repository and put it in the `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/issue-metrics.yml`) +1. If you are running metrics on a repository other than the one where the workflow file is going to be, then update the value of `GH_TOKEN`. Do this by creating a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with permissions to read the repo and write issues. Then take the value of the API token you just created, and [create a repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) where the name of the secret is `GH_TOKEN` and the value of the secret the API token. Then finally update the workflow file to use that repository secret by changing `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to `GH_TOKEN: ${{ secrets.GH_TOKEN }}`. The name of the secret can really be anything. It just needs to match between when you create the secret name and when you refer to it in the workflow file. +1. If you want the resulting issue with the metrics in it to appear in a different repository other than the one the workflow file runs in, update the line `token: ${{ secrets.GITHUB_TOKEN }}` with your own GitHub API token stored as a repository secret. This process is the same as described in the step above. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). 1. Commit the workflow file to the default branch (often `master` or `main`) 1. Wait for the action to trigger based on the `schedule` entry or manually trigger the workflow as shown in the [documentation](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow).