Skip to content

Latest commit

 

History

History
124 lines (83 loc) · 5.38 KB

README.md

File metadata and controls

124 lines (83 loc) · 5.38 KB

Documentation

Concepts

A report is a generated markdown file (and soon might be html or json). A report has many sections. A section and it's data is generated by crawling issues from a project board's cards or a repositories issues (known as targets). For that reason, there are "project" reports and "repo" reports. A project report for example expects data from a project board (and it's stages).

Project board reports report on the life cycle of work (a card) as it moves through stages. The logical stages are pre-defined for consistent reports.

    Proposed => Accepted => In-Progress => Done

Note: "In progress" (default in GitHub Kanban project) is auto mapped to In-Progress.

Each stage can map to one or more physical columns on your board. The time for each stage is recorded as the first time it entered that stage from a previous stage or no stage. For example, if it moved from accepted to in progress on date 1, then to Done on date 2 and back to in progress on date 3, it has been in progress since date 1.

If a report section targets multiple targets, the data will be rolled up and passed to the report. Since the stages and times are normalized, it can provide a common view of different boards and repos.

So let's get started ...

Create a repo for running and storing your reports

This could be an existing repo but having a separate repo for the reports is preferred. This also allows for securing reports. The wider the scope, the better the ability to rollup data, share the cache and avoid rate limiting. Note that the crawler writes a cache of etags so only data that changes between runs is pulled and debited to your rate limits.

Create a token for accessing

Create a personal access token that can read repo and project scopes for an identity that has permissions to the projects and repositories you are reporting on.

Add the secret to your repo and give it a name like PROJECT_TOKEN. Documentation is here.

Using in a workflow

Add the project-reports-action after the 'checkout step. Specify the secret name in the token input and supply a path relative to the root of the repo with your configuration file.

jobs:
  run-reports:
    runs-on: ubuntu-18.04
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v2
      - uses: bryanmacfarlane/project-reports-action@v1-alpha5
        with: 
          token: ${{ secrets.PROJECT_TOKEN }}
          configPath: yourconfig.yml

You will want to checkin the reports after they are generated. Note that the etag cache and other data files should be checked in with the reports. Do this by checking in the _reports folder generated in the root of the repo.

Add this step after the project-reports-action step. Note that pull-requests validate the report generation run but do not checkin reports or the cache.

    steps:
...
      - if: ${{ github.ref == 'refs/heads/master' }}
        run: |
          git config user.name github-actions
          git config user.email [email protected]     
          git pull origin master          
          git add ./_reports
          git commit -a -m "adding reports"
          git push origin master

Minimal Configuration File for Project

If you follow all the defaults, then a configuration file can be minimal. The sample-reports repository is an example of this.

Type labels: epic, feature, task, bug
Status labels: green, yellow, red
Project board column names: Proposed, Accepted, In progress, Done

NOTE: Github boards kanban creates a column named "In progress" by default. The action auto maps that to the "In-Progress" stage. The hyphen allows use in yaml tags etc.

For issue "updates" head with ## update (last updated column will read)

This is the minimal configuration file for a project:

targets: 
  sampleProject:
    type: project
    htmlUrl: https://github.com/users/bryanmacfarlane/projects/2

reports:
  - name: Sample
    title: "My Project Report"
    targets: ['sampleProject']
    sections:
      - name: "project-limits"
      - name: "project-in-progress"
      - name: "project-done"
      - name: "project-new"

If your column names are not the stage names listed above, it may still work since other common column names are auto mapped.

Proposed => New, Ready for Review, Ready for Triage, Not Started
Accepted => Ready for Work, Approved, Up Next
In-Progress => Active, In progress, InProgress, Started
Done => Completed, Complete

If it's not in that list, see the next section for configuration file details. You can still map them.

Configuration File Details

Detailed configuration settings are covered here

Built-in Reports

Documentation for reports built-in to the action

🚢 project-limits: Flag limits broken down by type and count labels

⏳ project-in-progress: Flag limits broken down by type and count labels

👋 project-new: List cards added to the board in last n days.

🏁 project-done: List cards completed in last n days.

Custom Reports

TODO: document and test