GitHubのポートフォリオはどう見せる?READMEの書き方と提出前の確認

ITエンジニアの選考・ポートフォリオ

GitHubに作品のコードを公開したものの「採用担当者はどこを見ればよいのだろう」「READMEには技術名だけ書けばよい?」と迷っていませんか。アプリが動いていても、リンク先で何ができるか分からなければ制作内容は伝わりにくくなります。

応募用のREADMEで優先したいのは、作品の目的・実際に動く機能・自分の担当範囲・確認方法を短時間で理解できるようにすることです。見た目を飾ることより、初めて見る人が「何を作ったのか」「どこまで完成したのか」「どう試すのか」を確かめられる状態を目指しましょう。

またGitHubのリポジトリを公開することと、アプリのデモを公開することは別です。READMEが完成しても、相手が閲覧できない設定や壊れた画像、秘密情報が残っていると提出には適しません。

この記事では2026年11月時点のGitHub公式ドキュメントをもとに、READMEの構成例から提出前の安全確認まで整理します。作品を実際に制作した体験談ではなく、掲載するREADMEやアプリは説明用の架空の例です。

GitHubで最初に見せたいのは「作品・担当・動作」の3つ

READMEはリポジトリの説明書です。GitHub公式もプロジェクトで何ができるか、なぜ有益なのか、使い始める方法などを記載する場所と説明しています。

採用担当者が最初に確認できるようにしたい情報を3つに絞ると、長い紹介文になりにくくなります。

伝えたいこと READMEの冒頭で示す内容 確認できるもの
作品 誰のどんな課題を解決するものか。主要機能は何か 1文の概要、画面画像、機能一覧
担当 自分が設計・実装・検証した範囲 担当工程、主要な実装、チームでの役割
動作 公開中のデモや手元で動かす方法 デモURL、起動手順、テスト方法

たとえば「ReactとNode.jsで作りました」だけでは利用者に何ができるか分かりません。「予定を登録して担当者ごとに進捗を確認できるタスク管理アプリ。画面とAPIを個人で実装」と書けば、作品と担当が伝わります。

公開リポジトリが複数ある場合は応募する職種に近いものを先に紹介しましょう。Webフロントエンドへの応募なら画面と操作例が分かる作品、バックエンドならAPI設計やデータ処理が分かる作品を中心にします。プロフィールに多くの作品を並べること自体が評価されるとは限りません。

公式情報:GitHub Docs「リポジトリのREADMEファイルについて」

READMEは何から書く?採用応募用の構成例

READMEにはGitHubが定めた採用専用の必須テンプレートはありません。応募先が独自の提出指示を出している場合はその指示を優先してください。

通常の個人制作を紹介するなら、次の順に配置すると読み手が迷いにくくなります。

配置する順番 書く内容 読む人が確認できること
1. 作品名・概要 何のアプリか、誰の課題を解決するか 何を作ったか
2. 画面・主要機能 スクリーンショット、操作できる機能 どのように使うか
3. デモURL 公開先、ログイン方法、操作上の制限 実際に試せるか
4. 使用技術 言語、フレームワーク、DB、インフラ、テスト どの技術で作ったか
5. 担当範囲・工夫 自分の実装、設計で判断したこと 本人が説明できる成果か
6. 起動・テスト方法 必要環境、設定、コマンド、テスト手順 手元で再現できるか
7. 制約・今後の改善 未実装、確認していない環境、改善予定 現在の完成範囲はどこか

最初に大量のバッジや技術ロゴを並べる必要はありません。最初の2~3行で作品を説明し、次に画面かデモへ進める構成をおすすめします。

書き始めに使えるREADMEのサンプル

以下は架空の「タスク共有アプリ」を使った簡略例です。コードブロック内のMarkdown記法を自分の作品に置き換えられます。サンプルのURL・ファイル名はそのまま提出せず、実在するものだけを記載してください。

# Team Task Board

少人数チームでタスクの担当者と進捗を共有するためのWebアプリです。
タスクの登録・検索・ステータス変更ができます。
個人制作として画面・API・データベースを実装しました。

## 画面
![タスク一覧画面](./docs/images/task-list.png)

## 主な機能
- タスクの登録・編集:実装済み
- 担当者・状態による絞り込み:実装済み
- メール通知:未実装

## デモ
公開URL:[実際のデモURLを記載]
閲覧方法:[ログイン不要/デモ用アカウント等]

