From 645c6720168166e536cdaa99273d1be50f28d6a9 Mon Sep 17 00:00:00 2001
From: Enrique Gonzalez <enriikke@gmail.com>
Date: Thu, 31 Jan 2019 00:09:57 -0500
Subject: [PATCH] Add documentation to README and recommended labels to
 Dockerfile

---
 Dockerfile |   4 ++
 README.md  | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)

diff --git a/Dockerfile b/Dockerfile
index 34cfa3de..77dc0a7f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -6,6 +6,10 @@ LABEL "com.github.actions.description"="Build and deploy your Gatsby site to Git
 LABEL "com.github.actions.icon"="book-open"
 LABEL "com.github.actions.color"="purple"
 
+LABEL "repository"="https://github.com/enriikke/gatsby-gh-pages-action"
+LABEL "homepage"="https://github.com/enriikke/gatsby-gh-pages-action"
+LABEL "maintainer"="Enrique Gonzalez <enriikke@gmail.com>"
+
 RUN	apk add --no-cache bash ca-certificates git && npm install --global gatsby-cli
 
 COPY entrypoint /entrypoint
diff --git a/README.md b/README.md
index 79af8ae8..21ea8fbe 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,118 @@
 # Gatsby Publish
 
 GitHub Action to build and deploy your Gatsby site to GitHub Pages ❤️🎩
+
+## Usage
+
+This GitHub Action will run `gatsby build` at the root of your repository and
+deploy it to GitHub Pages for you! Here's a basic workflow example:
+
+```workflow
+workflow "Gatsby to GitHub Pages" {
+  on = "push"
+  resolves = ["Publish"]
+}
+
+action "Publish" {
+  uses = "enriikke/gatsby-gh-pages-action@master"
+  secrets = ["ACCESS_TOKEN"]
+}
+```
+
+It's recommended to use this Action combined with the [Filters Action](https://github.com/actions/bin/tree/c6471707d308175c57dfe91963406ef205837dbd/filter)
+to specify only the branch(es) you want to trigger a build.
+
+```workflow
+workflow "Gatsby to GitHub Pages" {
+  on = "push"
+  resolves = ["Publish"]
+}
+
+action "On Master" {
+  uses = "actions/bin/filter@master"
+  args = "branch master"
+}
+
+action "Publish" {
+  uses = "enriikke/gatsby-gh-pages-action@master"
+  needs = ["On Master"]
+  secrets = ["ACCESS_TOKEN"]
+}
+```
+
+### Knobs & Handles
+
+This Action is fairly simple but it does provide you with a couple of
+configuration options:
+
+- **DEPLOY_BRANCH**: The repository branch used for your GitHub Page and where
+  the Gatsby build will be pushed. Defined as an [environment variable](https://developer.github.com/actions/creating-github-actions/accessing-the-runtime-environment/#environment-variables).
+  Defaults to `gh-pages`.
+
+- **ARGS**: Additional arguments that get passed to `gatsby build`. See the
+  [Gatsby documentation](https://www.gatsbyjs.org/docs/gatsby-cli/#build) for a
+  list of allowed options. Given as [workflow args](https://developer.github.com/actions/creating-github-actions/creating-a-docker-container/#cmd).
+  Defaults to nothing.
+
+### Org or User Pages
+
+Create a repository with the format `<YOUR/ORG USERNAME>.github.io`, push your
+Gatsby source code to the `master` branch,  and add this GitHub Action to your
+workflow! 🚀😃
+
+### Repository Pages
+
+Repo pages work a little different because the URL includes a trailing path with
+the repository name, like `https://username.github.io/reponame/`. You need to
+tell Gatsby what the path prefix is via `gatsby-config.js`:
+
+```js
+module.exports = {
+  pathPrefix: "/reponame",
+}
+```
+
+Additionally, you need to tell the `gatsby build` command to use it by passing
+the `--prefix-paths` as an argument. Here's an example workflow for that:
+
+```workflow
+workflow "Gatsby to GitHub Pages" {
+  on = "push"
+  resolves = ["Publish"]
+}
+
+action "Publish" {
+  uses = "enriikke/gatsby-gh-pages-action@master"
+  args = "--prefix-paths"
+  secrets = ["ACCESS_TOKEN"]
+}
+```
+
+🤩  Note that **NON** of this is necessary if you are using custom domains.🤩
+
+## Requirements
+
+A [GitHub Personal Access Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
+with the `repo` scope is needed to run this Action. This is important! This is
+**NOT** the same as the `GITHUB_TOKEN` that can be included as part of an Action.
+
+Just as important is that this personal access token needs to be provided as a
+[secret](https://developer.github.com/actions/creating-workflows/storing-secrets/)
+with the name `ACCESS_TOKEN`, **NOT** as an environment variable. The reason
+being that secrets get encrypted while environment variables do **NOT**.
+
+Sorry for being so _negative_ just now ☝️. I just want to make sure nobody
+accidentally exposes any sensitive information. Let's keep access tokens safe! 😉😇
+
+### Assumptions
+
+This Action assumes that your Gatsby code sits at the root of your repository
+and `gatsby build` outputs to the `public` directory. As of this writing, Gatsby
+doesn't provide a way to customize the build directory so this should be a safe
+assumption.
+
+
+## That's It
+
+Have fun building! ❤
+