From 94eefc87ba7162ab12e35021469b0363195996c1 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Wed, 3 Jan 2018 16:42:27 -0800 Subject: [PATCH] Update publishing docs and API information Some environment variables can be set by the CircleCI build itself Document `USE_SSH` --- docs/api-commands.md | 17 ++++++++++++++++- docs/getting-started-publishing.md | 13 +++++++++---- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/api-commands.md b/docs/api-commands.md index 9477fba155fe..c21734447d63 100644 --- a/docs/api-commands.md +++ b/docs/api-commands.md @@ -74,11 +74,26 @@ Alias: `publish-gh-pages` [Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined: +The following is generally set manually by the user in the CircleCI `config.yml` file. + - `GIT_USER`: The git user to be associated with the deploy commit. + - `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo. + + e.g., + + ```bash + GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages + ``` + +The following are set by the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/) during the build process. + - `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run. + - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request. + +The following should be set by you in `siteConfig.js` as `organizationName` and `projectName`, respectively. If they are not set in your site configuration, they fall back to the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/). + - `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the git repo, e.g. "facebook". - `CIRCLE_PROJECT_REPONAME`: The name of the git repo, e.g. "Docusaurus". - - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request. You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md). diff --git a/docs/getting-started-publishing.md b/docs/getting-started-publishing.md index 00d1bb89ff60..e5e5dc4401e8 100644 --- a/docs/getting-started-publishing.md +++ b/docs/getting-started-publishing.md @@ -42,9 +42,11 @@ One of the required parameters is set as a environment variable: - `GIT_USER`: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username. -There is also an optional parameter that is set as an environment variable. If nothing is set for this variable, then the current branch will be used. +There are also two optional parameters that are set as environment variables: -- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. +- `USE_SSH`: If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set. + +- `CURRENT_BRANCH`: The branch that contains the latest docs changes that will be deployed. Usually, the branch will be `master`, but it could be any branch (default or otherwise) except for `gh-pages`. If nothing is set for this variable, then the current branch will be used. > Docusaurus also supports deploying user or organization sites. Just set your project name to "_username_.github.io" (where _username_ is your username or organization name on GitHub) and the publish script will automatically deploy your site to the root of the `master` branch instead. @@ -52,9 +54,10 @@ Once you have the parameter value information, you can go ahead and run the publ To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. -``` +```bash GIT_USER= \ CURRENT_BRANCH=master \ + USE_SSH=true \ yarn run publish-gh-pages # or `npm run publish-gh-pages` ``` @@ -106,7 +109,9 @@ Make sure to replace `` with the actual username of the GitHub account **DO NOT** place the actual value of `$GITHUB_TOKEN` in `circle.yml`. We already configured that as an environment variable back in Step 3. -> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the values of `ORGANIZATION_NAME`, `PROJECT_NAME`, and `CURRENT_BRANCH` are already defined as environment variables within CircleCI and will be picked up by the script automatically. +> If you want to use SSH for your GitHub repo connection, you can set `USE_SSH=true`. So the above command would look something like: `cd website && npm install && GIT_USER= USE_SSH=true npm run publish-gh-pages`. + +> Unlike when you run the `publish-gh-pages` script manually, when the script runs within the Circle environment, the value of `CURRENT_BRANCH` is already defined as an [environment variable within CircleCI](https://circleci.com/docs/1.0/environment-variables/) and will be picked up by the script automatically. Now, whenever a new commit lands in `master`, CircleCI will run your suite of tests and, if everything passes, your website will be deployed via the `publish-gh-pages` script.