Publish Project To GitHub

Publish Project to GitHub

Turn a finished local project into a clean public artifact. Treat repository creation, public visibility, and deployment as separate gates; a successful push is not proof that the public site works.

Deliverables

Produce the applicable items:

• a narrowly scoped Git repository
• an intentional public or private GitHub repository
• a project-specific README.md
• a real preview image when the project is visual
• a portable build or remix prompt when it adds value
• a configured GitHub Pages site for compatible web projects
• post-push and post-deploy read-back

1. Resolve scope and authority

Inspect the local project, repository state, remotes, and local instructions before writing.

Confirm or safely infer:

• the exact project directory and intended files
• repository name and owner
• whether the target should be public or private
• whether an existing repository must be updated or a new one created
• whether the user wants a live website, source hosting only, or both

Creating a public repository is authorized only when the user explicitly asks for public sharing, a public URL, open source, or equivalent. Otherwise ask for visibility before creating it.

Never force-push, overwrite an existing remote, change repository visibility, or replace an existing Pages configuration without exact authorization.

2. Audit before packaging

Run the bundled audit from the project root:

bash /path/to/publish-project-to-github/scripts/audit_public_project.sh .

Then inspect findings rather than treating the script as a substitute for judgment.

Block publication on:

• API keys, tokens, private keys, passwords, or .env files
• personal data or private client information
• absolute local filesystem paths required at runtime
• unlicensed or private assets
• missing runtime files
• unclear ownership of a repository name that already exists

Review all external runtime URLs and generated assets. State any required network dependency in the README.

Inspect the existing license before publishing. If the user explicitly wants others to reuse or modify the project and no license exists, ask which license to add rather than inventing one. If the goal is only public viewing, a missing license does not block deployment, but report that reuse rights are not granted explicitly.

3. Choose the packaging model

Clean existing repository

Use the existing checkout when its remote, history, and tracked files match the intended public project. Stage only the requested files.

Mixed or unrelated workspace

Create a clean project directory or sibling checkout when the source workspace contains unrelated experiments, deletions, private files, or history. Copy only the intended runtime files. Do not publish an entire mixed folder for convenience.

Existing public repository

Inspect its default branch, Pages source, README, license, and remote state before changing it. Pull or reconcile deliberately; never hide divergence with a force push.

For a static one-file experiment, prefer this minimal shape:

project-name/
├── index.html
├── README.md
├── PROMPT.md        # optional
├── assets/          # optional previews or runtime assets
└── .gitignore

4. Build the repository presentation

Write the README from the real project. Use assets/README-template.md as a starting structure, not as final copy.

Include:

• project name and one concrete sentence explaining the experience
• a live demo link near the top and, when useful outside GitHub, a repository source link
• a screenshot or short GIF captured from the actual running project
• key interactions or features
• a concise explanation of the architecture and unusual implementation choices
• accurate local run instructions
• project structure
• runtime dependencies and network requirements
• originality, attribution, or non-affiliation notes when references inspired the work

For agent-built projects, optionally add official links and a portable prompt showing how to rebuild or remix the project with relevant coding agents. Verify current official URLs before publishing.

Avoid generic claims such as “cutting-edge,” “stunning,” or “production-ready.” Prefer specific craft and behavior.

5. Verify locally

Use the project's real runtime rather than opening module-based sites directly from disk.

For static sites:

python3 -m http.server 4173 --bind 127.0.0.1

Check:

• initial render
• the primary interaction path
• the primary interaction's return, close, or recovery path
• a normal desktop viewport and a narrow viewport around 390 × 844 when the project is responsive
• every README run command
• missing files and 404s
• console errors and warnings
• relative URLs under a repository subpath such as /project-name/

Use the browser requested by the user or required by repository instructions. Capture the README preview from this verified runtime.