OSS Contributions Generator - GitHub Marketplace

3 min read Original article ↗

OSS Contributions Action

A GitHub Action (written in Go) that automatically generates a markdown section listing your open-source contributions — merged PRs in repositories you don't own — and updates your README.

Output Example

## Open-Source Contributions

**[cpython](https://github.com/python/cpython) (The Python programming language)**

* [#4297](https://github.com/python/cpython/pull/4297): bpo-21862: Add -m option to cProfile for profiling modules
* [#4376](https://github.com/python/cpython/pull/4376): bpo-16055: Fixes incorrect error text for int('1', base=1000)

**[django](https://github.com/django/django) (The Web framework for perfectionists with deadlines.)**

* [#10569](https://github.com/django/django/pull/10569): Fixed #20098 -- Added a check for model Meta.db_table collisions.

**[hypothesis](https://github.com/HypothesisWorks/hypothesis) (The property-based testing library for Python)**

* [#1557](https://github.com/HypothesisWorks/hypothesis/pull/1557): fix(core): HypothesisDeprecationWarning now gives indication of slow tests

Quick Start

1. Add markers to your README

Add these HTML comments where you want the contributions section to appear:

<!-- OSS_CONTRIBUTIONS_START -->
<!-- OSS_CONTRIBUTIONS_END -->

The action will insert the generated content between these markers on each run.

2. Create a config file

Create .contributions.yml in your repo root:

username: "your-github-username"

# Optional: only include PRs from specific repos or orgs
# include:
#   repos:
#     - "python/cpython"
#   orgs:
#     - "django"

# Optional: exclude specific repos or orgs
# exclude:
#   repos:
#     - "some/repo"
#   orgs:
#     - "some-org"

# Optional: override display names and descriptions
# repo_overrides:
#   python/cpython:
#     display_name: "CPython"
#     description: "The Python programming language"

output:
  file: "README.md"
  heading: "## Open-Source Contributions"

3. Add the workflow

Create .github/workflows/update-contributions.yml:

name: Update OSS Contributions

on:
  schedule:
    - cron: "0 0 * * 1"  # Weekly on Monday
  workflow_dispatch:

permissions:
  contents: write

jobs:
  update-contributions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate OSS Contributions
        uses: CuriousLearner/oss-contributions-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          config_file: ".contributions.yml"

      - name: Commit and push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git diff --quiet README.md || (git add README.md && git commit -m "docs: update open-source contributions" && git push)

Configuration Reference

Field Type Default Description
username string required GitHub username to query PRs for
include.repos string[] [] Only include these owner/repo entries
include.orgs string[] [] Only include repos from these orgs
exclude.repos string[] [] Exclude these owner/repo entries
exclude.orgs string[] [] Exclude repos from these orgs
repo_overrides.<repo>.display_name string repo name Custom display name
repo_overrides.<repo>.description string GitHub description Custom description
output.file string README.md File to update
output.start_marker string <!-- OSS_CONTRIBUTIONS_START --> Start marker comment
output.end_marker string <!-- OSS_CONTRIBUTIONS_END --> End marker comment
output.heading string ## Open-Source Contributions Markdown heading

Action Inputs

Input Required Default Description
github_token No ${{ github.token }} Automatically provided by GitHub Actions — no setup needed. Only override if you need a custom PAT (e.g., for private repos).
config_file No .contributions.yml Path to config file

Action Outputs

Output Description
markdown The generated markdown content

How It Works

  1. Uses the GitHub Search API to find all merged PRs by the configured user in external repos
  2. Filters results based on include/exclude rules from the config
  3. Fetches repo metadata (description) from the GitHub API
  4. Applies any display name or description overrides from the config
  5. Generates markdown grouped by repository, sorted alphabetically
  6. Replaces the section between the start/end markers in the target file

License

MIT