Building a Trustworthy Developer Portfolio with GitHub, Node.js, and Structured Evidence
How we built Knowledge Cards in MyZubster, integrated GitHub evidence, protected profile README updates, and learned from a real open-source documentation proposal.
By Daniel Ioni — Founder & Product Builder, MyZubster
Introduction
What does a GitHub profile actually tell us about a developer?
We can examine repositories, commits, pull requests, documentation, and contribution activity. However, those artifacts don't always explain what problems a developer investigated, what knowledge they acquired, or how their work relates to specific technical subjects.
At the same time, a traditional portfolio might contain a long list of declared skills without providing any supporting references.
While developing MyZubster, we started experimenting with a different model.
Our idea was to connect structured descriptions of technical activities with supporting GitHub references while preserving an important distinction:
The existence of a technical artifact is not the same thing as independent verification of someone's expertise.
This article explains how we implemented that idea using Knowledge Cards, our Zorgax integration, GitHub APIs, and a controlled README synchronization workflow.
I'll also describe the bugs we encountered and how an unmerged Monero Docs pull request helped us improve our approach to documenting open-source activities.
1. Designing the Knowledge Card model
We wanted to move beyond traditional skill lists.
Instead of displaying a skill such as Node.js: Expert, we wanted developers to explain their activities and attach relevant technical references.
We created Knowledge Cards containing five main elements:
- Title: What activity or area of knowledge does the card describe?
- Domain: Which technologies or technical subjects are involved?
- Description: What does the owner declare they worked on?
- Evidence: Which external sources support or document that description?
- Verification note: What can readers actually establish from the available evidence?
For example, one of our published cards describes the development of digital identity and privacy-related modules for MyZubster Space Station.
It references a GitHub commit containing implementation work, technical documentation, tests, and GitHub Actions configuration.
View the Space Station Knowledge Card
Inspect the associated GitHub commit
The card distinguishes the owner's description from the public source reference.
This design also helps readers investigate an activity without interpreting every statement as an independently certified qualification.
2. GitHub URL validation: syntax is not verification
One of our first practical problems involved a malformed GitHub commit URL.
We initially added a commit reference manually. It looked correct but was missing the final character of its SHA identifier.
Consequently, our README importer excluded it.
We subsequently added the complete reference using the evidence attachment workflow.
This debugging experience highlighted two different responsibilities:
- Validate that a GitHub URL has an acceptable structure.
- Independently check whether the resource is publicly accessible.
For README import, we use a validation function similar to the following:
const publicGithubSourceUrl = value => {
const url = String(value || '').trim();
return /^https:\/\/github\.com\/[a-z\d_.-]+\/[a-z\d_.-]+\/(?:pull\/[1-9]\d*|commit\/[a-f\d]{40})\/?$/i.test(url)
? url
: '';
};
The regular expression accepts GitHub commit URLs with complete 40-character hexadecimal SHA identifiers and GitHub pull request URLs.
However, this validation does not establish that the commit or pull request exists.
For that, our backend performs a separate GitHub API request.
For example:
GET https://api.github.com/repos/OWNER/REPOSITORY/commits/SHA
If GitHub does not return an accessible resource, our application must not label it as publicly verified.
This distinction is especially important when working with private repositories, inaccessible forks, and authenticated API sessions.
A resource visible to one authenticated account might not be publicly accessible.
Engineering lesson: never confuse format validation with external evidence verification.
3. Linking evidence without automatically certifying expertise
We implemented a workflow that allows developers to attach public GitHub evidence to existing Knowledge Cards.
The owner selects a card, provides a supported GitHub URL, and explicitly confirms the operation.
Our backend checks whether the referenced artifact is publicly accessible before attaching it.
When the check succeeds, the reference can be described as an accessible public GitHub source.
However, we deliberately avoid describing the associated activity as independently certified.
A GitHub commit contains useful information, including its changes, timestamps, commit metadata, and potentially an associated GitHub account.
That information can support an investigation.
It does not independently prove every claim a developer makes about their expertise or individual responsibility.
Our verification notes communicate those limitations directly.
This approach allows structured portfolios to become more transparent without pretending that an automated system can accurately measure developer competence from GitHub metadata alone.
4. Documenting an unmerged Monero Docs proposal
The most interesting test of our evidence model involved Monero Docs.
Through my GitHub account DanielIoni-creator, I prepared a documentation clarification in a fork of the Monero Docs repository.
The proposed change involved the pending parameter of the Wallet RPC method get_transfers.
The original documentation stated:
Include pending transfers.
Our proposed clarification was:
Include pending, unconfirmed outgoing transfers.
The objective was to clarify that the parameter concerns pending outgoing transfers that have not yet been confirmed.
The proposal was submitted to the upstream project through pull request #389.
The pull request was closed without being merged.
Another complication emerged during verification: the original fork and pull request were not accessible without authentication.
Although our connected GitHub account could retrieve information about the activity, we could not treat that access as equivalent to independent public verification.
We had two options.
We could omit the activity entirely because the original evidence wasn't publicly accessible.
Or we could document it transparently, explicitly explaining the limitations.
We chose the second approach.
We prepared a publicly accessible technical document containing the original wording, the proposed modification, references to the original commit and pull request, and a clear statement about the outcome.
Read our Monero Docs contribution dossier
We then created a dedicated Knowledge Card.
View the Monero Knowledge Card
Crucially, we label the supporting document as self-declared documentation that has not been independently verified.
We don't describe the proposal as an accepted upstream contribution, an official Monero collaboration, or an independently certified achievement.
What other developers can learn from this
Not every meaningful engineering activity results in merged code.
Developers investigate problems, prepare proposals, explore unfamiliar codebases, and sometimes submit changes that are not accepted.
These experiences can be documented and discussed.
But the outcome is part of the engineering record.
A transparent portfolio should distinguish a proposed change from a merged change rather than treating both as identical achievements.
5. Using separate evidence categories
The Monero example revealed a limitation in systems that treat every external URL as equivalent evidence.
We needed to distinguish between publicly accessible GitHub commits and public documents authored by the card owner.
These are different categories.
A publicly accessible commit allows readers to inspect a specific repository change.
An owner-authored document allows readers to inspect the owner's account of an activity.
Both can be useful, but they support different conclusions.
We updated our README importer to track them separately.
Conceptually:
let githubSourceCount = 0;
let declaredDocumentCount = 0;
for (const source of evidenceItems) {
if (source.isDocument) {
declaredDocumentCount++;
} else {
githubSourceCount++;
}
}
This simplified illustration reflects the separation implemented in our importer.
Instead of making every reference look like a verified GitHub contribution, the generated README displays distinct labels.
This makes the resulting portfolio more informative and reduces the risk of accidentally overstating the evidence.
6. Safely synchronizing a GitHub profile README
Once the Knowledge Cards were publicly available, we wanted users to include them in their GitHub profiles.
However, automatic README modification introduces a serious risk.
Developers often maintain their GitHub profile descriptions manually. An automated system should not erase existing biographies, project references, or other user-authored content.
We introduced an explicitly managed section:
<!-- MYZUBSTER-KNOWLEDGE-CARDS:START -->
## Knowledge Cards
<!-- Reviewed Knowledge Card content -->
<!-- MYZUBSTER-KNOWLEDGE-CARDS:END -->
During synchronization, Zorgax prepares the updated Knowledge Card content inside these boundaries while preserving unrelated README sections.
If the managed block already exists, it is replaced instead of duplicated.
This makes the operation repeatable.
But we added another important restriction.
If Zorgax cannot retrieve the current GitHub README, the update stops.
During our testing, we encountered this condition when the existing README was temporarily unavailable to the application.
The workflow refused to prepare a potentially unsafe update.
This is preferable to guessing the previous state of an external document.
User-controlled publication
We also separated content generation from publication.
The user must load the existing profile, generate the updated content, inspect the preview, approve it, and authorize the GitHub update.
Knowledge Card publication does not automatically rewrite the user's GitHub profile.
This explicit approval process provides an additional layer of control over public identity information.
7. Idempotence matters for generated text, too
Idempotence is usually discussed in relation to APIs, infrastructure, and database operations.
We discovered that it matters just as much when generating public descriptions.
Our backend automatically appends a standard verification statement when public GitHub evidence is attached to a card.
Initially, a normalization function could remove the final punctuation from an existing custom note.
The result was grammatically incorrect:
... does not independently certify expertise At least
one public GitHub source has been linked ...
We corrected the text-normalization logic so it preserves or restores punctuation.
However, fixing new updates wasn't enough.
We also needed to repair notes that had already been published.
We therefore supported an explicit refresh operation for existing cards.
One requirement was especially important: refreshing an already corrected note should not append the same verification statement again.
Conceptually, our regression test checks:
const first = refreshVerificationNote(existingNote);
const second = refreshVerificationNote(first);
expect(second).toBe(first);
This example illustrates the behavior rather than reproducing the complete backend test suite.
We deployed the correction, refreshed the affected Knowledge Card, synchronized the GitHub profile again, and verified the resulting README.
Engineering lesson: generated text deserves the same attention to repeatability and regression testing as other application data.
8. What we actually published
After completing the workflow, we verified the public GitHub profile README.
It contained three published Knowledge Cards, three public GitHub commit references, and one separately labeled public document relating to the Monero Docs proposal.
It also contained exactly one managed Knowledge Card section.
Our published cards cover:
- MyZubster ecosystem development and supporting repository activity.
- Space Station security, digital identity, and privacy-related modules.
- A Monero Wallet RPC documentation proposal that was not merged upstream.
Explore the MyZubster GitHub profile
The resulting README is not a certificate of technical expertise.
Instead, it provides a structured overview of activities and references that readers can inspect and evaluate for themselves.
9. Lessons for developers building similar systems
Several principles emerged from this work.
Keep claims and evidence separate. A user description and its supporting source have different roles. Your data model should preserve that distinction.
Validate both structure and availability. A correctly formatted GitHub URL doesn't guarantee that the resource exists or is public.
Don't inflate contribution status. A proposed documentation improvement can be worth discussing even when the upstream pull request is closed without a merge.
Preserve existing user content. When updating external documents, define the exact area your application controls and stop when the original document cannot be retrieved.
Make publication an explicit decision. AI-assisted generation and external publication should be separate operations.
Test repeated operations. Re-running synchronization or refreshing verification text should not introduce duplicate sections or statements.
Treat documentation quality as engineering quality. Small punctuation errors can undermine the clarity of public verification disclosures.
10. What's next for MyZubster?
Our Knowledge Card implementation is an evolving foundation.
We're continuing to explore ways to improve source management, clean up outdated evidence, clarify verification states, and connect structured technical activities with other parts of the MyZubster ecosystem.
The broader goal is to make documented knowledge easier to discover without introducing misleading automated expertise scores or unsupported claims.
We believe developers should be able to explain not only what they successfully delivered, but also the investigations, proposals, experiments, and technical decisions behind their work.
That history becomes especially valuable when the supporting evidence and its limitations are clearly presented.
Conclusion
This project started as an attempt to improve our GitHub profile.
It evolved into an exploration of evidence modeling, API validation, safe synchronization, idempotent operations, and transparent open-source documentation.
The most valuable result isn't simply having three Knowledge Cards displayed on GitHub.
It's having a workflow that encourages developers to document their activities while preserving the distinction between personal declarations, accessible technical artifacts, and independently established facts.
A useful developer portfolio should make technical work discoverable, supporting evidence inspectable, and verification limitations visible.
That's what we're working toward with MyZubster and Zorgax.
Project references
Author: Daniel Ioni
Project: MyZubster
The Monero Docs proposal discussed in this article was not merged into the upstream project. The linked public dossier records the proposal and explicitly discloses its verification limitations.