## 技術構成
- フロントエンド:React
- バックエンド:Node.js
- データベース:PostgreSQL
- テスト:[実施した方法のみ記載]

## 担当範囲と工夫
- タスク一覧の画面と登録APIを実装
- 入力項目の検証とエラー表示を追加

## 起動方法
必要環境:[実際に確認したバージョン]
設定:[必要な環境変数名と準備方法]
起動:[実際に動作確認したコマンド]

## テストと制約
確認した機能:[検証した項目]
未対応:メール通知、複数管理者の権限設定

この例にある技術の組み合わせや機能は架空です。自分がReactを少し学習しただけなら「Reactで全画面を設計・実装」と書かず、実際に手を動かした範囲へ直してください。

READMEをルートディレクトリに置くと訪問者が見つけやすくなります。GitHubはルート以外に「.github」「docs」内のREADMEも認識しますが、複数ある場合は表示優先順位があるため、意図したREADMEが出ているかブラウザで確認しましょう。

機能・画面・技術選定は「利用者にできること」から説明する

READMEを読んだ人は、まずアプリが何をするものか知りたいはずです。使用技術を詳しく書く前に、利用者の操作を具体的に説明しましょう。

機能一覧では実装済みと未実装を区別する

タスク管理アプリなら「タスクを新規登録できる」「状態を絞って表示できる」「担当者を変更できる」と書きます。「使いやすいシステムです」とだけ書くより確認しやすくなります。

検索や予約、通知などの機能を追加する予定でも、現在動作しなければ「開発中」「未実装」と分けて記載してください。デモに存在しない機能を完成済みとして載せないことが大切です。

画面画像は実際の表示と一致させる

スクリーンショットは作品の全機能を載せるのではなく、主な操作が分かる2~3画面を選ぶと十分な場合があります。スマートフォンでも文字やボタンが判読できる大きさにし、必要なら一覧画面・登録画面を分けましょう。

画像に本物の顧客情報、メールアドレス、住所、アクセストークン、社内の機密画面を写さないでください。実在のデータではなく公開用に用意したダミーデータを使います。人物画像やアイコンなど他者の著作物にも利用許諾を確認してください。

READMEがリポジトリのルートにあり画像が「docs/images/task-list.png」に入っているなら、Markdownでは次のように書けます。

![タスク一覧画面](./docs/images/task-list.png)

GitHubはMarkdownの相対リンクと相対画像パスをサポートしています。ただしフォルダー名の大文字・小文字や画像のファイル名が実物と異なると表示されません。コードだけではなくGitHub上で表示された画面を開いて確認しましょう。

公式情報:GitHub Docs「基本的な書き込みと書式設定の構文」

技術名は用途と選んだ理由を添える

技術構成には言語・フレームワーク・データベース・実行環境・テストの区分を使えます。すべてのパッケージを列挙する必要はありません。応募職種に関係する主要な技術を中心にします。

たとえば「PostgreSQLを使った」だけでなく「担当者別のタスクを検索するためデータをリレーショナルに管理した」と説明できます。実装した理由を1~2行で添えると面接でも話しやすくなります。

教材に従って導入した技術なら、その事実と自分が変更・検討した部分を区別してください。触れていない技術を見栄えのためだけに追加しないことも重要です。

共同制作・訓練課題なら自分の担当範囲を明記する

複数人で作った作品は、リポジトリ全体の機能と本人が担当した部分を分けて説明します。たとえば共同制作で認証機能を別のメンバーが作ったなら、自分の担当欄へ「ログイン機能を実装」と書かないようにしましょう。

制作の形 READMEに書くこと
個人制作 自分で設計・実装した機能。教材や生成AIの支援を受けた部分があれば説明できるようにする
職業訓練・スクール課題 学習課題であること、制作期間、授業の共通部分と独自に追加した機能
チーム制作 チーム全体の作品概要、自分の担当機能、設計・レビュー・テストの範囲
有償の受託開発 契約で公開が許された範囲のみ。顧客名・ソース・成果物を許可なく公開しない

たとえば「4人での共同制作。自分は予約一覧画面と予約登録APIを担当し、テストケースを作成した」と説明できます。使用した技術の名前より、担当した成果物が分かることが大切です。

チームの成果物を公開するときは、メンバー間の取り決めや学校・会社の規約も確認してください。リポジトリを自分のアカウントにコピーできることと、応募用に自由公開してよいことは別です。コードが公開できない場合は許可された画面や説明資料だけで紹介する方法も検討します。

