ghaction-github-pages/README.md

[![GitHub release](https://img.shields.io/github/release/crazy-max/ghaction-github-pages.svg?style=flat-square)](https://github.com/crazy-max/ghaction-github-pages/releases/latest)
[![GitHub marketplace](https://img.shields.io/badge/marketplace-github--pages-blue?logo=github&style=flat-square)](https://github.com/marketplace/actions/github-pages)
[![Test workflow](https://github.com/crazy-max/ghaction-github-pages/workflows/test/badge.svg)](https://github.com/crazy-max/ghaction-github-pages/actions)
[![Become a sponsor](https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square)](https://github.com/sponsors/crazy-max)
[![Paypal Donate](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square)](https://www.paypal.me/crazyws)

## ✨ About

A GitHub Action to deploy to GitHub Pages

If you are interested, [check out](https://git.io/Je09Y) my other :octocat: GitHub Actions!

> **:warning: Note:** To use this action, you must have access to the [GitHub Actions](https://github.com/features/actions) feature. GitHub Actions are currently only available in public beta. You can [apply for the GitHub Actions beta here](https://github.com/features/actions/signup/).

## 🚀 Usage

Below is a simple snippet to deploy to GitHub Pages. A [test example](https://github.com/crazy-max/ghaction-github-pages/actions?query=workflow%3Atest) is also available for this repository.

```yaml
name: website

on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v1
      -
        name: Build
        run: |
          mkdir public
          cat > public/index.html <<EOL
          <!doctype html>
          <html>
            <head>
              <title>GitHub Pages deployed!</title>
            </head>
            <body>
              <p>GitHub Pages with <strong>${{ github.sha }}</strong> commit ID has been deployed through <a href="https://github.com/marketplace/actions/github-pages">GitHub Pages action</a> successfully.</p>
            </body>
          </html>
          EOL
      -
        name: Deploy
        if: success()
        uses: crazy-max/ghaction-github-pages@v1
        with:
          target_branch: gh-pages
          build_dir: public
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## 💅 Customizing

### inputs

Following inputs can be used as `step.with` keys

| Name            | Type    | Description                                                       |
|-----------------|---------|-------------------------------------------------------------------|
| `repo`          | String  | GitHub repository where assets will be deployed (default current) |
| `target_branch` | String  | Git branch where assets will be deployed (default `gh-pages`)     |
| `build_dir`     | String  | Build directory to deploy (**required**)                          |
| `commit_name`   | String  | Commit author's name  (default [GITHUB_ACTOR](https://help.github.com/en/github/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables) or `github-actions`) |
| `commit_email`  | String  | Commit author's email (default `<committer_name>@users.noreply.github.com`) |
| `commit_message`| String  | Commit message (default `Deploy to GitHub pages`)                 |

### environment variables

Following environment variables can be used as `step.env` keys

| Name           | Description                          |
|----------------|--------------------------------------|
| `GITHUB_TOKEN` | GITHUB_TOKEN as provided by `secrets`|
| `GITHUB_PAT`   | [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) (see Limitation section below)|

## :warning: Limitation

Currently, `GITHUB_TOKEN` [does not suffice to trigger a page build](https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/26869) on a **public repository** (propagate content to the GitHub content-delivery network). You must therefore create a custom [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) and use it through the `GITHUB_PAT` environment variable:

```yaml
- name: Deploy
  if: success()
  uses: crazy-max/ghaction-github-pages@v1
  with:
    target_branch: gh-pages
    build_dir: public
  env:
    GITHUB_PAT: ${{ secrets.GITHUB_PAT }}
```

## 🤝 How can I help ?

All kinds of contributions are welcome :raised_hands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon: You can also support this project by [**becoming a sponsor on GitHub**](https://github.com/sponsors/crazy-max) :clap: or by making a [Paypal donation](https://www.paypal.me/crazyws) to ensure this journey continues indefinitely! :rocket:

Thanks again for your support, it is much appreciated! :pray:

## 📝 License

MIT. See `LICENSE` for more details.
Add test workflow 2019-09-01 06:30:48 +08:00			`[![GitHub release](https://img.shields.io/github/release/crazy-max/ghaction-github-pages.svg?style=flat-square)](https://github.com/crazy-max/ghaction-github-pages/releases/latest)`
			`[![GitHub marketplace](https://img.shields.io/badge/marketplace-github--pages-blue?logo=github&style=flat-square)](https://github.com/marketplace/actions/github-pages)`
			`[![Test workflow](https://github.com/crazy-max/ghaction-github-pages/workflows/test/badge.svg)](https://github.com/crazy-max/ghaction-github-pages/actions)`
Update README 2019-11-15 02:25:19 +08:00			`[![Become a sponsor](https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square)](https://github.com/sponsors/crazy-max)`
Initial version 2019-09-01 04:23:41 +08:00			`[![Paypal Donate](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square)](https://www.paypal.me/crazyws)`

			`## ✨ About`

Spelling 2019-10-11 08:25:58 +08:00			`A GitHub Action to deploy to GitHub Pages`
Initial version 2019-09-01 04:23:41 +08:00
Update README 2019-10-25 05:26:25 +08:00			`If you are interested, [check out](https://git.io/Je09Y) my other :octocat: GitHub Actions!`

Initial version 2019-09-01 04:23:41 +08:00			`> :warning: Note: To use this action, you must have access to the [GitHub Actions](https://github.com/features/actions) feature. GitHub Actions are currently only available in public beta. You can [apply for the GitHub Actions beta here](https://github.com/features/actions/signup/).`

			`## 🚀 Usage`

Fix link 2019-11-06 10:14:13 +08:00			`Below is a simple snippet to deploy to GitHub Pages. A [test example](https://github.com/crazy-max/ghaction-github-pages/actions?query=workflow%3Atest) is also available for this repository.`
Initial version 2019-09-01 04:23:41 +08:00
			```yaml
			`name: website`

			`on: push`

			`jobs:`
			`publish:`
			`runs-on: ubuntu-latest`
			`steps:`
			`-`
			`name: Checkout`
Use v1 2019-10-11 07:51:17 +08:00			`uses: actions/checkout@v1`
Initial version 2019-09-01 04:23:41 +08:00			`-`
			`name: Build`
			`run: \|`
			`mkdir public`
			`cat > public/index.html <<EOL`
			`<!doctype html>`
			`<html>`
			`<head>`
			`<title>GitHub Pages deployed!</title>`
			`</head>`
			`<body>`
Add test workflow 2019-09-01 06:30:48 +08:00			`<p>GitHub Pages with <strong>${{ github.sha }}</strong> commit ID has been deployed through <a href="https://github.com/marketplace/actions/github-pages">GitHub Pages action</a> successfully.</p>`
Initial version 2019-09-01 04:23:41 +08:00			`</body>`
			`</html>`
			`EOL`
			`-`
			`name: Deploy`
Add target_branch input 2019-09-01 05:28:00 +08:00			`if: success()`
Use v1 2019-10-11 07:51:17 +08:00			`uses: crazy-max/ghaction-github-pages@v1`
Initial version 2019-09-01 04:23:41 +08:00			`with:`
Add target_branch input 2019-09-01 05:28:00 +08:00			`target_branch: gh-pages`
Initial version 2019-09-01 04:23:41 +08:00			`build_dir: public`
			`env:`
			`GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
			```

			`## 💅 Customizing`

			`### inputs`

Add target_branch input 2019-09-01 05:28:00 +08:00			Following inputs can be used as `step.with` keys
Initial version 2019-09-01 04:23:41 +08:00
Text 2019-10-11 08:22:34 +08:00			`\| Name \| Type \| Description \|`
			`\|-----------------\|---------\|-------------------------------------------------------------------\|`
			\| `repo` \| String \| GitHub repository where assets will be deployed (default current) \|
			\| `target_branch` \| String \| Git branch where assets will be deployed (default `gh-pages`) \|
Review some inputs 2019-11-06 10:10:09 +08:00			\| `build_dir` \| String \| Build directory to deploy (required) \|
			\| `commit_name` \| String \| Commit author's name (default [GITHUB_ACTOR](https://help.github.com/en/github/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables) or `github-actions`) \|
			\| `commit_email` \| String \| Commit author's email (default `<committer_name>@users.noreply.github.com`) \|
Update README 2019-11-06 10:02:08 +08:00			\| `commit_message`\| String \| Commit message (default `Deploy to GitHub pages`) \|
Initial version 2019-09-01 04:23:41 +08:00
			`### environment variables`

Limitation using GITHUB_TOKEN 2019-09-01 13:01:38 +08:00			Following environment variables can be used as `step.env` keys
Initial version 2019-09-01 04:23:41 +08:00
			`\| Name \| Description \|`
			`\|----------------\|--------------------------------------\|`
			\| `GITHUB_TOKEN` \| GITHUB_TOKEN as provided by `secrets`\|
Limitation using GITHUB_TOKEN 2019-09-01 13:01:38 +08:00			\| `GITHUB_PAT` \| [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) (see Limitation section below)\|

			`## :warning: Limitation`

Update README 2019-11-11 13:57:13 +08:00			Currently, `GITHUB_TOKEN` [does not suffice to trigger a page build](https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/26869) on a public repository (propagate content to the GitHub content-delivery network). You must therefore create a custom [Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) and use it through the `GITHUB_PAT` environment variable:
Limitation using GITHUB_TOKEN 2019-09-01 13:01:38 +08:00
			```yaml
			`- name: Deploy`
			`if: success()`
Use v1 2019-10-11 07:51:17 +08:00			`uses: crazy-max/ghaction-github-pages@v1`
Limitation using GITHUB_TOKEN 2019-09-01 13:01:38 +08:00			`with:`
			`target_branch: gh-pages`
			`build_dir: public`
			`env:`
			`GITHUB_PAT: ${{ secrets.GITHUB_PAT }}`
			```
Initial version 2019-09-01 04:23:41 +08:00
			`## 🤝 How can I help ?`

Update README 2019-11-15 02:25:19 +08:00			`All kinds of contributions are welcome :raised_hands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon: You can also support this project by [becoming a sponsor on GitHub](https://github.com/sponsors/crazy-max) :clap: or by making a [Paypal donation](https://www.paypal.me/crazyws) to ensure this journey continues indefinitely! :rocket:`
Initial version 2019-09-01 04:23:41 +08:00
Update README 2019-11-15 02:25:19 +08:00			`Thanks again for your support, it is much appreciated! :pray:`
Initial version 2019-09-01 04:23:41 +08:00
			`## 📝 License`

			MIT. See `LICENSE` for more details.