1 unstable release

0.1.0 Mar 19, 2023

#42 in #access-token

MIT license

250KB
461 lines

gh-report-gen

gh-report-gen is a CLI tool written in Rust that fetches Github issues and generate report based on a specified template.
It helps developers easily crate summaries and overviews of the issue in their repositories.

Installation

cargo install gh-report-gen

Prerequisties

Create Github Personal access tokens(PAT)

gh-report-gen uses the Github graphql api. Therefore, a PAT with repo scope which grants read access to your repositories is required.

Settings > Generate new tokens

The GraphQL API does not support authentication with fine-grained personal access tokens.

Usage

It is assumed that the environment variable GH_PAT is exported.

export GH_PAT=ghp_your_personal_access_token_with_repo_scope

Fetch issues and output in default format

gh-report-gen

Filter issues

Fetch issues updated/created after the specified time.
The time is specified in RFC3339 format.

gh-report-gen --since "2023-03-01T00:00:00+09:00"

Specify repositories from which issues will be fetched. The repository is specified in owner/name format.
Since glob pattern is supported, you can write --include myorg/* to specify all repositories in myorg organization.
Specify repositories you want to exclude with --exclude.
By default, --include * is specified, so all repositories are included.

You may specify include/exclude as many times as you wish.
In order for an issue to be eligible for inclusion, it must fall under one of the includes, but not all of the excludes.

For example, to target all repositories of the ymgyt user except the repository corresponding to the "-handson" suffix and
the foo repository of the myorg organization, execute the following.

gh-report-gen \
  --include ymgyt/* \
  --exlucde ymgyt/*-handson \
  --include myorg/foo

Customize output

You can specify how to output the retrieved issues.
The format is based on Rust's template library, tera.
By default, the following template is specified.

For example, to output only the title of the issue

cat << EOF > ./issues.tmpl
# Issues
user: {{ user }}
{% for issue in issues %}
- {{ issue.title }}
{% endfor %}
EOF

gh-report-gen --template ./issues.tmpl

Variables available in template

The following variables can be referenced in template.

name description
user Github username(login) who created the PAT
issues Array of issue

issue

The issue has the following fields
To reference the title of an issue, use something like issue.title.
All times are in RFC3339 format.

name description
number issue ID
title title of the issue
closed boolean whether the issue is closed or not
closed_at time the issue was closed, or None if the issue was not closed
created_at time the issue was created
updated_at time the issue was updated
state current issue state. OPEN
url link to issue
repository_name name of the repository to which the issue belongs
repository_owner owner of the repository to which the issue belogns
assignees assignees for issue excluding the user
labels labels of the issue
tracked_issues_count number of issues the issue is tracking
tracked_closed_issues_count number of closed issues the issue is tracking

Development

Update Github graphql schema

cargo install graphql_client_cli --force
graphql-client introspect-schema https://api.github.com/graphql \
    --header "Authorization: bearer ${GH_PAT}" \
    --header "user-agent: rust-graphql-client"

Github Docs

License

This project is licensed under the MIT license.

Dependencies

~22–40MB
~661K SLoC