起動方法・テスト結果・デモURLは「相手が試せる順」に書く

コードを見せる作品では、READMEを読んだ人が自分の環境で動かせるかも重要です。「npm installで起動します」とだけ書いても、必要なNode.jsのバージョンやデータベースの準備が抜けていれば再現できないことがあります。

実際に動作確認した順番で、必要環境・依存パッケージ・環境変数・データベースの準備・起動・動作確認を記載しましょう。

READMEに書く項目 必要な説明
必要環境 OS、言語・ランタイム、DBなど実際に動作を確認したバージョン
取得と依存関係 クローン後のディレクトリ移動、依存パッケージの導入コマンド
設定 環境変数名だけの見本と設定方法。実際の鍵・パスワードは載せない
初期データ DBの作成・マイグレーション・ダミーデータ投入の手順
起動 実際に確認済みのコマンド、アクセス先、正常に起動した判断方法
テスト 実行コマンド、確認した機能、未実施のテストや制約

環境変数の説明では「.env.example」のようなサンプルファイルを用意し、変数名とダミー値だけを載せる方法があります。ただしこれも実際のプロジェクトに合わせて作成してください。実物のAPIキー、DBのパスワード、トークンをREADMEや設定例に貼り付けてはいけません。

テスト欄では「一覧・登録・編集の手動確認を実施」「APIの単体テストを実施」「モバイル表示は未確認」など、実際の結果を記載します。実施していないのに「全機能テスト済み」と断定しないことが大切です。

デモはリポジトリと別に公開状態を確認する

GitHubにコードが公開されていても、アプリがインターネット上で動いているとは限りません。デモを用意しているならURLと「何を試せるか」をREADMEに書きましょう。

たとえばログイン後にタスクを登録するアプリなら、採用担当者が個人のメールアドレスで登録せずに操作できる方法を検討します。公開画面だけで機能が伝わるならゲストログインを追加する必要はありません。

デモ用アカウントを用意する場合は本番利用者と分離し、公開用のダミーデータを使いましょう。管理者機能・大量削除・外部メール送信など必要のない操作はサーバー側でも制限します。画面上のボタンを隠すだけでは権限の制限になりません。

デモが停止中なら動いているふりをせず「現在停止中」と明記し、許可された画面画像・操作動画・ローカル起動手順など代替の確認方法を示します。応募時点の状態と違う案内を残さないようにしてください。

ログインが必要な作品をどう試してもらうかは次の記事で詳しく説明しています。

ポートフォリオにゲストログインは必要?採用担当が試せるデモの作り方
ポートフォリオにゲストログインは必要?ログイン不要の公開画面・テストアカウント・ゲストログインを比較。デモ用データ、操作範囲、削除やメール送信、初期化の方法と、採用担当が試せる公開前確認を整理します。

Public・Privateと秘密情報を提出前に確認する

READMEを書き終えたら公開範囲を確認します。GitHubのPublicリポジトリはインターネット上の誰でも閲覧できます。一方Privateリポジトリは許可されたアカウントなどに閲覧を限定します。

PrivateのURLを応募先へ送っただけでは相手が開けない場合があります。企業から公開範囲や共有先の指定があるならそれに従い、必要な権限の付与方法を事前に確認してください。

ただしPrivateにしていれば秘密情報を置いてよいわけではありません。GitHub公式はAPIの認証情報やトークンを安全に管理し、コードへ埋め込まないことを案内しています。

公開前に調べる場所 確認内容
設定ファイル・.env APIキー、パスワード、DB接続情報などの実値が入っていないか
ソース・テストデータ 個人情報、顧客情報、実際の認証情報を使用していないか
画像・ログ 利用者名、メールアドレス、管理画面、内部URLが写っていないか
コミット履歴 現在のファイルから消した秘密情報が過去のコミットにないか
素材・共同制作物 第三者のコード・画像・学校課題の公開許可、ライセンス条件
リポジトリ権限 公開・非公開の指定、応募先に必要な閲覧権限

誤って秘密キーをコミットした場合は、最新のファイルから削除するだけでは不十分です。Gitの履歴やフォーク、複製先に残る可能性があります。まず該当する鍵・トークンを失効または再発行(ローテーション)し、必要に応じてGitHub公式の履歴削除手順を検討します。履歴の書き換えは共同開発者にも影響するため、手順を理解せず強制更新しないでください。

