https://github.com/rseng/opensource-heartbeat-action
Generate an interface to showcase the open source contributions for your organization or user group (under development)
https://github.com/rseng/opensource-heartbeat-action
Last synced: 4 months ago
JSON representation
Generate an interface to showcase the open source contributions for your organization or user group (under development)
- Host: GitHub
- URL: https://github.com/rseng/opensource-heartbeat-action
- Owner: rseng
- Created: 2020-08-18T17:33:57.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-05-28T12:20:51.000Z (about 3 years ago)
- Last Synced: 2024-09-17T00:09:12.190Z (almost 2 years ago)
- Language: Python
- Size: 699 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Open Source Heartbeat
A GitHub action to generate a web interface to show GitHub activity for a subset
of users or organizations.
- the interface is created under docs/
- events are populated in docs/_events
- the site is served via Jekyll
This means that you can use the action in your workflows too,
and choose how often / when to run it, and how to update your GitHub pages.
Continue reading to learn more.
## Interface
The main page shows a sortable view of the top 100 new contributions. You can
filter down to a contribution type, or click on browse to see a subset of that type.
Here is the browse view.
And here is looking at an archive for a contribution type. Archives are linked from
the browse page.
And finally, a chart shows a summary of contributions.
## Getting Started
If you have a custom set of users or organizations, you'll need to first generate a
users.txt file (or a differently named file that you'll specify as the `users_file` for your action
and/or an orgs.txt file (for the `orgs_file` to specify organizations to use).
As an alternative, you can have this file generated or updated via the GitHub action first
by specifying the `query` argument. For help building your query, it's recommended to try
your search in the [GitHub Advanced](https://github.com/search/advanced) view. For example,
to search users for the location being "Stanford" I might use the query `location%3AStanford`.
To summarize, you'll need to:
1. Add A GitHub workflow for your run, you can see examples in the [examples](examples) folder.
2. Run the workflow as you have set up to generate the docs/ folder.
3. Update the _config.yml in the docs folder to have the correct baseurl for your site.
Once the docs folder is added to your repository via a pull request, it won't be generated
again, so you are free to customize it as you like.
## Inputs
### `users_file`
**Optional** The path to the users.txt (or otherwise named) file that has
a single GitHub username per line. These are the users that will have their
events parsed to show on the website.
```
username1
username2
...
usernameN
```
If you define the `query` variable this file will be updated, or created first
if it doesn't exist.
### `orgs_file`
**Optional** If you want to add contributions based on organizations, you can
define an `orgs_file` which defaults to orgs.txt. The format is the same as
the `users_file`. If you don't define this variable, parsing organization
events will be skipped.
### `users_from_orgs_file`
If you want to use an organization to look up public members, set this varaible.
It will default to `user-orgs.txt` and be used if it's found.
### `query`
**Optional** If defined, we will use [update-users.py](scripts/update-users.py)
to first update the users.txt based on your query. For example,
to search users for the location being "Stanford" I might use the query `location%3AStanford`.
For help building your query, it's recommended to try your search in the
[GitHub Advanced](https://github.com/search/advanced) view. If this variable
is not defined, the update will be skipped, and you will be required to already
have a users.txt file.
### `cleanup`
If defined as anything, clean up the previous collection folder before generating
new events. If not defined, skip cleanup entirely (old events will be preserved).
### `exclude_users_file`
**Optional** The path to the exclude-users.txt (or otherwise named) file that has
a single GitHub username per line for users to not include. For example, if we discover
a username via a query but then don't want to add it (e.g., the user has requested
not being added) it will not be included. This file has the same format
as the users.txt file - one username per line.
```
username1
username2
...
usernameN
```
### `events`
A comma separated list of allowed events. By default, we use "all" to allow all events.
Events include:
- PushEvent
- IssueCommentEvent
- PullRequestEvent
- CreateEvent
- IssueCommentEvent
- ReleaseEvent
- IssuesEvent
- PublicEvent
- PullRequestReviewCommentEvent
- PullRequestReviewEvent
For example, maybe you are just interested in questions being asked by members of your
orgs (or repos they need help or contribution to) - you would select the IssuesEvent.
Or if you want to see contribution, you might choose the PullRequestEvent. It's up to you!
### `token`
Your GitHub token is required to define in the environment to increase query
limits for the GitHub API.
## Supporting Scripts
If you want to update the users.txt file manually (and via the same method
done for the action) you can do that via:
```
$ python scripts/update-users.py --help
Present working directory is /home/vanessa/Desktop/Code/rseng/stanford-issues/scripts
usage: update-users.py [-h] [--version] [--users-file USERS_FILE] [--exclude-users-file EXCLUDE_USERS_FILE]
[--user-query USER_QUERY]
Open Source Heartbeat
optional arguments:
-h, --help show this help message and exit
--version suppress additional output.
--users-file USERS_FILE
The users.txt file with GitHub usernames on lines.
--exclude-users-file EXCLUDE_USERS_FILE
A list of users to never add (that might still be discovered).
--user-query USER_QUERY
The string portion of a user query, generate with
https://github.com/search/advanced.
```
For example:
```bash
$ python scripts/update-users.py --users-file users.txt --user-query "location%3AStanford"
...
users file: users.txt
users file: exclude-users.txt
Found 24 new users!
```
## Example usage
In the example usage below, you should update the `master` branch to a versioned
release.
```yaml
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Generate OpenSource Heartbeat Interface
uses: rseng/opensource-heartbeat-action@master
with:
users_file: 'users.txt'
collection: 'docs/_events'
query: 'location%3AStanford'
token: ${{ secrets.GITHUB_TOKEN }}
```
If you want to just include a subset of organizations (and not parse individual
users) then you can leave out the query, and don't define the users file.
```yaml
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Generate OpenSource Heartbeat Interface
uses: rseng/opensource-heartbeat-action@master
with:
orgs_file: 'orgs.txt'
collection: 'docs/_events'
token: ${{ secrets.GITHUB_TOKEN }}
```
## Questions
## Why do I only see 1 push event for my repository?
For push and comment events, it might be the case that a user comments or pushes
multiple times on a single repository. To be concise, we only add the first
event of this type seen, per user and per repository. This means that the
events that are generated are generally an underestimate of actual activity.
## How do I customize the interface?
The interface will always be generated in the docs subfolder, so
if you haven't created it there yet, the action will generate
it the first time around. It's up to you to add all or a subset of
files in docs/* or docs/_events after the content is generated.
For example, you could add both docs and _issues
in a next step that will commit to an existing or new branch:
```
git add docs/*
git add docs/_issues/*
```
This means that after the original docs is added and merged,
you should be able to customize or otherwise update the template
to your liking. The folder won't be edited if it already exists
beyond the _events folder.
## Showcase
If you use the action and want to share, please open a pull request to add your repository here!
- [vsoch Opensource Heartbeat](https://vsoch.github.io/opensource-heartbeat/)
- [rse-ops Opensource Heartbeat](https://rse-ops.github.io/opensource-heartbeat/)
- [Stanford Opensource Heartbeat](https://stanford-rc.github.io/opensource-stanford/) (removed/404 when @vsoch left Stanford)
- **Coming soon** LLNL RADIUSS
## Future Wants
It would be nice to have the ability to see charts by year (e.g., to determine
contribution changes over the years).