Skip to content

profile-readme.md

Latest commit

 

History

History
174 lines (115 loc) · 7.04 KB

profile-readme.md

File metadata and controls

174 lines (115 loc) · 7.04 KB
Raw

Profile README Example

Quick Start: Recommended GitHub Actions Setup

  1. Copy profile-readme-workflow.yml into your profile README repository as .github/workflows/update-buildmarks-card.yml.

  2. Add the generated card and report link to your profile README.md:

![Buildmarks public project snapshot](./assets/buildmarks.svg)

[View the Buildmarks report](./assets/buildmarks-report/buildmarks-report.html)
  1. Run the workflow once from GitHub Actions using the manual workflow_dispatch button.

The workflow creates and commits:

assets/buildmarks.svg
assets/buildmarks-report/buildmarks-report.html
assets/buildmarks-report/buildmarks-report.json

This is the recommended backend-free path. GitHub serves the checked-in SVG and report directly from your profile repository, so profile views do not trigger fresh API requests.

Static Checked-In Card

Generate a local SVG card from a profile fixture:

bun run build:card

Then copy the generated SVG into a public location that your GitHub profile README can load.

![Buildmarks public project snapshot](./out/example-card.svg)

Public GitHub Collection

Generate a card directly from public GitHub data:

bun src/cli/render-github-card.ts YOUR_USERNAME assets/buildmarks.svg --token "optional-public-data-token"

Generate the matching static report from the same public data:

bun src/cli/render-github-report.ts YOUR_USERNAME assets/buildmarks-report --token "optional-public-data-token"

Add the report link to the SVG when generating the card manually:

bun src/cli/render-github-card.ts YOUR_USERNAME assets/buildmarks.svg --token "optional-public-data-token"

For quick unauthenticated demos, keep the scan small:

bun src/cli/render-github-card.ts YOUR_USERNAME assets/buildmarks.svg --max-repositories-scanned 1 --max-repositories-scored 1

Then reference the checked-in SVG from your profile README:

![Buildmarks public project snapshot](./assets/buildmarks.svg)

[View the Buildmarks report](./assets/buildmarks-report/buildmarks-report.html)

The token is optional for local public-only experiments, but authenticated requests are much less likely to hit GitHub's low unauthenticated REST API limit. Buildmarks does not read tokens from environment variables automatically; pass a token explicitly when you want one used.

Private-local mode is opt-in. Use private-local: "true" only in an owner-controlled workflow with an explicit read token for selected private repositories. Names and URLs are redacted by default, but the artifacts can still reveal private project details. Do not commit private-local SVG, HTML, or JSON to a public profile repository unless that disclosure is intentional.

GitHub Actions

Copy profile-readme-workflow.yml into your profile README repository as .github/workflows/update-buildmarks-card.yml.

That workflow uses the official composite action, generates assets/buildmarks.svg plus assets/buildmarks-report/, links the SVG to the HTML report, and commits the generated artifacts only when they change. This keeps the profile README backend-free: GitHub serves the SVG and report as normal repository assets.

The composite action generates files only. The workflow around it owns checkout, repository write permission, staging, commit, and push. The example stages generated artifacts before checking for changes, so the first run commits new files correctly.

Use exact string values for action booleans. generate-report and private-local accept "true" or "false" only, and repository limits must be positive integers.

The default repository activity window is 365 days from the public pushed_at timestamp. Use activity-window-days: "180" for a six-month snapshot that emphasizes recent projects and makes fewer per-repository API calls. This is a collection window, not a claim that older work has no value.

Minimal action step:

- uses: 0disoft/buildmarks@v0
  with:
    username: ${{ github.repository_owner }}
    output: assets/buildmarks.svg
    generate-report: "true"
    report-output: assets/buildmarks-report
    token: ${{ github.token }}

Action inputs:

Input Default Notes
username required Non-empty GitHub username to analyze.
output assets/buildmarks.svg Non-empty SVG artifact path in the caller repository.
generate-report "true" Must be exactly "true" or "false".
report-output assets/buildmarks-report Non-empty HTML and JSON report directory.
token empty Optional token. Public-only mode does not need private scopes; private-local mode requires an explicit owner-provided read token.
private-local "false" Must be exactly "true" or "false". Includes owner-supplied private repositories and hides their names.
max-repositories-scanned 30 Positive integer public repository scan limit, capped at 100 and must be greater than or equal to max-repositories-scored.
max-repositories-scored 12 Positive integer repository display limit, capped at 24. Despite the legacy input name, all successfully evaluated repositories contribute to the profile calculation.
activity-window-days 365 Positive integer recent-activity window based on public pushed_at, capped at 3650.
max-api-requests 160 Positive integer GitHub REST request budget for one profile collection, capped at 500. Retries spend budget.

See profile-smoke-test.md for the real v0 adoption smoke-test checklist.

Example Card Assets

Committed sample SVGs are available in assets for quick visual inspection:

![Buildmarks public project snapshot](./assets/example-card.svg)
![Buildmarks project improvement card](./assets/example-gaps-card.svg)
![Buildmarks repository snapshot](./assets/example-repo-card.svg)

Project Suggestions Card

Generate a static card with practical ways to strengthen the projects in the local fixture:

bun run build:gaps-card

Then reference it from your README:

![Buildmarks project improvement card](./out/example-gaps-card.svg)

Repository Snapshot Card

Generate a static card for one repository from the local fixture:

bun run build:repo-card

Then reference it from a project README:

![Buildmarks repository snapshot](./out/example-repo-card.svg)

Inspectable Static Report

Generate an HTML and JSON report:

bun run build:report

Then link to the static report from your README:

[View the Buildmarks report](./out/report/buildmarks-report.html)

The JSON next to the HTML uses schemaVersion: "buildmarks-report/v1" and scoring rules 2.0.1. Library consumers can validate its shape with the packaged schema at schemas/buildmarks-report-v1.schema.json. The report shows how much Buildmarks checked and records how many repositories were reviewed versus how many fit on the card.

For a hosted version, replace the checked-in SVG path with the future card endpoint once that service exists.