日頃から.envなど実際の秘密を含むファイルを追跡対象にしない設定を使い、コミットする変更を事前に確認しましょう。既にGitに登録したファイルは.gitignoreを追加しただけで履歴から消えるわけではありません。

GitHub公式:「リポジトリについて」/「Keeping your API credentials secure」/「Removing sensitive data from a repository」

なお企業からコーディング課題を提出するよう指定されている場合は、通常の個人ポートフォリオとは公開条件が異なることがあります。勝手にPublicへ変更せず提出要項を確認してください。

コーディング課題をGitHubで提出するときの確認事項|公開範囲・README・動作確認
コーディング課題をGitHubで提出する前に、公開範囲・README・動作確認・秘密情報・未実装部分を点検。応募先の指定を優先する確認表とREADME構成例、提出メッセージ例を紹介します。

提出前は第三者の立場でURL・画像・動作を確かめる

READMEの内容がそろったら、普段開発しているアカウント以外の視点で確認します。自分はGitHubにログインしているためPrivateリポジトリを開けても、応募先は見られない場合があります。

Publicのリポジトリはログアウト状態やシークレットウィンドウで開き、README・画像・リンクが見えるか確認します。Privateのリポジトリはログアウト状態で見えないことが正常なので、応募先に必要なアクセス権が付与されているかを設定から確認します。自分が閲覧できたことだけでは共有の検証になりません。

デモURLは別に開き、トップ画面から代表的な操作を試してください。テストアカウントを使う場合はログアウト後に再ログインできるか、別の人が同じデモを試すときにデータが壊れないかも確認します。

提出前の確認 完了の判断
リポジトリURL 応募先に必要な閲覧権限があり、指定した作品が開く
README冒頭 作品の目的・主要機能・本人の担当がすぐ分かる
画像・内部リンク 画像が表示され、機能説明や別資料へのリンクが切れていない
デモ 未ログインでの閲覧やテストアカウントでの操作が想定どおり
ローカル起動 新しく取得したコードでも手順どおり再現できる
セキュリティ 秘密情報・実データ・公開不可の素材がないことを確認
未実装・制約 動作しない機能、確認していない環境を隠していない

READMEの起動手順を確認するなら、普段の開発用フォルダーではなく別の新しいフォルダーへリポジトリを取得して試す方法があります。ローカルだけに残った設定ファイルや未コミットの修正に依存していないか気づきやすくなります。

面接では作品を60~90秒で紹介できるようにする

提出後に作品について聞かれたら「なぜ作ったか → 何を実装したか → 技術を選んだ理由 → 苦労と検証 → 今後の改善」を短く説明できるようにしておきましょう。60~90秒は練習の目安であり採用側の公式な評価基準ではありません。

共同制作なら自分の担当を中心に話します。未実装機能について質問された場合も「今は対応していない」「次にこう改善したい」と答えられる状態にしておく方が説明に一貫性が出ます。

READMEが整って提出先の閲覧確認も終わったら、応募書類の指定欄に作品URLを記載します。履歴書や自己PR欄でのURLの載せ方は次の記事で確認できます。

プログラマーの履歴書にGitHubはどこに書く?URLと紹介文の記入例
プログラマーの履歴書にGitHubを載せる場所を、応募先の指定・URL欄・自己PR欄に分けて解説。プロフィールとリポジトリの選び方、3種類の記入例、紙・PDFでのURL表記、提出前の確認をまとめました。

まとめ|READMEは「読める・試せる・担当が分かる」を目標に

GitHubのREADMEでは、作品の目的と主要機能を先に伝え、画面・使用技術・担当範囲・デモ・起動方法・テスト結果へ進めると理解しやすくなります。採用担当者が実際に何を確認できるかを考え、作品に合う情報だけを載せてください。

公開リポジトリのURLが開くこととアプリのデモが動くことは別です。Privateの閲覧権限、画像の表示、実際の起動手順、ログインの方法を提出前に確認しましょう。

作品の価値・自分の担当・再現方法が伝わり、秘密情報が含まれていないこと。この4点を確認できればREADMEは応募先に見せるための説明資料になります。見た目の飾りより、実際の制作内容を正確に伝えることを優先してください。

参考にした公式資料

確認日:2026年11月5日。READMEの構成や面接の説明時間は編集上の推奨例です。応募先が提出方式・公開範囲・利用技術・ライセンス等を指定している場合はその条件を優先してください。