diff --git a/.github/workflows/netlifypreview.yaml b/.github/workflows/netlifypreview.yaml index 3f9eea57..de9372e4 100644 --- a/.github/workflows/netlifypreview.yaml +++ b/.github/workflows/netlifypreview.yaml @@ -37,9 +37,10 @@ jobs: uses: nwtgck/actions-netlify@v3.0 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 new file mode 100644 index 00000000..2eb08cb0 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/github-setup.md b/docs/github-setup.md new file mode 100644 index 00000000..04db60ff --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/images/github-org-secrets-list.png b/docs/images/github-org-secrets-list.png new file mode 100644 index 00000000..04902ce0 Binary files /dev/null and b/docs/images/github-org-secrets-list.png differ diff --git a/docs/images/github-repo-secrets.png b/docs/images/github-repo-secrets.png new file mode 100644 index 00000000..03158f8d Binary files /dev/null and b/docs/images/github-repo-secrets.png differ diff --git a/docs/images/github-repo-secrets2.png b/docs/images/github-repo-secrets2.png new file mode 100644 index 00000000..94877532 Binary files /dev/null and b/docs/images/github-repo-secrets2.png differ diff --git a/docs/images/netlify-addsite.png b/docs/images/netlify-addsite.png new file mode 100644 index 00000000..3a9fcdcc Binary files /dev/null and b/docs/images/netlify-addsite.png differ diff --git a/docs/images/netlify-auth-token.png b/docs/images/netlify-auth-token.png new file mode 100644 index 00000000..151ea94a Binary files /dev/null and b/docs/images/netlify-auth-token.png differ diff --git a/docs/images/netlify-install-github-app.png b/docs/images/netlify-install-github-app.png new file mode 100644 index 00000000..4dbf26a5 Binary files /dev/null and b/docs/images/netlify-install-github-app.png differ diff --git a/docs/images/netlify-link-github.png b/docs/images/netlify-link-github.png new file mode 100644 index 00000000..13c16d7e Binary files /dev/null and b/docs/images/netlify-link-github.png differ diff --git a/docs/images/netlify-repo-access.png b/docs/images/netlify-repo-access.png new file mode 100644 index 00000000..f74237da Binary files /dev/null and b/docs/images/netlify-repo-access.png differ diff --git a/docs/images/netlify-select-org.png b/docs/images/netlify-select-org.png new file mode 100644 index 00000000..ebeac4f2 Binary files /dev/null and b/docs/images/netlify-select-org.png differ diff --git a/docs/images/netlify-select-repo.png b/docs/images/netlify-select-repo.png new file mode 100644 index 00000000..f29166fb Binary files /dev/null and b/docs/images/netlify-select-repo.png differ diff --git a/docs/images/netlify-stop-builds.png b/docs/images/netlify-stop-builds.png new file mode 100644 index 00000000..315dc140 Binary files /dev/null and b/docs/images/netlify-stop-builds.png differ diff --git a/docs/netlify-setup.md b/docs/netlify-setup.md new file mode 100644 index 00000000..dbba6e35 --- /dev/null +++ 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) \ No newline at end of file