{"id":25685672,"url":"https://github.com/thinhphoenix/github-pages","last_synced_at":"2026-05-06T00:06:30.322Z","repository":{"id":274401668,"uuid":"922783420","full_name":"ThinhPhoenix/github-pages","owner":"ThinhPhoenix","description":"Automate the deployment of static websites using GitHub Actions and GitHub Pages. This template simplifies the build and deployment process for Vite, React, Vue, and other static frameworks, ensuring secure environment variable management and seamless updates. 🚀","archived":false,"fork":false,"pushed_at":"2025-02-23T10:55:41.000Z","size":92,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T11:20:00.839Z","etag":null,"topics":["automation","bunjs","deploy","front-end-development","gh-pages","github","github-actions","github-pages","github-workflows","production","template"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThinhPhoenix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-01-27T03:57:36.000Z","updated_at":"2025-02-23T10:55:44.000Z","dependencies_parsed_at":"2025-02-02T05:23:53.166Z","dependency_job_id":"13786dd8-d33c-4a86-9e44-c358ddb6003b","html_url":"https://github.com/ThinhPhoenix/github-pages","commit_stats":null,"previous_names":["thinhphoenix/deploy","thinhphoenix/gh-deploy","thinhphoenix/how-2-deploy","thinhphoenix/gh-pages","thinhphoenix/github-pages"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinhPhoenix%2Fgithub-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinhPhoenix%2Fgithub-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinhPhoenix%2Fgithub-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinhPhoenix%2Fgithub-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThinhPhoenix","download_url":"https://codeload.github.com/ThinhPhoenix/github-pages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240540549,"owners_count":19817791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","bunjs","deploy","front-end-development","gh-pages","github","github-actions","github-pages","github-workflows","production","template"],"created_at":"2025-02-24T18:57:08.179Z","updated_at":"2026-05-06T00:06:30.315Z","avatar_url":"https://github.com/ThinhPhoenix.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Actions Deployment Template\r\n\r\nA well-structured template for deploying **Vite, Next.js, Nuxt.js**, and similar applications to **GitHub Pages** using **GitHub Actions**, ensuring secure environment variable management.\r\n\r\n\u003e [!Note]\r\n\u003e Special thanks to [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action) and [rafgraph/spa-github-pages](https://github.com/rafgraph/spa-github-pages) for enabling this streamlined deployment process.\r\n\r\n![image](https://github.com/user-attachments/assets/99f76422-edfd-4fa1-ae48-77996cc433f6)\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Initialize Deploy Configuration\r\n\r\nRun the universal setup script (works on **Windows, macOS, and Linux**):\r\n\r\n```bash\r\ncurl -L https://cdn.jsdelivr.net/gh/ThinhPhoenix/github-pages@main/init.min.js | node\r\n```\r\n\r\nThis downloads and executes the init script directly from CDN.\r\n\r\n---\r\n\r\n### 2. Enable GitHub Actions Permissions\r\n\r\n**Option A - Using GitHub CLI (Recommended):**\r\n```bash\r\ngh api -X PUT /repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/permissions/workflow -f default_workflow_permissions='write'\r\n```\r\n\u003e [!Note]\r\n\u003e Install gh cli https://cli.github.com/\r\n\r\n**Option B - Manual Setup:**\r\nNavigate to: `Repository ▸ Settings ▸ Actions ▸ General ▸ Workflow permissions ▸ Read \u0026 Write`\r\n\r\n\r\n### 3. Configure Base URL in vite.config.ts\r\nFor **Vite-based projects**, set the correct base URL:\r\n```typescript\r\nimport { defineConfig } from \"vite\";\r\nimport react from \"@vitejs/plugin-react\";\r\n\r\nexport default defineConfig({\r\n  plugins: [react()],\r\n  base: \"/your-repo-name/\", //✎ Replace with your repository name\r\n});\r\n```\r\n\u003e ༼ つ ◕_◕ ༽つ If your project not vite-based then check for config file to change your root base\r\n\r\n### 4. Configure Environment Variables\r\nAll secrets stored in GitHub Actions Secrets are automatically injected into the build environment. Simply add your secrets via GitHub CLI or the web interface.\r\n\r\n\u003e [!Warning]\r\n\u003e **Do not** commit actual secret values to the repository.\r\n\r\n### 5. Secure Environment Variables Using GitHub Secrets\r\nTo securely store environment variables, use GitHub CLI:\r\nbash\r\ngh secret set -f .env\r\n\r\n\u003e [!Note]\r\n\u003e Ensure GitHub CLI is installed before executing this command. You can download GitHub CLI here: [GitHub CLI](https://cli.github.com/).  \r\n\u003e Alternatively, you can manually add secrets to **GitHub Actions Secrets** via **Repository \u003e Settings \u003e Secrets and variables \u003e Actions**.\r\n\r\n---\r\n\r\n## 📦 Features\r\n\r\n- ✓ Automated deployment to GitHub Pages  \r\n- ✓ Secure environment variable handling  \r\n- ✓ Configurable build and deployment settings  \r\n- ✓ Jekyll processing disabled (.nojekyll included)  \r\n\r\n---\r\n\r\n## 🔧 Configuration\r\n\r\n### GitHub Pages Setup\r\n\r\ngh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pages -X POST -f source[branch]=public -f source[path]=/\r\n\r\n1. Navigate to: `Repository ▸ Settings ▸ Pages`\r\n2. Set the source branch to public\r\n3. Click `Save`\r\n\r\n### Workflow Configuration\r\nThe deployment workflow is defined in `.github/workflows/deploy.yml` and includes:\r\n- Automated deployment on main branch pushes\r\n- Manual workflow execution with optional secret overrides\r\n- Bun runtime setup with caching\r\n- Automatic injection of all GitHub Secrets into the build environment\r\n- Build and deployment execution\r\n\r\n```yml\r\nname: Deploy 🕊️\r\n\r\non:\r\n  push:\r\n    branches:\r\n      - main #✎ Adjust to branch you want to deploy\r\n  workflow_dispatch:\r\n    inputs:\r\n      secrets_txt:\r\n        description: 'Paste secrets here (format: KEY=VALUE)'\r\n        required: false\r\n\r\njobs:\r\n  build_and_deploy:\r\n    name: Build \u0026 Deploy 🚀\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - name: Checkout repo\r\n        uses: actions/checkout@v4.1.7\r\n\r\n      - name: Import secrets\r\n        env:\r\n          SECRETS_CONTEXT: ${{ toJSON(secrets) }}\r\n        run: |\r\n          echo \"$SECRETS_CONTEXT\" | jq -r 'to_entries[] | \"\\(.key)=\\(.value)\"' \u003e\u003e \"$GITHUB_ENV\"\r\n\r\n      - name: Setup Bun\r\n        uses: oven-sh/setup-bun@v1\r\n\r\n      - name: Install dependencies\r\n        run: |\r\n          bun install\r\n          if [ -f bun.lockb ]; then\r\n            if git ls-files --error-unmatch bun.lockb \u003e /dev/null 2\u003e\u00261; then\r\n              if ! git diff --quiet bun.lockb; then\r\n                git config --global user.name \"github-actions[bot]\"\r\n                git config --global user.email \"github-actions[bot]@users.noreply.github.com\"\r\n                git add bun.lockb\r\n                git commit -m \"chore: update bun.lockb\"\r\n                git push\r\n              fi\r\n            else\r\n              echo \"bun.lockb is not tracked by Git. Adding it...\"\r\n              git config --global user.name \"github-actions[bot]\"\r\n              git config --global user.email \"github-actions[bot]@users.noreply.github.com\"\r\n              git add bun.lockb\r\n              git commit -m \"chore: add bun.lockb\"\r\n              git push\r\n            fi\r\n          else\r\n            echo \"bun.lockb does not exist. Skipping commit.\"\r\n          fi\r\n\r\n      - name: Build project\r\n        run: bun run build \u0026\u0026 touch ./dist/.nojekyll #✎ Adjust to your build output folder (dist or out)\r\n\r\n      - name: Deploy to GitHub Pages\r\n        uses: JamesIves/github-pages-deploy-action@v4.6.0\r\n        with:\r\n          token: ${{ secrets.GITHUB_TOKEN }}\r\n          branch: public\r\n          folder: dist #✎ Adjust to your build output folder (dist or out)\r\n```\r\n\r\n---\r\n\r\n## 💡 Environment Variables\r\n\r\nEnvironment variables can be managed in two ways:\r\n1. **GitHub Secrets** (recommended for production)\r\n2. **Workflow dispatch input** (useful for testing purposes)\r\n\r\n---\r\n\r\n## 🏗️ Build Configuration\r\n\r\n| Setting             | Default Value        | Configuration File    |\r\n|--------------------|--------------------|---------------------|\r\n| **Output Directory** | dist              | deploy.yml         |\r\n| **Base URL**        | /repository-name/ | vite.config.ts     |\r\n\r\nThese settings can be adjusted based on project requirements.\r\n\r\n---\r\n\r\n## 📝 Usage\r\n\r\n### Automatic Deployment\r\nDeploy automatically by pushing changes to the main branch:\r\nbash\r\ngit push origin main\r\n\r\n\r\n### Manual Deployment\r\n1. Navigate to **Actions** in the repository\r\n2. Select the **Deploy 🕊️** workflow\r\n3. Click **Run workflow**\r\n4. (Optional) Provide secrets in KEY=VALUE format\r\n\r\n---\r\n\r\n## ⚠️ Important Considerations\r\n\r\n\u003e [!Warning]\r\n\u003e - Ensure the repository name matches the base URL in vite.config.ts.\r\n\u003e - **Do not** commit actual secret values to the repository.\r\n\u003e - The public branch is automatically generated upon the first deployment.\r\n\u003e - **Fix SPA GitHub Pages 404 Error:** \r\n\u003e   1. Place `404.html` (from `./public`) at the root of your deployed site. This file redirects all 404s back to `index.html` with the original path preserved in the query string.\r\n\u003e   2. Add the following script to your `index.html` **inside the `\u003chead\u003e` tag** (before any other scripts):\r\n\u003e      ```html\r\n\u003e      \u003c!-- Start Single Page Apps for GitHub Pages --\u003e\r\n\u003e      \u003cscript type=\"text/javascript\"\u003e\r\n\u003e        // Single Page Apps for GitHub Pages\r\n\u003e        // MIT License\r\n\u003e        // https://github.com/rafgraph/spa-github-pages\r\n\u003e        // This script checks to see if a redirect is present in the query string,\r\n\u003e        // converts it back into the correct url and adds it to the\r\n\u003e        // browser's history using window.history.replaceState(...),\r\n\u003e        // which won't cause the browser to attempt to load the new url.\r\n\u003e        // When the single page app is loaded further down in this file,\r\n\u003e        // the correct url will be waiting in the browser's history for\r\n\u003e        // the single page app to route accordingly.\r\n\u003e        (function(l) {\r\n\u003e          if (l.search[1] === '/' ) {\r\n\u003e            var decoded = l.search.slice(1).split('\u0026').map(function(s) { \r\n\u003e              return s.replace(/~and~/g, '\u0026')\r\n\u003e            }).join('?');\r\n\u003e            window.history.replaceState(null, null,\r\n\u003e                l.pathname.slice(0, -1) + decoded + l.hash\r\n\u003e            );\r\n\u003e          }\r\n\u003e        }(window.location))\r\n\u003e      \u003c/script\u003e\r\n\u003e      \u003c!-- End Single Page Apps for GitHub Pages --\u003e\r\n\u003e      ```\r\n\u003e   - This allows client-side routing to work correctly when refreshing or accessing deep links directly (e.g., `/about`, `/user/123`).\r\n\u003e   - For React Router, Vue Router, or other SPA frameworks, this ensures routes work on refresh.\r\n\u003e   - Special thanks to [rafgraph/spa-github-pages](https://github.com/rafgraph/spa-github-pages) for this solution.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions and improvements are welcome! Feel free to submit issues or feature requests.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nThis project is distributed under the **MIT License**. Refer to the LICENSE file for more details.\r\n\r\n---\r\n\r\n## 🙏 Acknowledgments\r\n\r\nThis deployment template is powered by:\r\n- [JamesIves/github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)\r\n- [rafgraph/spa-github-pages](https://github.com/rafgraph/spa-github-pages)\r\n\r\nConsider supporting their valuable contributions!\r\n\r\n---\r\n\r\n## Star History\r\n\r\n[![Star History Chart](https://api.star-history.com/svg?repos=ThinhPhoenix/github-pages\u0026type=Date)](https://star-history.com/#ThinhPhoenix/github-pages\u0026Date)\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinhphoenix%2Fgithub-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthinhphoenix%2Fgithub-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinhphoenix%2Fgithub-pages/lists"}