Better install instructions

[paul-uz]

Can we get some better installation instructions?

I'm struggling to understand what exactly I need to do in order to use this action.

Step 1 states "Create a repository to host this GitHub Action or select an existing repository."

Do I fork this repo? Clone it then upload to me own account? Or if I select a pre-existing repo, is it the one I want to be scanned?

Step 2 "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. Note: Your GitHub token will need to have read access to the repository in the organization that you want evaluated"

Where do I put these env vars? I see an .env-example file, so I guess I need an .env file, but where would it go? In the repo I want scanning, or in some other repo (see issues with step 1)

[zkoppert]

Hi @paul-uz! Thanks for creating this issue! I agree we need some better instructions.

It's easiest in terms of setup if you use the repo that you want scanned as the repo where you run this action.

Here is an example: I'd like to get statistics on github.com/zkoppert/project-a and I would also like the resulting reports to be opened as issues in that repo.

1. I go to the github.com/zkoppert/project-a repository
2. click on "add file"
3. I name the file at the top with the path for GitHub workflows and my specific file name:
   
4. I copy an example from the issue-metrics README.md file. I chose this one because I want to run the report monthly.

name: Monthly issue metrics
on:
  workflow_dispatch:
  schedule:
    - cron: '3 2 1 * *'

permissions:
  issues: write

jobs:
  build:
    name: issue metrics
    runs-on: ubuntu-latest
    
    steps:

    - name: Get dates for last month
      shell: bash
      run: |
        # Get the current date
        current_date=$(date +'%Y-%m-%d')

        # Calculate the previous month
        previous_date=$(date -d "$current_date -1 month" +'%Y-%m-%d')

        # Extract the year and month from the previous date
        previous_year=$(date -d "$previous_date" +'%Y')
        previous_month=$(date -d "$previous_date" +'%m')

        # Calculate the first day of the previous month
        first_day=$(date -d "$previous_year-$previous_month-01" +'%Y-%m-%d')

        # Calculate the last day of the previous month
        last_day=$(date -d "$first_day +1 month -1 day" +'%Y-%m-%d')

        echo "$first_day..$last_day"
        echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"

    - name: Run issue-metrics tool
      uses: github/issue-metrics@v2
      env:
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SEARCH_QUERY: 'repo:owner/repo is:issue created:${{ env.last_month }} -reason:"not planned"'

    - name: Create issue
      uses: peter-evans/create-issue-from-file@v4
      with:
        title: Monthly issue metrics report
        token: ${{ secrets.GITHUB_TOKEN }}
        content-filepath: ./issue_metrics.md
        assignees: <YOUR_GITHUB_HANDLE_HERE>

5. After I paste it in my browser, I change line 40 SEARCH_QUERY: 'repo:owner/repo is:issue created:${{ env.last_month }} -reason:"not planned"' to match the issues I want to get metrics on. I want metrics for all issues created last month so I change it to SEARCH_QUERY: 'repo:zkoppert/project-a is:issue created:${{ env.last_month }}'
6. Next I change line 47 assignees: <YOUR_GITHUB_HANDLE_HERE> to be assignees: zkoppert since I want the metrics report issue to be assigned to me.
7. I commit the workflow file to the repo
   
8. I can either wait for my workflow to run on the first day of the month, or I can navigate to https://github.com/zkoppert/project-a/actions/workflows/metrics.yaml and click the "Run Workflow button"
   
9. Then after the workflow runs (time to complete will vary by repo), you should see an issue pop up in the repo like this one: https://github.com/zkoppert/project-a/issues

Hope that helps! I'll also work on improving the README documentation.

[paul-uz]

How do I create the GITHUB_TOKEN secret exactly?

EDIT - i'm getting the following error on the step "Run issue-metrics tool"

Starting issue-metrics search...
Searching for issues...
Traceback (most recent call last):
File "/action/workspace/issue_metrics.py", line 324, in
main()
File "/action/workspace/issue_metrics.py", line 275, in main
issues = search_issues(search_query, github_connection)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/action/workspace/issue_metrics.py", line 82, in search_issues
for issue in issues:
File "/usr/local/lib/python3.11/site-packages/github3/structs.py", line 98, in iter
json = self._get_json(response)
^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/local/lib/python3.11/site-packages/github3/structs.py", line 193, in _get_json
json = self._json(response, 200)
^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/local/lib/python3.11/site-packages/github3/models.py", line 161, in _json
raise exceptions.error_for(response)
github3.exceptions.UnprocessableEntity: 422 Validation Failed

I created a personal token in my account, which has access to my organisation repos. Problem is, I don't know what permissions it needs exactly. I selected issues, PRs and some others, as read only, but its still failing.

[zkoppert]

GITHUB_TOKEN should be automatically generated as a part of the GitHub action running. More info on that at https://docs.github.com/en/actions/security-guides/automatic-token-authentication. Is your workflow file in the same repository that you are running metrics on?

Could you post your workflow file?

[paul-uz]

GITHUB_TOKEN should be automatically generated as a part of the GitHub action running. More info on that at https://docs.github.com/en/actions/security-guides/automatic-token-authentication. Is your workflow file in the same repository that you are running metrics on?

Could you post your workflow file?

I copied the workflow you posted and just changed the github user name to my own.

You say the token should be generated automatically but the instructions talk about creating a secret with a token with correct permissions so now I'm totally confused.

[zkoppert]

Here is the decision point on whether or not you need to generate your own token or use the built in one (called GITHUB_TOKEN):

If you are running this workflow in the same repository as the one that you are measuring and the issue with the metrics should also appear in that repository then you do not need to create your own token.

If you are running this workflow in a different repository from the one you are measuring or you want the resulting issue with the metrics in it to appear in a different repository, then you need to create your own token.

[zkoppert]

With regards to the workflow file, you mentioned that you changed the github username. That's great! Did you also change the SEARCH_QUERY? Step 5 from my list above?

[paul-uz]

With regards to the workflow file, you mentioned that you changed the github username. That's great! Did you also change the SEARCH_QUERY? Step 5 from my list above?

No, I kept the search query the same. That wasn't the issue though, it's the token that's not working.

I'm running the action in the report I want to report on, but I get that validation error, so it seems the auto generated token isn't working?

Edit - looks like you need to specify the repository in that search query, which I missed. Again, the instructions aren't super clear. Will retry tomorrow with the repo name in. Is there no way around this so it just uses the repository name of the repository the action is in? Seems redundant to have to set it.

[paul-uz]

Here is the decision point on whether or not you need to generate your own token or use the built in one (called GITHUB_TOKEN):

If you are running this workflow in the same repository as the one that you are measuring and the issue with the metrics should also appear in that repository then you do not need to create your own token.

If you are running this workflow in a different repository from the one you are measuring or you want the resulting issue with the metrics in it to appear in a different repository, then you need to create your own token.

Can you provide succinct instructions on how to set up the 2nd type of token as well, please?

[zkoppert]

I've added instructions for the 2nd type of token in this pull request. Let me know if you feel like something is missing there.

[zkoppert]

regarding the auto-generated token not working, do you have this in your workflow file:

permissions:
  issues: write