QA GitHub Portfolio: README, Demo Video and Real Metrics
A hiring manager might spend only a few minutes on your repository. A strong QA GitHub portfolio makes those minutes count, with a clear story, proof that it works and honest numbers. In this lesson you will prepare your project for public view, starting with the most important check of all: making sure that it contains no secrets.
📖 What You’ll Learn
- What belongs in a QA portfolio
- How to write a README that gets read
- How to record a short demo
- How to present honest metrics
💡 Clean Your QA GitHub Portfolio First
Explain Like I’m 5: Tidying Before Guests Arrive
Imagine: Before visitors come, you put away your private letters as well as the laundry.
What it really means: A public repository shows everything, including its history.
In testing: A key committed last year can still be found today.
Check these before you make anything public:
- Search your code and Git history for keys, tokens and passwords.
- Confirm that
.envwas never committed. - Remove employer code, data, names and screenshots.
- Use only synthetic test data.
- Delete any secret that was ever exposed, and create a new one.
Never publish your employer’s work
Even small snippets may belong to your company. Build a separate project on a demo application, and describe your work experience without confidential details.
🔍 Choose What to Show
Explain Like I’m 5: Three Good Drawings
Imagine: A folder with three good drawings beats a pile of forty scribbles.
What it really means: A few complete projects are better than many unfinished ones.
In testing: Pin only the projects that you can explain in detail.
| Project | What it proves |
|---|---|
| Playwright framework | Reliable automation |
| AI evaluation pack | You can test AI products |
| QA agent with guardrails | You can build safe AI systems |
The QA agent project from Level 8 is ideal, because it shows design, testing and safety together.
🧩 Write the README
A good README answers a reader’s questions in order. Use this structure.
# QA Automation AI Agent
An AI-assisted QA workflow that turns a requirement into reviewed
Playwright tests, runs them and writes an evidence-based report.
## Demo
[Link to a 3-minute video]
## Why I Built It
[The problem, in two sentences]
## How It Works
[Architecture diagram]
## Safety Design
- Code controls the workflow, not the model
- People approve writing and running generated code
- Test targets are limited by an allowlist
## Quick Start
[Commands that work from a fresh clone]
## Results
[Real numbers, and how you measured them]
## Known Limits
[What it cannot do yet]Known Limits is the section that many people leave out. It builds more trust than almost anything else.
🛠️ Record a Short Demo
Explain Like I’m 5: A Short Bedtime Story
Imagine: A short story with a clear ending keeps children listening. A long one sends them to sleep.
What it really means: Keep your demo short and show one clear journey.
In testing: Three minutes is enough to show the whole workflow.
- State the problem in one sentence.
- Show the requirement.
- Run the agent, and read one approval.
- Show one failure and its diagnosis.
- Reject an approval to show control.
- Open the report.
The script from AI Agent Acceptance Criteria already gives you this story. Use synthetic data, and hide any personal details on your screen.
📌 Show Real Metrics
| Weak claim | Strong claim |
|---|---|
| “Saves huge amounts of time” | “Cut one task from 60 to 25 minutes across 10 timed runs” |
| “Very accurate” | “Matched human diagnosis in 8 of 10 reviewed failures” |
| “Fully tested” | “32 unit tests, and one real browser smoke test” |
Say how you measured each number, and give the sample size. Small samples are fine if you are open about them. The AI testing ROI lesson shows how to measure fairly.
🌍 Real-Life Example: The Honest README
A candidate’s README says that the healer works on only one kind of failure, and that a real provider has been tested on just five requirements. The interviewer is impressed by that honesty, and spends the interview discussing how the candidate would improve it. It becomes the best conversation of the day.
🧪 Try It Yourself
- Search your repository history for secrets.
- Write your README using the template.
- Ask a friend to set up the project using only the README.
- Record a three-minute demo.
- Pin your best two or three repositories.
📋 Ready-to-Copy Prompt
You are a hiring manager reviewing a QA engineer's GitHub project.
README:
[paste your README with no secrets]
Tell me what you understand after 60 seconds, what is unclear and which
claims you do not believe yet. Say what evidence would convince you.
Do not invent results for me. Mark anything that I need to measure.⚠️ Common Mistakes
- Publishing a repository that contains secrets
- Using code that belongs to an employer
- Pinning many unfinished projects
- Making claims without numbers or method
- Hiding what the project cannot do
🎯 Key Takeaways
- Check for secrets, including in the history.
- A few complete projects beat many small ones.
- Keep your demo short, and show control.
- Honest metrics and known limits build trust.
🎤 Interview Questions
1. Walk me through your portfolio project.
Model answer: I start with the problem, then the architecture, then one design decision and its trade-off. I finish with the results and what I would do next.
2. How did you measure your results?
Model answer: I timed the same tasks with and without the tool and included review time. I state the sample size and know that it is small.
3. How did you make sure that no secrets were exposed?
Model answer: I used environment variables and a gitignore from the start, then scanned the code and its history before publishing. All test data is synthetic.
4. What are the limits of your project?
Model answer: I can name them directly. For example, it covers one workflow and needs human review. I also explain what I would build next.
5. Did you use AI to build it?
Model answer: Yes, and I am open about it. I reviewed the output, wrote tests and can explain each design decision. The tests caught real mistakes along the way.
📝 Assignment
Publish one project with a complete README and a demo video. Ask someone who has not seen it to clone it and run it. Fix the first thing that confuses them.
❓ FAQ
Can I share a portfolio built with AI help?
Yes, if you say so and can explain it all. Be ready to change the code live.
What if my code is not perfect?
Nobody expects perfection. Clear thinking, tests and honesty matter more.
🚀 Next Steps
Well done on finishing this lesson. Complete the assignment, then continue with QA Resume with AI Skills: Resume and LinkedIn for Testers.