uwhackweek · scottyhq · Jun 13, 2024 · Jun 13, 2024 · Jun 13, 2024 · Jun 13, 2024
diff --git a/.github/workflows/netlifypreview.yaml b/.github/workflows/netlifypreview.yaml
@@ -37,9 +37,10 @@ jobs:
       uses: nwtgck/[email protected]
       with:
         publish-dir: './book/_build/html'
-        production-deploy: false
         github-token: ${{ secrets.GITHUB_TOKEN }}
         deploy-message: "Deploy from GitHub Actions"
+        enable-github-deployment: false
+        enable-commit-status: false
         enable-commit-comment: false
         enable-pull-request-comment: true
         overwrites-pull-request-comment: true

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,7 @@
+# Recommended Additional Configuration
+
+Some template features require additional GitHub settings. For example, the [netlifypreview.yaml](.github/workflows/netlifypreview.yaml) workflow requires a [netlify account](https://www.netlify.com) and configuring Netlify and GitHub to work together
+
+[github-setup.md](./github-setup.md): Our recommendations for configuring a GitHub organization and managing secrets for a Hackweek
+
+[netlify-setup.md](./netlify-setup.md): Documentation on setting up previews of website changes in pull requests with Netlify
diff --git a/docs/github-setup.md b/docs/github-setup.md
@@ -0,0 +1,27 @@
+# GitHub Setup
+
+## GitHub Organization
+
+We recommend that each hackweek creates a [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations) to manage various repositories for an event. This makes organizing teams of users easy and consolidates content such as project work and tutorials for easier discoverability. It also allows managing secrets and making them available to different repositories if necessary.
+
+## Hackweek Bots
+
+For NASA-focused hackweeks we created a "bot" user with a Gmail account, GitHub Account https://github.com/hackweek-admin, and NASA Earthdata login (https://urs.earthdata.nasa.gov) to allow GitHub Actions workflows to access NASA Data with a set of credentials that do not belong to any individual.
+
+## GitHub Actions Secrets
+
+We can add credentials as ["Organization Secrets"](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) and make them available to only select repositories that need them. For example see the screenshots below on giving the `EARTHDATA_PASS` secret to a specific repository
+
+1. ### Repository secrets are under `Settings` -> `Secrets and variables` 
+
+   For example, replace `snowex-hackweek/website-2024` for your repository in the following URL: https://github.com/snowex-hackweek/website-2024/settings/secrets/actions  
+
+   **only people with `admin` access to a repository can access these settings**
+
+   ![Repo secrets](./images/github-repo-secrets.png)
+
+1. ### Select `Manage organization secrets`. 
+
+   You can either create a new one, or click the "pencil" icon of an existing one to give access to a new repository
+
+   ![Org Secrets](./images/github-org-secrets-list.png)
diff --git a/docs/images/github-org-secrets-list.png b/docs/images/github-org-secrets-list.png
diff --git a/docs/images/github-repo-secrets.png b/docs/images/github-repo-secrets.png
diff --git a/docs/images/github-repo-secrets2.png b/docs/images/github-repo-secrets2.png
diff --git a/docs/images/netlify-addsite.png b/docs/images/netlify-addsite.png
diff --git a/docs/images/netlify-auth-token.png b/docs/images/netlify-auth-token.png
diff --git a/docs/images/netlify-install-github-app.png b/docs/images/netlify-install-github-app.png
diff --git a/docs/images/netlify-link-github.png b/docs/images/netlify-link-github.png
diff --git a/docs/images/netlify-repo-access.png b/docs/images/netlify-repo-access.png
diff --git a/docs/images/netlify-select-org.png b/docs/images/netlify-select-org.png
diff --git a/docs/images/netlify-select-repo.png b/docs/images/netlify-select-repo.png
diff --git a/docs/images/netlify-stop-builds.png b/docs/images/netlify-stop-builds.png
diff --git a/docs/netlify-setup.md b/docs/netlify-setup.md
@@ -0,0 +1,63 @@
+# Configuring Netlify for pull request previews
+
+Public websites for hackweeks have content contributed by many different people, and we want to ensure that they are well-formatted and functional at all times. In order to do this, we "preview" changes to a website to confirm it all looks good before merging new content. There are different ways to accomplish this, but we have found that [Netlify](https://www.netlify.com) is free and works well for previews. 
+
+## Link Netlify to a repository
+
+Netlify organizes websites by "Site" which is tied to a specific GitHub repository. *All preview links created are persistent and public but not indexed by search engines.* If you want to delete them, you can delete the 'Site' from Netlify. Importantly, the Netlify previews are completely decoupled from the main website that is hosted by GitHub Pages, so you do not need to worry about overwriting or losing your main event webpage!
+
+1. ### Make sure the Netlify App is installed for your organization
+
+   Go to https://github.com/apps/netlify/installations/select_target or visit GitHub Org settings for GitHub Apps (e.g. https://github.com/organizations/snowex-hackweek/settings/installations):
+
+   ![Add Site](./images/netlify-install-github-app.png)
+
+   Under 'Configure' for Netlify you can select which repositories Netlify has access to: 
+
+   ![Add Site](./images/netlify-repo-access.png)
+
+1. ### Log into Netlify and 'Add new site'
+
+   ![Add Site](./images/netlify-addsite.png)
+
+1. ### Select deploy project with GitHub
+
+   ![Link GitHub](./images/netlify-link-github.png)
+
+1. ### Select correct GitHub Organization for website repo
+
+   ![Select org](./images/netlify-select-org.png)
+
+1. ### Select correct repository based on this template (e.g. website-2024)
+
+   ![Select repo](./images/netlify-select-repo.png)
+
+   For 'Site name' enter something informative like `snowex-website-2024` and click 'Deploy'
+
+1. ### Disable netlify main deployment
+
+   Important!! We only want to use Netlify for *Previews* so under 'Site Configuration' -> 'Build & Deploy' -> 'Continuous deployment' -> 'Build settings' select "Stopped Builds"
+   (e.g. https://app.netlify.com/sites/snowex-website-2024/configuration/deploys)
+
+   If you do not do this, you will have a public mirror of your website available at your netlify site name (https://snowex-website-2024.netlify.app)
+
+   ![Disable builds](./images/netlify-stop-builds.png)
+
+1. ### Copy unique NETLIFY_SITE_ID to use in GitHub Actions Workflows
+
+   Copy the "Site ID" token string under "Site Details", it will look something like this "f9235abc-688d-45e4-8f62-5519ghi455j1"
+
+   (e.g. https://app.netlify.com/sites/snowex-website-2024/configuration/general)
+
+1. ### Create a NETLIFY_AUTH_TOKEN to use in GitHub Actions workflows
+
+   Go to https://app.netlify.com/user/applications and under 'Personal access token' create a new token with optional expiration. It will look something like this `nfp_8abcUxd2ESPs9yEegb3ATSBst13JicvY135s`
+
+   ![Auth token](./images/netlify-auth-token.png)
+
+
+1. ### Add GitHub Action Secrets to your repository
+
+   In the end, a website repository needs to have access to both `NETLIFY_AUTH_TOKEN` and a specific `NETLIFY_SITE_ID` for the preview workflow to function:
+
+   ![Repo secrets final](./images/github-repo-secrets2.png)