{"id":41665313,"url":"https://github.com/domelic/github-repository-setup","last_synced_at":"2026-01-24T17:16:57.327Z","repository":{"id":333396302,"uuid":"1137104737","full_name":"domelic/github-repository-setup","owner":"domelic","description":"Comprehensive guide and Claude Code skill for setting up GitHub repositories with best practices","archived":false,"fork":false,"pushed_at":"2026-01-19T07:42:23.000Z","size":85,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T11:08:58.204Z","etag":null,"topics":["automation","best-practices","claude-code","devops","documentation","github","github-actions","repository","setup-guide"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/domelic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T23:05:54.000Z","updated_at":"2026-01-19T07:35:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/domelic/github-repository-setup","commit_stats":null,"previous_names":["domelic/github-repository-setup"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/domelic/github-repository-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domelic%2Fgithub-repository-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domelic%2Fgithub-repository-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domelic%2Fgithub-repository-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domelic%2Fgithub-repository-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/domelic","download_url":"https://codeload.github.com/domelic/github-repository-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domelic%2Fgithub-repository-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28732327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","best-practices","claude-code","devops","documentation","github","github-actions","repository","setup-guide"],"created_at":"2026-01-24T17:16:56.853Z","updated_at":"2026-01-24T17:16:57.301Z","avatar_url":"https://github.com/domelic.png","language":"JavaScript","readme":"# GitHub Repository Setup Guide\n\nA comprehensive guide and Claude Code skill for setting up GitHub repositories with production-grade automation.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/domelic/github-repository-setup/actions/workflows/release-please.yml/badge.svg)](https://github.com/domelic/github-repository-setup/actions/workflows/release-please.yml)\n[![GitHub release](https://img.shields.io/github/v/release/domelic/github-repository-setup)](https://github.com/domelic/github-repository-setup/releases)\n[![Contributors](https://img.shields.io/github/contributors/domelic/github-repository-setup)](https://github.com/domelic/github-repository-setup/graphs/contributors)\n\n---\n\n## Overview\n\nThis guide covers everything needed to set up a professional GitHub repository:\n\n| Category | What's Included |\n|----------|-----------------|\n| **Documentation** | README, LICENSE, CONTRIBUTING, CHANGELOG, CODE_OF_CONDUCT, RELEASING |\n| **Branch Protection** | PR requirements, CODEOWNERS, admin enforcement |\n| **Issue/PR Management** | Templates, labels, PR template, stale bot, welcome bot |\n| **Quality Gates** | Commitlint, spell check, link checker, markdown lint |\n| **Release Automation** | Release Please, auto-CHANGELOG, semantic versioning |\n| **CI/CD** | Build workflows, PDF/artifact previews, Dependabot |\n| **Discovery** | Topics, social preview, FUNDING.yml, CITATION.cff |\n| **Code Intelligence** | [Serena MCP](docs/SERENA.md) for semantic code understanding |\n| **Research Tools** | [Zotero MCP](docs/ZOTERO_MCP.md) for bibliography management |\n| **Knowledge Management** | [Obsidian MCP](docs/OBSIDIAN_MCP.md) for vault integration |\n\n---\n\n## Quick Start\n\n### Using the Claude Code Skill\n\n```bash\n/github-setup                    # Full setup wizard (auto-detects project type)\n/github-setup docs               # Documentation files\n/github-setup protection         # Branch protection + CODEOWNERS\n/github-setup issues             # Templates, labels, Discussions\n/github-setup quality            # Linting, spell check, link checker\n/github-setup releases           # Release Please automation\n/github-setup automation         # All GitHub Actions\n/github-setup discovery          # Topics, social preview, funding\n/github-setup checklist          # Show what's missing\n```\n\n### Language Presets\n\n```bash\n/github-setup nodejs             # Node.js/TypeScript preset\n/github-setup python             # Python preset\n/github-setup go                 # Go preset\n/github-setup rust               # Rust preset\n```\n\n### Category Presets\n\n```bash\n/github-setup ci                 # CI workflows only\n/github-setup security           # Security workflows only\n/github-setup deploy             # Deployment workflows only\n```\n\n### Manual Setup\n\n1. Copy templates from [`templates/`](templates/) directory\n2. Follow the [Complete Checklist](#complete-setup-checklist)\n3. Customize for your project\n\n---\n\n## Table of Contents\n\n1. [Documentation Files](#1-documentation-files)\n2. [Branch Protection](#2-branch-protection)\n3. [Issue \u0026 PR Management](#3-issue--pr-management)\n4. [Quality Gate Workflows](#4-quality-gate-workflows)\n5. [Release Automation](#5-release-automation)\n6. [CI/CD Workflows](#6-cicd-workflows)\n7. [Language-Specific CI](#7-language-specific-ci)\n8. [Publishing Workflows](#8-publishing-workflows)\n9. [Deployment Templates](#9-deployment-templates)\n10. [Dev Containers](#10-dev-containers)\n11. [Editor Configuration](#11-editor-configuration)\n12. [Discovery \u0026 Sponsorship](#12-discovery--sponsorship)\n13. [Publishing (Books/eBooks)](#13-publishing-booksebooks)\n14. [Serena Code Intelligence](#14-serena-code-intelligence)\n15. [Zotero Research Library](#15-zotero-research-library)\n16. [Obsidian Knowledge Base](#16-obsidian-knowledge-base)\n17. [Complete Setup Checklist](#complete-setup-checklist)\n18. [Workflow Reference](#workflow-reference)\n19. [Troubleshooting](#troubleshooting)\n\n---\n\n## 1. Documentation Files\n\n### Required Files\n\n| File | Purpose | Template |\n|------|---------|----------|\n| `README.md` | Project overview, badges, usage | — |\n| `LICENSE` | Legal terms | [choosealicense.com](https://choosealicense.com/) |\n| `CONTRIBUTING.md` | How to contribute | [Template](templates/CONTRIBUTING.md) |\n| `CHANGELOG.md` | Version history | [Keep a Changelog](https://keepachangelog.com/) |\n\n### Recommended Files\n\n| File | Purpose | Template |\n|------|---------|----------|\n| `CODE_OF_CONDUCT.md` | Community guidelines | [Contributor Covenant](https://www.contributor-covenant.org/) |\n| `RELEASING.md` | Release process docs | [Template](templates/RELEASING.md) |\n| `CITATION.cff` | Machine-readable citation | [Template](templates/CITATION.cff) |\n| `CLAUDE.md` | Claude Code instructions | [Template](templates/CLAUDE.md) |\n| `SECURITY.md` | Vulnerability reporting | For software projects |\n\n### CITATION.cff (For Academic/Citable Projects)\n\n```yaml\ncff-version: 1.2.0\ntitle: \"Your Project Title\"\nmessage: \"If you use this software, please cite it as below.\"\nauthors:\n  - family-names: LastName\n    given-names: FirstName\n    orcid: \"https://orcid.org/0000-0000-0000-0000\"\nversion: \"1.0.0\"\ndoi: \"10.5281/zenodo.XXXXXXX\"\ndate-released: \"2024-01-01\"\nurl: \"https://github.com/owner/repo\"\n```\n\nGitHub displays a \"Cite this repository\" button when this file exists.\n\n---\n\n## 2. Branch Protection\n\n### Configuration via CLI\n\n```bash\ngh api repos/OWNER/REPO/branches/main/protection -X PUT --input - \u003c\u003c'EOF'\n{\n  \"required_status_checks\": {\n    \"strict\": true,\n    \"contexts\": [\"build\", \"test\"]\n  },\n  \"enforce_admins\": true,\n  \"required_pull_request_reviews\": {\n    \"required_approving_review_count\": 0\n  },\n  \"restrictions\": null,\n  \"allow_force_pushes\": false,\n  \"allow_deletions\": false\n}\nEOF\n```\n\n### Auto-Delete Merged Branches\n\n```bash\ngh api repos/OWNER/REPO -X PATCH -f delete_branch_on_merge=true\n```\n\n### Branch Naming Convention\n\nBranch names should match conventional commit types:\n\n| Type | Branch Prefix | Example |\n|------|---------------|---------|\n| `feat` | `feat/` | `feat/user-authentication` |\n| `fix` | `fix/` | `fix/memory-leak` |\n| `docs` | `docs/` | `docs/api-guide` |\n| `chore` | `chore/` | `chore/update-deps` |\n| `ci` | `ci/` | `ci/add-workflow` |\n| `refactor` | `refactor/` | `refactor/parser-logic` |\n\n**Rules:** lowercase, hyphens between words, concise but descriptive\n\n### Branching Strategy\n\n**When to use feature branches vs. small PRs:**\n\n| Work Type | Approach | Why |\n|-----------|----------|-----|\n| **Exploratory/investigative** | Feature branch | Accumulate changes, merge once when stable |\n| **Interconnected fixes** | Feature branch | Related changes should ship together |\n| **Independent, unrelated fixes** | Small PRs | Each has standalone value |\n| **Production hotfixes** | Small PRs | Need immediate deployment |\n| **New features** | Feature branch | Develop fully before merging |\n| **CI/infrastructure changes** | Feature branch | Test everything works before merging |\n\n**Anti-pattern to avoid:**\n\n```text\n# BAD: Many small PRs for interconnected exploratory work\nfix #1 → PR → merge → v1.0.1\nfix #2 → PR → merge → v1.0.2  (discovered while fixing #1)\nfix #3 → PR → merge → v1.0.3  (discovered while fixing #2)\nfix #4 → PR → merge → v1.0.4  (related to #1-3)\n\n# GOOD: Feature branch for exploratory work\nfix/infrastructure-improvements branch\n  ├── fix #1 (commit)\n  ├── fix #2 (commit)\n  ├── fix #3 (commit)\n  └── fix #4 (commit)\n        ↓\n    single PR → merge → v1.0.1\n```\n\n**Key insight:** If you're discovering related issues as you work, you're doing exploratory work—use a feature branch. If fixes are truly independent and each could ship alone, use small PRs.\n\n### Settings by Team Size\n\n| Setting | Solo | Small Team | Large Team |\n|---------|------|------------|------------|\n| PRs required | ✅ | ✅ | ✅ |\n| Approvals | 0 | 1 | 2+ |\n| CODEOWNERS | Optional | ✅ | ✅ |\n| Status checks | Optional | ✅ | ✅ |\n| Enforce admins | ✅ | ✅ | ✅ |\n\n### CODEOWNERS\n\nLocation: `.github/CODEOWNERS`\n\n```text\n# Default owner\n* @username\n\n# By path\n/docs/ @docs-team\n/src/api/ @backend-team\n\n# By file type\n*.ts @typescript-team\n```\n\n---\n\n## 3. Issue \u0026 PR Management\n\n### Issue Templates\n\nLocation: `.github/ISSUE_TEMPLATE/`\n\nSee [`templates/ISSUE_TEMPLATE/`](templates/ISSUE_TEMPLATE/) for complete examples:\n\n- `bug_report.md` — Bug reports\n- `feature_request.md` — Feature requests\n- `config.yml` — Template chooser config\n\n### PR Template\n\nLocation: `.github/PULL_REQUEST_TEMPLATE.md`\n\n```markdown\n## Summary\n\u003c!-- Brief description --\u003e\n\n## Type of Change\n- [ ] Bug fix\n- [ ] New feature\n- [ ] Documentation\n- [ ] Refactoring\n\n## Checklist\n- [ ] Tests pass\n- [ ] Documentation updated\n- [ ] Commits follow conventional format\n```\n\n### Labels\n\n```bash\n# Essential labels\ngh label create \"bug\" -c \"d73a4a\" -d \"Something isn't working\"\ngh label create \"enhancement\" -c \"a2eeef\" -d \"New feature or request\"\ngh label create \"documentation\" -c \"0075ca\" -d \"Documentation improvements\"\ngh label create \"good first issue\" -c \"7057ff\" -d \"Good for newcomers\"\ngh label create \"help wanted\" -c \"008672\" -d \"Extra attention needed\"\n\n# Priority labels\ngh label create \"priority: critical\" -c \"b60205\" -d \"Must be fixed immediately\"\ngh label create \"priority: high\" -c \"d93f0b\" -d \"High priority\"\ngh label create \"priority: medium\" -c \"fbca04\" -d \"Medium priority\"\ngh label create \"priority: low\" -c \"c5def5\" -d \"Low priority\"\n\n# Status labels\ngh label create \"in-progress\" -c \"0e8a16\" -d \"Work in progress\"\ngh label create \"blocked\" -c \"b60205\" -d \"Blocked by dependency\"\ngh label create \"stale\" -c \"ededed\" -d \"Inactive issue/PR\"\ngh label create \"pinned\" -c \"006b75\" -d \"Exempt from stale bot\"\n\n# Automation labels\ngh label create \"dependencies\" -c \"0366d6\" -d \"Dependency updates\"\ngh label create \"github-actions\" -c \"000000\" -d \"CI/CD changes\"\n```\n\n### Enable Discussions\n\n```bash\ngh api repos/OWNER/REPO -X PATCH -f has_discussions=true\n```\n\n### Stale Bot\n\nSee [`templates/workflows/stale.yml`](templates/workflows/stale.yml)\n\nAutomatically marks and closes inactive issues/PRs:\n\n- Marks stale after 45 days\n- Closes after 14 more days (60 total)\n- Exempt: `pinned`, `security`, `in-progress` labels\n\n### Welcome Bot\n\nSee [`templates/workflows/welcome.yml`](templates/workflows/welcome.yml)\n\nGreets first-time contributors with helpful information.\n\n---\n\n## 4. Quality Gate Workflows\n\n### Commitlint (Conventional Commits)\n\nEnforces commit message format: `type: description`\n\n**Workflow:** [`templates/workflows/commitlint.yml`](templates/workflows/commitlint.yml)\n**Config:** [`templates/commitlint.config.js`](templates/commitlint.config.js)\n\n```bash\n# Valid commits\nfeat: add user authentication\nfix: resolve memory leak in parser\ndocs: update API documentation\n\n# Invalid commits\nadded feature        # No type\nfeat add feature     # Missing colon\nFEAT: add feature    # Wrong case\n```\n\n### Spell Check\n\nUses cspell with custom dictionary support.\n\n**Workflow:** [`templates/workflows/spell-check.yml`](templates/workflows/spell-check.yml)\n**Config:** [`templates/.cspell.json`](templates/.cspell.json)\n\n### Link Checker\n\nValidates all links in markdown files.\n\n**Workflow:** [`templates/workflows/link-checker.yml`](templates/workflows/link-checker.yml)\n\n- Runs on push/PR to markdown files\n- Weekly scheduled scan\n- Auto-creates issue if broken links found\n\n### Markdown Lint\n\nEnforces consistent markdown formatting.\n\n**Workflow:** [`templates/workflows/markdown-lint.yml`](templates/workflows/markdown-lint.yml)\n**Config:** [`templates/.markdownlint.json`](templates/.markdownlint.json)\n**Guide:** [docs/MARKDOWN_LINT.md](docs/MARKDOWN_LINT.md) — Common rules and fixes\n\n---\n\n## 5. Release Automation\n\n### Release Please (Recommended)\n\nFully automated releases from conventional commits.\n\n**Workflow:** [`templates/workflows/release-please.yml`](templates/workflows/release-please.yml)\n**Config:** [`templates/release-please-config.json`](templates/release-please-config.json)\n\n**How it works:**\n\n```text\nfeat: add feature → Push → Release PR created → Merge → v1.1.0 released\n```\n\n| Commit Type | Version Bump |\n|-------------|--------------|\n| `feat:` | Minor (1.0.0 → 1.1.0) |\n| `fix:` | Patch (1.0.0 → 1.0.1) |\n| `feat!:` or `BREAKING CHANGE:` | Major (1.0.0 → 2.0.0) |\n| `chore:`, `ci:` | No release |\n\n### Manual Release Workflow\n\nIf you prefer manual control:\n\n**Workflow:** [`templates/workflows/release-manual.yml`](templates/workflows/release-manual.yml)\n\n```bash\ngit tag v1.0.0\ngit push origin v1.0.0\n# Release created automatically\n```\n\n---\n\n## 6. CI/CD Workflows\n\n### Dependabot (Auto-update Actions)\n\n**Config:** [`templates/dependabot.yml`](templates/dependabot.yml)\n\n- Updates GitHub Actions weekly\n- Groups updates into single PR\n- Uses conventional commit format\n\n### Build/Test Workflow\n\n**Workflow:** [`templates/workflows/ci.yml`](templates/workflows/ci.yml)\n\n### Artifact Preview on PRs\n\nUpload build artifacts for review before merge.\n\n**Workflow:** [`templates/workflows/artifact-preview.yml`](templates/workflows/artifact-preview.yml)\n\n---\n\n## 7. Language-Specific CI\n\nPre-configured CI workflows for major programming languages with version matrix testing.\n\n### Node.js CI\n\n**Workflow:** [`templates/workflows/ci-nodejs.yml`](templates/workflows/ci-nodejs.yml)\n\n| Feature | Details |\n|---------|---------|\n| Node versions | 18, 20, 22 |\n| Package manager | npm with caching |\n| Steps | Install, lint, type-check, test, build |\n\n### Python CI\n\n**Workflow:** [`templates/workflows/ci-python.yml`](templates/workflows/ci-python.yml)\n\n| Feature | Details |\n|---------|---------|\n| Python versions | 3.10, 3.11, 3.12 |\n| Package manager | pip with caching |\n| Linting | ruff (linter + formatter) |\n| Type checking | mypy |\n| Testing | pytest with coverage |\n\n### Go CI\n\n**Workflow:** [`templates/workflows/ci-go.yml`](templates/workflows/ci-go.yml)\n\n| Feature | Details |\n|---------|---------|\n| Go versions | 1.21, 1.22 |\n| Linting | golangci-lint |\n| Testing | go test with race detection |\n\n### Rust CI\n\n**Workflow:** [`templates/workflows/ci-rust.yml`](templates/workflows/ci-rust.yml)\n\n| Feature | Details |\n|---------|---------|\n| Toolchains | stable, nightly (+ optional MSRV) |\n| Linting | clippy |\n| Formatting | rustfmt |\n| Caching | Swatinem/rust-cache |\n\n### Shared Features\n\nAll language-specific CI workflows include:\n\n- **Concurrency control** — Cancel in-progress runs for same ref\n- **Matrix testing** — Test across multiple language versions\n- **Fail-fast disabled** — All matrix jobs complete\n- **Caching** — Package manager caches for speed\n\n---\n\n## 8. Publishing Workflows\n\nAutomated package publishing on GitHub release.\n\n### npm Publishing\n\n**Workflow:** [`templates/workflows/publish-npm.yml`](templates/workflows/publish-npm.yml)\n\n- Publishes with provenance (supply chain security)\n- Verifies version matches tag\n- Supports GitHub Packages (optional)\n\n**Required secret:** `NPM_TOKEN`\n\n### PyPI Publishing\n\n**Workflow:** [`templates/workflows/publish-pypi.yml`](templates/workflows/publish-pypi.yml)\n\n- Uses OIDC trusted publishing (no secrets needed)\n- Builds with `python -m build`\n- Supports TestPyPI (optional)\n\n**Setup:** Configure trusted publishing at [pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing)\n\n### Docker Publishing\n\n**Workflow:** [`templates/workflows/publish-docker.yml`](templates/workflows/publish-docker.yml)\n\n- Publishes to GitHub Container Registry (GHCR)\n- Optional Docker Hub publishing\n- Multi-platform builds (amd64, arm64)\n- Automatic tagging (semver, sha)\n- Build provenance and SBOM\n\n### crates.io Publishing\n\n**Workflow:** [`templates/workflows/publish-crates.yml`](templates/workflows/publish-crates.yml)\n\n- Verifies Cargo.toml version matches tag\n- Runs `cargo package` check first\n- Supports workspaces with cargo-workspaces\n\n**Required secret:** `CRATES_IO_TOKEN`\n\n---\n\n## 9. Deployment Templates\n\nAutomated deployment workflows for static sites and applications.\n\n### GitHub Pages\n\n**Workflow:** [`templates/workflows/deploy-github-pages.yml`](templates/workflows/deploy-github-pages.yml)\n\n- Supports Node.js, Python (MkDocs), Rust (mdBook)\n- Uses GitHub Pages official actions\n- Configurable build output directory\n\n### Vercel\n\n**Workflow:** [`templates/workflows/deploy-vercel.yml`](templates/workflows/deploy-vercel.yml)\n\n- Preview deployments on PRs\n- Production deployments on merge to main\n- PR comments with preview URLs\n\n**Required secrets:** `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`\n\n### Netlify\n\n**Workflow:** [`templates/workflows/deploy-netlify.yml`](templates/workflows/deploy-netlify.yml)\n\n- Preview deployments on PRs\n- Production deployments on merge to main\n- PR comments with preview URLs\n\n**Required secrets:** `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID`\n\n---\n\n## 10. Dev Containers\n\nPre-configured development containers for consistent environments.\n\n### Available Containers\n\n| File | Language | Base Image |\n|------|----------|------------|\n| [`devcontainer.json`](templates/.devcontainer/devcontainer.json) | Generic | Ubuntu base |\n| [`devcontainer-nodejs.json`](templates/.devcontainer/devcontainer-nodejs.json) | Node.js | Node 22 |\n| [`devcontainer-python.json`](templates/.devcontainer/devcontainer-python.json) | Python | Python 3.12 |\n| [`devcontainer-go.json`](templates/.devcontainer/devcontainer-go.json) | Go | Go 1.22 |\n| [`devcontainer-rust.json`](templates/.devcontainer/devcontainer-rust.json) | Rust | Rust latest |\n\n### Usage\n\n1. Copy the appropriate config to `.devcontainer/devcontainer.json`\n2. Open in VS Code with Remote - Containers extension\n3. Or use GitHub Codespaces\n\n### Features Included\n\n- **Common utilities** — zsh, Oh My Zsh, git, GitHub CLI\n- **Language tools** — Formatters, linters, language servers\n- **VS Code extensions** — Pre-installed recommendations\n- **Port forwarding** — Common development ports configured\n\n---\n\n## 11. Editor Configuration\n\nConsistent editor settings across the team.\n\n### EditorConfig\n\n**File:** [`templates/.editorconfig`](templates/.editorconfig)\n\nUniversal formatting rules:\n\n| Setting | Default | Python | Go |\n|---------|---------|--------|-----|\n| Indent style | spaces | spaces | tabs |\n| Indent size | 2 | 4 | 4 |\n| End of line | LF | LF | LF |\n\n### VS Code Settings\n\n**Files:**\n\n- [`templates/.vscode/settings.json`](templates/.vscode/settings.json) — Workspace settings\n- [`templates/.vscode/extensions.json`](templates/.vscode/extensions.json) — Recommended extensions\n\nLanguage-specific formatters configured:\n\n| Language | Formatter |\n|----------|-----------|\n| JavaScript/TypeScript | Prettier |\n| Python | Black + isort |\n| Go | gofmt |\n| Rust | rustfmt |\n| YAML | Red Hat YAML |\n\n---\n\n## 12. Discovery \u0026 Sponsorship\n\n### Repository Topics\n\n```bash\ngh api repos/OWNER/REPO/topics -X PUT --input - \u003c\u003c'EOF'\n{\n  \"names\": [\"topic1\", \"topic2\", \"topic3\"]\n}\nEOF\n```\n\n### Social Preview\n\n- Recommended size: 1280×640 pixels\n- Upload: **Settings \u003e General \u003e Social preview**\n- Or provide SVG at `.github/social-preview.svg`\n\n### FUNDING.yml\n\nLocation: `.github/FUNDING.yml`\n\n```yaml\ngithub: [username]\npatreon: username\nko_fi: username\ncustom: ['https://example.com/donate']\n```\n\n### GitHub Pages\n\n```bash\ngh api repos/OWNER/REPO/pages -X POST --input - \u003c\u003c'EOF'\n{\n  \"source\": { \"branch\": \"main\", \"path\": \"/\" }\n}\nEOF\n```\n\n---\n\n## 13. Publishing (Books/eBooks)\n\n### Amazon KDP Automation\n\nFor book/ebook projects, automate EPUB generation on release:\n\n**Workflow:** [`templates/workflows/amazon-kdp-publish.yml`](templates/workflows/amazon-kdp-publish.yml)\n\n**What it does:**\n\n1. Builds EPUB from source (LaTeX/Markdown) using Pandoc\n2. Attaches EPUB to GitHub release\n3. Creates issue with KDP upload checklist\n\n**Why semi-automated?**\nAmazon KDP has no public API. The workflow automates everything possible while the actual upload requires manual action.\n\n\u003e ⚠️ **KDP Select Warning:** Do NOT enroll in KDP Select if you also distribute free EPUB/PDF on GitHub. KDP Select requires exclusivity—you cannot distribute the ebook elsewhere. Use standard KDP publishing instead.\n\n**Customization:**\n\n```yaml\nenv:\n  BOOK_TITLE: \"Your Book Title\"\n  BOOK_SUBTITLE: \"Your Subtitle\"\n  BOOK_AUTHOR: \"Your Name\"\n  SOURCE_FILE: \"book.tex\"\n  COVER_IMAGE: \"cover.jpg\"\n```\n\n**Best Practice:** Build EPUB in `release-please.yml` post-release job (not just `amazon-kdp-publish.yml`) to ensure it's always attached to releases. The `amazon-kdp-publish.yml` workflow may not trigger reliably from Release Please-created releases.\n\n---\n\n## 14. Serena Code Intelligence\n\nSerena is an MCP server that provides semantic code understanding for Claude Code.\n\n**Full Documentation:** [docs/SERENA.md](docs/SERENA.md)\n\n### Quick Setup\n\n1. Add to Claude Code MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"serena\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"serena-mcp\", \"serena\"]\n    }\n  }\n}\n```\n\n2. Activate in your project:\n\n```text\nSerena: activate_project /path/to/project\n```\n\n3. Copy templates to your project:\n\n```bash\ncp -r templates/serena/ .serena/\n```\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Symbolic Navigation** | Find symbols by name, trace references |\n| **Intelligent Editing** | Replace symbol bodies, semantic refactoring |\n| **Memory System** | Persistent markdown notes across sessions |\n| **Multi-Language** | TypeScript, Python, Go, Java, C/C++ via LSP |\n\n### Templates\n\n- [`templates/serena/project.yml`](templates/serena/project.yml) — Project configuration\n- [`templates/serena/.gitignore`](templates/serena/.gitignore) — Cache exclusion\n- [`templates/serena/memories/README.md`](templates/serena/memories/README.md) — Memory system guide\n\n---\n\n## 15. Zotero Research Library\n\nZotero MCP connects your research library with Claude Code for AI-powered literature management.\n\n**Full Documentation:** [docs/ZOTERO_MCP.md](docs/ZOTERO_MCP.md)\n\n### Quick Setup\n\n1. Install Zotero MCP:\n\n```bash\nuv tool install \"git+https://github.com/54yyyu/zotero-mcp.git\"\nzotero-mcp setup\n```\n\n2. Add to Claude Code MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero\": {\n      \"command\": \"zotero-mcp\",\n      \"env\": {\n        \"ZOTERO_LOCAL\": \"true\"\n      }\n    }\n  }\n}\n```\n\n3. Enable semantic search (optional):\n\n```bash\nzotero-mcp update-db --fulltext\n```\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Semantic Search** | AI-powered similarity search across papers |\n| **BibTeX Export** | Export citations directly to `.bib` files |\n| **PDF Annotations** | Extract highlights and notes from PDFs |\n| **Collection Management** | Browse and search by tags, collections |\n\n### When to Use\n\n**Good fit:**\n- Academic/research projects with citations\n- Books/treatises with bibliography (like `references.bib`)\n- Literature reviews and research synthesis\n\n**Not needed:**\n- Software projects without academic references\n- Small reference lists (manual BibTeX works fine)\n\n---\n\n## 16. Obsidian Knowledge Base\n\nObsidian MCP connects your Obsidian vault with Claude Code for AI-assisted knowledge management.\n\n**Full Documentation:** [docs/OBSIDIAN_MCP.md](docs/OBSIDIAN_MCP.md)\n\n### Quick Setup\n\nInstall the Obsidian plugin (recommended for Claude Code users):\n\n1. In Obsidian, go to **Settings \u003e Community plugins \u003e Browse**\n2. Search for \"Claude Code MCP\"\n3. Install and enable the plugin\n\nClaude Code automatically discovers vaults via WebSocket.\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Vault Search** | Search and reference notes while working |\n| **File Operations** | Read, edit, create files in your vault |\n| **Auto-Discovery** | No manual config needed with plugin |\n| **Cross-Linking** | Find connections across your notes |\n\n### When to Use\n\n**Good fit:**\n- Research projects with extensive notes\n- Knowledge management workflows\n- Projects with related Obsidian vaults\n\n**Not needed:**\n- Projects without associated notes\n- Simple documentation needs\n\n---\n\n## Complete Setup Checklist\n\n### Documentation\n\n- [ ] README.md with badges, installation, usage\n- [ ] LICENSE (MIT, Apache 2.0, etc.)\n- [ ] CONTRIBUTING.md with guidelines\n- [ ] CHANGELOG.md (or Release Please manages it)\n- [ ] CODE_OF_CONDUCT.md\n- [ ] RELEASING.md (if manual releases)\n- [ ] CITATION.cff (if citable)\n- [ ] CLAUDE.md (for Claude Code users)\n\n### Editor Configuration\n\n- [ ] .editorconfig for universal formatting\n- [ ] .vscode/settings.json for VS Code\n- [ ] .vscode/extensions.json for recommended extensions\n\n### Branch Protection\n\n- [ ] PRs required for main\n- [ ] Auto-delete merged branches enabled\n- [ ] CODEOWNERS file\n- [ ] Status checks required (if CI exists)\n- [ ] Force push blocked\n\n### Issue \u0026 PR Management\n\n- [ ] Bug report template\n- [ ] Feature request template\n- [ ] Discussion templates (ideas, Q\u0026A)\n- [ ] PR template\n- [ ] Labels configured\n- [ ] Discussions enabled\n- [ ] Stale bot configured\n- [ ] Welcome bot configured\n\n### Quality Gates\n\n- [ ] Commitlint workflow\n- [ ] Spell check workflow + dictionary\n- [ ] Link checker workflow\n- [ ] Markdown lint workflow + config\n- [ ] Format check workflow (multi-language)\n\n### Release Automation\n\n- [ ] Release Please OR manual release workflow\n- [ ] CITATION.cff auto-update (if applicable)\n\n### CI/CD\n\n- [ ] Language-specific CI workflow (nodejs, python, go, rust)\n- [ ] Coverage workflow with Codecov\n- [ ] Dependabot for Actions + packages\n- [ ] Artifact preview on PRs (if applicable)\n\n### Security\n\n- [ ] Dependency review workflow (PR vulnerability check)\n- [ ] Dependabot configured for security updates\n\n### Publishing (if applicable)\n\n- [ ] npm publishing workflow\n- [ ] PyPI publishing workflow (OIDC)\n- [ ] Docker publishing workflow\n- [ ] crates.io publishing workflow\n\n### Deployment (if applicable)\n\n- [ ] GitHub Pages deployment\n- [ ] Vercel deployment\n- [ ] Netlify deployment\n\n### Dev Experience\n\n- [ ] Dev container configured\n- [ ] All-contributors bot (optional)\n\n### Discovery\n\n- [ ] Repository description set\n- [ ] Topics configured\n- [ ] Social preview uploaded\n- [ ] FUNDING.yml (if accepting sponsors)\n- [ ] GitHub Pages (if applicable)\n\n### MCP Integrations (Optional)\n\n- [ ] Serena MCP configured (code intelligence)\n- [ ] Zotero MCP configured (research/academic projects)\n- [ ] Obsidian MCP configured (knowledge management)\n\n---\n\n## Workflow Reference\n\n### Quality \u0026 Automation\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `release-please.yml` | Push to main | Auto-create release PRs |\n| `commitlint.yml` | PR opened | Validate commit messages |\n| `spell-check.yml` | Push/PR with docs | Check spelling |\n| `link-checker.yml` | Push/PR + weekly | Validate links |\n| `markdown-lint.yml` | Push/PR with .md | Lint markdown |\n| `format-check.yml` | Push/PR | Multi-language format check |\n| `stale.yml` | Daily schedule | Mark inactive issues |\n| `welcome.yml` | First issue/PR | Welcome contributors |\n| `all-contributors.yml` | Issue comment | Add contributors |\n\n### CI Workflows\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Push/PR | Generic build and test |\n| `ci-nodejs.yml` | Push/PR | Node.js CI (18, 20, 22) |\n| `ci-python.yml` | Push/PR | Python CI (3.10, 3.11, 3.12) |\n| `ci-go.yml` | Push/PR | Go CI (1.21, 1.22) |\n| `ci-rust.yml` | Push/PR | Rust CI (stable, nightly) |\n| `coverage.yml` | Push/PR | Upload coverage to Codecov |\n| `dependency-review.yml` | PR | Check for vulnerabilities |\n\n### Publishing Workflows\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `publish-npm.yml` | Release | Publish to npm |\n| `publish-pypi.yml` | Release | Publish to PyPI (OIDC) |\n| `publish-docker.yml` | Release/Push | Publish Docker image |\n| `publish-crates.yml` | Release | Publish to crates.io |\n| `amazon-kdp-publish.yml` | Release | Build EPUB for KDP |\n\n### Deployment Workflows\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `deploy-github-pages.yml` | Push to main | Deploy to GitHub Pages |\n| `deploy-vercel.yml` | Push/PR | Deploy to Vercel |\n| `deploy-netlify.yml` | Push/PR | Deploy to Netlify |\n| `artifact-preview.yml` | PR | Upload build preview |\n\n---\n\n## Claude Code Skills\n\n### Skill File Location\n\n\u003e **Important:** Claude Code uses `.claude/commands/` (not `.claude/skills/`) for custom slash commands.\n\n```bash\n# Correct location for Claude Code to recognize skills\n~/.claude/commands/skill-name.md      # Global (all projects)\n.claude/commands/skill-name.md        # Project-level\n\n# This will NOT work (common mistake)\n~/.claude/skills/skill-name.md        # Wrong directory name\n```\n\nIf you see `Unknown skill: skillname`, verify the file is in the `commands/` directory.\n\n### `/github-setup` — Repository Setup Wizard\n\nInstall the `/github-setup` skill:\n\n```bash\n# Copy to project\nmkdir -p .claude/commands\ncp templates/commands/github-setup.md .claude/commands/\n\n# Or global installation\nmkdir -p ~/.claude/commands\ncp templates/commands/github-setup.md ~/.claude/commands/\n```\n\nSee [templates/commands/github-setup.md](templates/commands/github-setup.md) for full documentation.\n\n### `/github-release` — Create Releases via Playwright\n\nAutomate GitHub release creation using Playwright browser automation:\n\n```bash\n/github-release v3.0.0\n/github-release v2.1.0 \"Bug fixes and improvements\"\n```\n\n**Prerequisites:** Tag pushed to remote, user authenticated to GitHub, Playwright MCP available.\n\nInstall:\n\n```bash\nmkdir -p .claude/commands\ncp templates/commands/github-release.md .claude/commands/\n```\n\nSee [templates/commands/github-release.md](templates/commands/github-release.md) for full documentation.\n\n---\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE).\n\n---\n\n## Troubleshooting\n\n### Release Please: \"GitHub Actions is not permitted to create or approve pull requests\"\n\n**Problem:** Release Please fails with permission error.\n\n**Fix:** Enable PR creation in repository settings:\n\n1. Go to **Settings → Actions → General**\n2. Scroll to **Workflow permissions**\n3. Check **\"Allow GitHub Actions to create and approve pull requests\"**\n4. Click **Save**\n\n### Link Checker: `--exclude-mail` flag error\n\n**Problem:** Link checker fails with unknown flag error.\n\n**Cause:** The `--exclude-mail` flag was removed in lychee v2 (now default behavior).\n\n**Fix:** Remove `--exclude-mail` from the workflow args and upgrade to `lycheeverse/lychee-action@v2`.\n\n### Link Checker: Release Please compare URLs return 404\n\n**Problem:** Link checker fails on URLs like `https://github.com/owner/repo/compare/v1.0.0...v1.0.1`.\n\n**Cause:** Release Please auto-generates these compare URLs in CHANGELOG.md. GitHub may return 404 briefly after a new release until the comparison is indexed.\n\n**Fix:** Exclude compare URLs in your link-checker workflow:\n\n```yaml\nargs: \u003e-\n  --exclude \"^https://github.com/OWNER/REPO/compare/\"\n  '**/*.md'\n```\n\nReplace `OWNER/REPO` with your actual repository path.\n\n### Markdown Lint: Many MD022/MD031/MD032 errors\n\n**Problem:** Lint fails with blanks-around-headings, blanks-around-fences, blanks-around-lists errors.\n\n**Fix:** These pedantic rules often conflict with real-world content. Disable in `.markdownlint.json`:\n\n```json\n{\n  \"MD022\": false,\n  \"MD031\": false,\n  \"MD032\": false\n}\n```\n\n### Markdown Lint: MD040 fenced-code-language errors\n\n**Problem:** Code blocks without language specifiers trigger errors.\n\n**Fix:** Add language identifiers to all code blocks. For plain text, use `text`:\n\n```text\nThis is plain text content\n```\n\n### Spell Check: Many unknown words\n\n**Problem:** Technical terms, author names, or project-specific words flagged.\n\n**Fix:** Add words to `.cspell.json` in the `words` array:\n\n```json\n{\n  \"words\": [\"yourterm\", \"anotherterm\"]\n}\n```\n\n### Stale Bot closes important issues\n\n**Problem:** Important long-running issues get marked stale.\n\n**Fix:** Add exempt labels to the stale workflow:\n\n```yaml\nexempt-issue-labels: 'pinned,security,in-progress,amazon-kdp'\n```\n\n### Release assets not uploading (PDF, EPUB missing)\n\n**Problem:** Post-release job runs but PDF/EPUB not attached to release.\n\n**Cause:** An earlier step (like CITATION.cff push) failed and stopped the job before upload steps ran.\n\n**Fix:** Reorder steps in `release-please.yml`:\n\n1. Put critical asset uploads **first** (PDF, EPUB)\n2. Put potentially-failing operations **last** (CITATION.cff, notifications)\n3. Add `continue-on-error: true` to non-critical steps\n\n```yaml\nsteps:\n  # Critical uploads FIRST\n  - name: Upload PDF to release\n    run: gh release upload ...\n\n  # Non-critical operations LAST\n  - name: Update CITATION.cff\n    continue-on-error: true  # Don't fail release if this fails\n    run: ...\n```\n\n### CITATION.cff not updating automatically\n\n**Problem:** CITATION.cff version doesn't update on release, or push fails with \"branch protection\" error.\n\n**Cause:** Post-release workflow steps that push directly to main are blocked by branch protection.\n\n**Best Fix (Recommended):** Use Release Please `extra-files` to manage CITATION.cff version automatically. This includes the version update in the Release Please PR itself, respecting branch protection.\n\n1. Add to `release-please-config.json`:\n\n```json\n{\n  \"packages\": {\n    \".\": {\n      \"extra-files\": [\n        {\n          \"type\": \"generic\",\n          \"path\": \"CITATION.cff\",\n          \"glob\": false\n        }\n      ]\n    }\n  }\n}\n```\n\n2. Ensure CITATION.cff has a `version:` field that Release Please can find and update.\n\n3. Remove any post-release CITATION.cff update steps from your workflow.\n\n**Alternative Fix:** If you can't use extra-files, add `continue-on-error: true`:\n\n```yaml\n- name: Update CITATION.cff\n  continue-on-error: true\n  run: |\n    # ... update commands ...\n    git push origin main || echo \"::warning::Could not push - branch protection requires PR\"\n```\n\n### Markdown Lint: MD024 duplicate heading errors\n\n**Problem:** Lint fails on files with intentionally repeated headings (e.g., multiple \"Example\" sections).\n\n**Fix:** Disable MD024 in `.markdownlint.json`:\n\n```json\n{\n  \"MD024\": false\n}\n```\n\n### Markdown Lint: MD029 ordered list prefix errors\n\n**Problem:** Lint fails on ordered lists that intentionally use `1.` for all items.\n\n**Fix:** Disable MD029 in `.markdownlint.json`:\n\n```json\n{\n  \"MD029\": false\n}\n```\n\n### Markdown Lint fails on CHANGELOG.md\n\n**Problem:** Release Please generates CHANGELOG.md with asterisks for lists, but markdownlint config expects dashes.\n\n**Fix:** Exclude CHANGELOG.md from lint in the workflow:\n\n```yaml\nglobs: |\n  **/*.md\n  !CHANGELOG.md\n```\n\n### Install script fails with 404 error\n\n**Problem:** A curl-based install script fails to download files from GitHub with a 404 error.\n\n**Cause:** The script downloads from `main` branch, but the files were recently moved/added on a feature branch that hasn't been merged yet.\n\n```bash\n# Script downloads from main branch\ncurl -o file.txt https://raw.githubusercontent.com/owner/repo/main/path/to/file.txt\n# Returns 404 if file only exists on feature branch\n```\n\n**Fix:** Merge the feature branch to `main` before the install script will work. Install scripts that download from GitHub should always reference paths that exist on `main`.\n\n**Best Practice for Install Scripts:**\n\n1. Test locally before pushing changes to file locations\n2. Merge PRs that move/rename files before updating download URLs\n3. Consider versioned URLs (`/v1.0.0/path`) instead of `/main/path` for stability\n\n### Install script shows \"Installed\" even when skipped\n\n**Problem:** Install script reports \"Installation Complete!\" even when user declined all prompts.\n\n**Fix:** Track what was actually installed and show an accurate summary:\n\n```bash\n# Track installation results\nINSTALLED_COMPONENT=false\n\ninstall_component() {\n    if check_and_download; then\n        INSTALLED_COMPONENT=true\n    fi\n}\n\nshow_summary() {\n    if [[ \"$INSTALLED_COMPONENT\" == \"false\" ]]; then\n        echo \"No changes made - all components already exist or skipped\"\n        echo \"To reinstall, run with --force flag\"\n        return\n    fi\n    echo \"Installation Complete!\"\n    [[ \"$INSTALLED_COMPONENT\" == \"true\" ]] \u0026\u0026 echo \"  • Component installed\"\n}\n```\n\n---\n\n## Resources\n\n- [GitHub Docs](https://docs.github.com)\n- [Conventional Commits](https://www.conventionalcommits.org/)\n- [Release Please](https://github.com/google-github-actions/release-please-action)\n- [Keep a Changelog](https://keepachangelog.com/)\n- [Contributor Covenant](https://www.contributor-covenant.org/)\n- [Serena MCP Documentation](docs/SERENA.md)\n- [Zotero MCP Documentation](docs/ZOTERO_MCP.md)\n- [Obsidian MCP Documentation](docs/OBSIDIAN_MCP.md)\n- [Markdown Lint Guide](docs/MARKDOWN_LINT.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomelic%2Fgithub-repository-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdomelic%2Fgithub-repository-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomelic%2Fgithub-repository-setup/lists"}