{"id":15065668,"url":"https://github.com/skywarth/vite-github-pages-deployer","last_synced_at":"2026-03-16T16:39:53.464Z","repository":{"id":165147511,"uuid":"640519297","full_name":"skywarth/vite-github-pages-deployer","owner":"skywarth","description":"Deploy your Vite application to Github pages, plug-and-play.","archived":false,"fork":false,"pushed_at":"2025-03-16T00:08:50.000Z","size":158,"stargazers_count":35,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-06T00:33:38.546Z","etag":null,"topics":["deployer","deployment","github-actions","github-pages","github-pages-deployment","npm","react","reactjs","release-automation","static-site","vite","vite-plugin","vite-project","vitejs","vitest","vue","yarn"],"latest_commit_sha":null,"homepage":"https://github.com/marketplace/actions/vite-github-pages-deployer","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skywarth.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},"funding":{"github":["skywarth"],"buy_me_a_coffee":"skywarth"}},"created_at":"2023-05-14T11:14:35.000Z","updated_at":"2025-03-31T17:36:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"ff296cd9-b453-46ce-b433-4d52d53d75a2","html_url":"https://github.com/skywarth/vite-github-pages-deployer","commit_stats":null,"previous_names":["skywarth/vite-vue-github-pages-deploy"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywarth%2Fvite-github-pages-deployer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywarth%2Fvite-github-pages-deployer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywarth%2Fvite-github-pages-deployer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skywarth%2Fvite-github-pages-deployer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skywarth","download_url":"https://codeload.github.com/skywarth/vite-github-pages-deployer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225707,"owners_count":21068078,"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":["deployer","deployment","github-actions","github-pages","github-pages-deployment","npm","react","reactjs","release-automation","static-site","vite","vite-plugin","vite-project","vitejs","vitest","vue","yarn"],"created_at":"2024-09-25T00:44:44.052Z","updated_at":"2026-03-16T16:39:53.391Z","avatar_url":"https://github.com/skywarth.png","language":null,"readme":"# Vite GitHub Pages Deployer\n\n\u003c!-- ![GitHub all releases](https://img.shields.io/github/downloads/skywarth/vite-github-pages-deployer/total?style=for-the-badge) --\u003e\n\nDeploy your [Vite](https://vitejs.dev/guide/) application to Github Pages, at a glance. \n- No shenanigans such as committing the dist folder and pushing to a branch. \n- Clean deploy to GitHub Pages by utilizing actions and artifacts.\n- Customizable with optional build path\n- Can be used with any frontend framework as long as you use `vite` as your `build` tool. Vue, React, Svelte... You name it!\n\n```\n- name: Vite Github Pages Deployer\n  uses: skywarth/vite-github-pages-deployer@v1.5.0\n```\n\n\n## Table of Contents\n\n1. [Usage](#usage)\n2. [Example Workflow](#example-workflow)\n3. [Demo](#demo)\n4. [Input Parameters](#input-parameters)\n5. [Outputs](#outputs)\n6. [Common errors and mistakes](#common-errors)\n7. [TODOs](#todos)\n\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n## 1. Usage :checkered_flag:\n\nYou can use this action simply by adding it to your action's `yaml` files appropriately. \n\n### 1.1 Add the usage step :triangular_flag_on_post:\n\nMake sure to place this step after your 'checkout' step.\n\n```yaml\n- name: Vite Github Pages Deployer\n  uses: skywarth/vite-github-pages-deployer@v1.5.0\n  id: deploy_to_pages\n```\n\n### 1.2 Release environment :outbox_tray:\n\nYou have to place the environment section right before the `steps`. This enables the release of environment, under the environments tab. \n\n```yaml\nenvironment:\n  name: demo\n  url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}\n```\n\n### 1.3 Set the permissions for the action  :shipit:\n\nYou need to set the proper permission for the action, in order to successfully release environment and artifact. If you don't you may receive permission errors.\n\nPermission declaration can be placed anywhere before `jobs:` section.\n\n```yaml\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n```\n\n### 1.4 Enjoy! :tada:\n\n\n\u003ca name=\"example-workflow\"\u003e\u003c/a\u003e\n## 2. Example workflow :rocket:\n\nIf you don't know what to do, what actions are, or where to place the code pieces in the [usage](#usage) section, then follow these steps:\n\n1. Create an action file at this path: `./.github/workflows/vite-github-pages-deploy.yml`. So in essence create a `.github` folder at your project root, and create a `yml` file in there.\n2. Copy the code below and paste it into the action you've just created, then save.\n3. Done. On your next push to `master` branch, or your next manual run from actions tab, this action will run and your project will be deployed to github pages.\n\n\n```yaml\nname: Vite Github Pages Deploy\n\non:\n  # Runs on pushes targeting the default branch\n  push:\n    branches: [\"master\", \"main\"]\n  # Allows you to run this workflow manually from the Actions tab\n  workflow_dispatch:\n\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: \"pages\"\n  cancel-in-progress: false\n\njobs:\n  # Build job\n  build:\n    runs-on: ubuntu-latest\n    environment:\n      name: demo\n      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Vite Github Pages Deployer\n        uses: skywarth/vite-github-pages-deployer@master\n        id: deploy_to_pages\n\n```\n\n\n\u003ca name=\"demo\"\u003e\u003c/a\u003e\n## 3. Demo :moyai:\n\nWant to see it in action? Sure thing, head on to this vue project to see it live: https://github.com/skywarth/country-routing-algorithm-demo-vue\n\n\n\u003ca name=\"input-parameters\"\u003e\u003c/a\u003e\n## 4. Input Parameters :wrench:\n\n### `public_base_path` (optional)\n| Type     | Default                                      | Example Values     |\n|----------|----------------------------------------------|--------------------|\n| `string` | `/{your-repo-name}` OR `/` if you have CNAME | `/my-vite-project` |\n\n\n[Public base path](https://vitejs.dev/guide/build.html#public-base-path) string for Vite, this affects the routing, history and asset links. Make sure to provide appropriately since GitHub Pages stores your app in a directory under a subdomain. If you plan on deploying to alternative platform such as Vercel, you should simply provide `/`.\n\nUnder normal circumstances, you don't need to provide/override this parameter, action will set it to your repo name appropriately.\n\n#### Here's how `public_base_path` is resolved:\n\n- If `public_base_path` parameter/input is provided, it will be used regardless.\n- If `public_base_path` parameter/input is **NOT** provided:\n  - If the repository root has `CNAME` file for GitHub Pages Custom Domain setup, then `public_base_path` default value will resolve to `/`\n  - If the repository root does **NOT** have `CNAME`, `public_base_path` default value will resolve to `/{your-repo-name}`\n\n\u003ca name=\"public-base-path-ack\"\u003e\u003c/a\u003e\n#### Acknowledgement \n\nSee the suggestion for the CNAME expansion [here](https://github.com/skywarth/vite-github-pages-deployer/issues/5)\n\nGrateful to the [Greg Sadetsky](https://github.com/gregsadetsky) for his proposition on alternating default value of this input. Also, thankful for his collaboration on explaining GitHub pages custom domain setting and testing phase of these changes.\n\n\u003cbr\u003e\n\n\n\u003ca name=\"build_path\"\u003e\u003c/a\u003e\n### `build_path`(optional)\n| Type     | Default  | Example Values                                         |\n|----------|----------|--------------------------------------------------------|\n| `string` | `./dist` | - `./deploy`\u003cbr/\u003e - `./dist/browser` \u003cbr/\u003e - `../dist` |\n\nWhich folder do you want your GitHub Page to use as root directory of deployment, after the build process. Simply it is your build output directory such as `./dist`. If your `vite` config exports to a folder other than `./dist`, then you should pass it as parameter.\n\n#### :warning: `build_path` works along with `working_path` [see section](#working_path)\n\nHere's how `build_path` is resolved and utilized while working along `working_path` parameter.\n\n- If `build_path` is an absolute path (e.g: `build_path: /some-folder/sub-folder`, then it is used as is\n  - Keep in mind this absolute path is really absolute, `/` doesn't point to repository root, it points to \n- If `build_path` is NOT an absolute path\n  - If `working_path: ./` (default value) then use `build_path` as is\n  - If `working_path` is NOT the default value (repository root), then combine `working_path` and `build_path` and use it as build directory.\n\nSee the examples below to understand how it is resolved.\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cb\u003eExample-1: Standard repository\u003c/b\u003e\u003c/summary\u003e\n\n\n#### Example-1: Standard repository\n\n---\n\n```\n.\n├── src/ \n├── dist/ (doesn't exist in repository, created during build)\n├── package.json\n├── package-lock.json\n├── docs/\n└── README.md\n```\n\nThen you don't have to configure any parameters for the action. This is the default setup with the following default parameter values:\n- `build_path: ./dist`\n- `working_path: ./`\n- Resolved build output folder: `./dist`\n\n---\n\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cb\u003eExample-2: All code related files reside under a folder\u003c/b\u003e\u003c/summary\u003e\n\n---\n\n#### Example-2: All code related files reside under a folder\n\n```\n.\n├── app/ \n│   └── src/\n│   └── dist/ (doesn't exist in repository, created during build)\n│   └── package.json\n│   └── package-lock.json\n└── docs/\n└── README.md\n```\n\nPass the following parameters:\n```yml\n- name: Deploy to Github Pages\n  uses: skywarth/vite-github-pages-deployer@master\n  id: deploy_to_pages\n  with:\n    working_path: ./app\n```\n- With this setup, the resolved build output folder is: `./app/dist`\n\n---\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cb\u003e Example-3: All code related files reside under a folder, with a custom build folder name\u003c/b\u003e\u003c/summary\u003e\n\n#### Example-3: All code related files reside under a folder, with a custom build folder name\n\n---\n\n```\n.\n├── app/ \n│   └── src/\n│   └── my_custom_build_folder/ (doesn't exist in repository, created during build)\n│   └── package.json\n│   └── package-lock.json\n└── docs/\n└── README.md\n```\n\nPass the following parameters:\n```yml\n- name: Deploy to Github Pages\n  uses: skywarth/vite-github-pages-deployer@master\n  id: deploy_to_pages\n  with:\n    working_path: ./app\n    build_path: my_custom_build_folder\n```\n- With this setup, the resolved build output folder is: `./app/my_custom_build_folder`\n\n---\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cb\u003e Example-4: All code related files reside under a folder, except the build folder, with a custom build folder name\u003c/b\u003e\u003c/summary\u003e\n\n#### Example-4: All code related files reside under a folder, except the build folder, with a custom build folder name\n\n---\n\n```\n.\n├── app/ \n│   └── src/\n│   └── package.json\n│   └── package-lock.json\n└── deploy/\n└── docs/\n└── README.md\n```\n\nPass the following parameters:\n```yml\n- name: Deploy to Github Pages\n  uses: skywarth/vite-github-pages-deployer@master\n  id: deploy_to_pages\n  with:\n    working_path: ./app\n    build_path: ../deploy\n```\n- With this setup, the resolved build output folder is: `./deploy`, because `./app/../deploy`\n\n---\n\n\u003c/details\u003e\n\n\n\n\n\n\n\n### `install_phase_node_env`(optional)\n| Type     | Default | Example Values                                                                             |\n|----------|---------|--------------------------------------------------------------------------------------------|\n| `string` | `dev`   | - `dev` \u003cbr/\u003e - `production` \u003cbr/\u003e - `staging` \u003cbr/\u003e - `test` \u003cbr/\u003e - `my-little-pony-env` |\n\n\nNode environment that will be used for the installation of dependencies. **It is imperative you use an environment that has 'vite' as dependency**. Commonly and naturally, that env is `dev`.\n\n:x: If you don't provide a NODE_ENV that has `vite` as dependency (check your package.json), you'll receive `sh: 1: vite: not found` during build phase.\n\n### `build_phase_node_env` (optional)\n| Type     | Default      | Example Values                                                                             |\n|----------|--------------|--------------------------------------------------------------------------------------------|\n| `string` | `production` | - `dev` \u003cbr/\u003e - `production` \u003cbr/\u003e - `staging` \u003cbr/\u003e - `test` \u003cbr/\u003e - `my-little-pony-env` |\n\n\n\nNode environment that will be used for the build phase. You may provide any valid NODE_ENV value for this, since node builds tend to change for different environments (e.g: you hide debugging features from production).\n\n\n\n### `artifact_name` (optional)\n| Type     | Default        | Example Values                                        |\n|----------|----------------|-------------------------------------------------------|\n| `string` | `github-pages` | - `what-a-cool-artifact` \u003cbr/\u003e - `ah-yes-ze-artifact` |\n\nDesired name for the exposed artifact. This name is visible in job and used as the artifacts name.\n\n\n### `package_manager` (optional)\n| Type     | Default | Example Values         |\n|----------|---------|------------------------|\n| `string` | `npm`   | - `npm` \u003cbr/\u003e - `yarn` |\n\nIndicate the package manager of preferrence. It'll be used for installing dependencies and building the `dist`. For example if you prefer/use `yarn` as your package manager for the project, then you may pass `package_manager: 'yarn'` as input which then will be used as `yarn install` and `yarn build`.\n\n\u003ca name=\"working_path\"\u003e\u003c/a\u003e\n### `working_path` (optional)\n| Type     | Default   | Example Values               |\n|----------|-----------|------------------------------|\n| `string` | `./`      | - './app' \u003cbr/\u003e `./example` |\n\n- :warning: **Make sure `working_path` points to where your `package.json` is!** \n- `working_path` affects `build_path` resolution, [see section](#build_path)\n\nSpecifies the directory where the `install`, `build`, and deploy commands should be executed.\n\n**Example:**\n\nIf your project structure looks like this:\n\n```text\napp/\n  package.json\n  ...\nREADME.md\n```\n\nYou can set the `working_path` to `./app` to ensure the commands run in the correct directory:\n\n```yaml\nwith:\n  working_path: ./app\n```\n\n#### Acknowledgement \n\nMany thanks to [@sondalex](https://github.com/sondalex) for proposing the idea and implementing the necessary changes to support working directory option. See the related [PR](https://github.com/skywarth/vite-github-pages-deployer/pull/14) for details and discussion. \n\n\n### `debug_mode` (optional)\n| Type     | Default   | Example Values               |\n|----------|-----------|------------------------------|\n| `string` | `'false'` | - `'true'` \u003cbr/\u003e - `'false'` |\n\n\nControls the debug mode, string, `'true'` is for on. When turned on, it'll output certain information on certain steps. Mainly used for development, but use it as you please to inspect your env and variables.\n\n\n\u003ca name=\"outputs\"\u003e\u003c/a\u003e\n## 5. Outputs :pushpin:\n\n\n### `github_pages_url`\n| Type     | Example Values                                                       |\n|----------|----------------------------------------------------------------------|\n| `string` | - `'https://skywarth.github.io/country-routing-algorithm-demo-vue/'` |\n\n\nThis output value shall be used to acquire the github pages url following the deployment. It can be accessed like so: `${{ steps.deploy_to_pages.outputs.github_pages_url }}` (deploy_to_pages is the id of the step that you run Vite Github Pages Deployer).\n\nIt is expected to be used as a way to publish environment during the job, like so:\n```\nenvironment:\n      name: demo\n      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}\n```\n\nSee [example workflow](#example-workflow) to grasp how to utilize this output\n\n\n\n\n\u003ca name=\"common-errors\"\u003e\u003c/a\u003e\n## 6. Common errors and mistakes :sos: :name_badge:\n\n### 6.1 Not releasing the environment\n\n**Error:** `Environment URL '' is not a valid http(s) URL, so it will not be shown as a link in the workflow graph.`\n\n**Cause:** Environment declaration is missing from the action, you should add it to your action `yaml` file in order to both solve the error/warning and to display the released environment in the `environments` tab in the repository.\n\n**Solution:** Add the following to your action:\n```yaml\nenvironment:\n  # Name could be whatever you wish. It'll be visible publicly under the environments tab.\n  name: demo\n  url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}\n```\n\n:warning: Remember, `deploy_to_pages` name should be identical to the `id` of the step that you run the `Vite GitHub pages deployer`. See the [example workflow](#example-workflow) for details. \n\n\n### 6.2 Missing permission requirements for `GITHUB_TOKEN`\n\n**Error:** `Error: Ensure GITHUB_TOKEN has permission \"id-token: write\".`\n\n**Cause:** Permission wasn't set as indicated in the [usage](#usage) section. If proper permissions are not granted to the action, it won't be able to create artifacts or create environments.\n\n**Solution:** Add the following code about permissions to your action `yaml` file.\n\n```\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n```\n\nSee the [example workflow](#example-workflow) if you're not sure where to place it.\n\n\n### 6.3 `package-lock.json` is not present when using `npm` as package manager preferrence.\n\n**Error:** `The `npm ci` command can only install with an existing package-lock.json...`\n\n**Cause:** If `package_manager` input preference is set to `npm` (or default, unassigned), it will install dependencies using `npm ci` which utilizes `package-lock.json`. In this case make sure `package-lock.json` is present in your project root.\n\n**Solution:** Add your `package-lock.json` file to your project. If it's in the directory but doesn't appear in the repository, check your gitignore file and remove it from gitignore. Alternatively, you may set `yarn` as your preferred package manager for dependency installation via `package_manager` parameter input of the action.\n\n\n\u003ca name=\"todos\"\u003e\u003c/a\u003e\n## 7. TODOs\n\n- [X] ~~Output the deploy url for environment, see issue #2~~\n- [X] ~~Spread the gospel.~~\n  - [X] ~~[DEV.to post](https://dev.to/skywarth/deploying-your-vite-apps-to-github-pages-is-a-breeze-with-vite-github-pages-deployer-30c3)~~\n  - [X] ~~Reddit (opensource, github, github action, ci/cd, vite, vue, react forums etc.).Blah, reddit was like, you know... Reddit.~~\n  - [X] ~~Maybe a [medium.com post](https://medium.com/@yigitk.ersoy/introducing-vite-github-pages-deployer-a-better-way-to-showcase-your-vite-projects-fadbb93f3db9)... God I hate that place, it stinks.~~\n- [X] ~~NODE_ENV options/params~~\n  - [X] ~~Install phase NODE_ENV~~\n  - [X] ~~Build phase NODE_ENV~~\n- [X] ~~Section for common errors and solutions. (Dismantle tidbits)~~\n- [X] ~~Make README more eye-candy~~\n  - [X] ~~Table for each input/param (type, default etc.)~~\n  - [X] ~~Icons for emphasis~~\n- [X] ~~Option for defining package manager preference, see issue #1~~\n- [X] Table of Content\n- [ ] ~~Move bash scripts to a separate file for each section: build.sh, install.sh etc...~~ (not feasible, see the branch `bash-files`)\n  - [ ] ~~Passing some parameters to it perhaps~~ (not feasible, see the branch `bash-files`)\n- [ ] Public docs deployment, `README` is becoming rather *rudimentary* \n- [ ] Update ToC to include each input parameter\n\n### Something is lacking ?\n\nIs there something you require, does this action fail to meet your expectations or it lacks certain futures that prevent you from using it ? Open up an issue, and we add it to the roadmap/TODOs. Contributions are welcome.\n\n\n\u003cdetails\u003e\u003csummary\u003eNotes to self\u003c/summary\u003e\n\n- `${{github.action_path}}`: Gives you the dir for this action itself.\n\n- `${{ github.workspace }}`: Gives you the dir of the project (E.g: /home/runner/work/country-routing-algorithm-demo-vue/country-routing-algorithm-demo-vue)\n\n- When you import a sh file in the bash shell, it is only accessible during that step only. This is due to the fact that each step is a shell on its own.\n\n- ~~Inside separate `sh` files, you can access input variables of the action by their respective uppercase name. For example:~~\n  - Input definition:\n    ```\n    inputs: \n        package_manager:\n        description: \"Your preference of package manager: 'npm' and 'yarn' are possible values.\"\n        required: false\n        default: 'npm'\n    ```\n  - ~~Accessing this input **inside the action**: `${{ inputs.package_manager }}`~~\n  - ~~Accessing this input **inside a `sh` file: `$PACKAGE_MANAGER`~~\n    - Alternatively, you may pass env to the step to access it from a name of your liking:\n      ```\n      env:\n        SOME_OTHER_NAME: ${{ inputs.package_manager }}\n      ``` \n\n- If you run `sh` files in steps, don't expect each shell to share the environments. For example in one step you install dependencies in install.sh, in another step you build by build.sh. It won't work because installed libs are only available for the install.sh step. This is why `bash-files` failed, I consulted GPT but apparently there is no way of achieving it.\n\n\n\u003c/details\u003e\n\n\n\n\n\n","funding_links":["https://github.com/sponsors/skywarth","https://buymeacoffee.com/skywarth"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskywarth%2Fvite-github-pages-deployer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskywarth%2Fvite-github-pages-deployer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskywarth%2Fvite-github-pages-deployer/lists"}