Skip to content

ci(docs): publish the internal preview from the internal-preview branch #214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flozanofdez merged 1 commit into from
Sep 11, 2026
Merged

ci(docs): publish the internal preview from the internal-preview branch #214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ name: Deploy to GitHub Pages

on:
pull_request:
branches: [main, dev]
branches: [main, dev, internal-preview]
push:
branches: [main, dev, docs-v2]
branches: [main, dev, internal-preview]
workflow_dispatch:

jobs:
Expand All @@ -29,8 +29,8 @@ jobs:
run: yarn build

# Publishes the public documentation sites. Restricted to main and dev on
# purpose: the docs-v2 branch goes to the internal preview job below, and a
# GitHub Pages deploy would make its internal-only pages public.
# purpose: the internal-preview branch goes to the internal preview job
# below, and a GitHub Pages deploy would make its internal-only pages public.
deploy:
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
runs-on: ubuntu-latest
Expand Down Expand Up @@ -62,19 +62,19 @@ jobs:
yarn generate
yarn deploy

# Internal preview of the docs-v2 branch (Jira PRODUCT-190).
# Internal preview of the internal-preview branch (Jira PRODUCT-190, PRODUCT-209).
# Publishes to https://developers-internal.handpoint.io in the staging
# account. A WAF permits the office VPN only, so the site is not public.
deploy-staging:
if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/docs-v2'
if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/internal-preview'
runs-on: ubuntu-latest
timeout-minutes: 15

# Queue a later push instead of cancelling the running one. Cancelling
# could abort "aws s3 sync --delete" halfway and leave the site partly
# published, with no successful run to repair it.
concurrency:
group: deploy-staging-docs-v2
group: deploy-staging-internal-preview
cancel-in-progress: false

permissions:
Expand Down
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ yarn --version # should be 1.x
# 1. Clone the repo (or pull the branch if you already have it)
git clone <repo-url>
cd <repo-name>
git checkout docs-v2
git checkout internal-preview

# 2. Install dependencies
yarn install
Expand Down Expand Up @@ -99,16 +99,17 @@ Static output goes to `build/`. Serve it locally with `yarn serve`.

## Internal preview of this branch

The `docs-v2` branch publishes to an internal preview site:
The `internal-preview` branch publishes to an internal preview site:

- <https://developers-internal.handpoint.io>

**You must be on the office VPN to open it.** Any other connection receives a
403 and a page that says the VPN is required. Ask the infrastructure team to
add your address if you are on the VPN and still see that page.

A push to `docs-v2` publishes the site again through GitHub Actions. To publish
by hand:
A push to `internal-preview` publishes the site again through GitHub Actions.
Open your pull request against `internal-preview`. A merge publishes it, and the
pull request runs a build check first. To publish by hand:

```bash
AWS_PROFILE=test ./scripts/deploy-staging.sh
Expand All @@ -118,7 +119,7 @@ The preview runs `DOCS_ENV=staging`, so it shows the pages marked
`visibility: internal`. That is why the site stays behind the VPN.

The infrastructure and its runbook live in the `handpoint-scripts` repository,
under `aws/docs-v2/infra/`. This preview is separate from the public sites at
under `aws/documentation/infra/`. This preview is separate from the public sites at
`developer.handpoint.com` and `developer.handpoint.io`, which GitHub Pages
serves from `main` and `dev`.

Expand Down
2 changes: 1 addition & 1 deletion docs-internal/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> **INTERNAL ONLY — Handpoint Staff**
>
> Files in this directory are **never merged to `dev` or `main`**. They exist only on the `docs-v2` branch.
> Files in this directory are **never merged to `dev` or `main`**. They exist only on the `internal-preview` branch.
> Do not include `docs-internal/` in PRs targeting `dev` or `main`.
> This directory is outside Docusaurus's `docs/` folder and is never built or published.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/known-issues.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,6 @@ import KnownIssues from '@site/src/components/KnownIssues';

Tracked bugs across all Handpoint SDK and API products. Issues marked **Open** have no fix yet — check the workaround column. Issues marked **Fixed** include the version that resolved them.

To add or update an issue, edit [`data/knownIssues.js`](https://github.com/handpoint/doc/blob/docs-v2/data/knownIssues.js). Use `visibility: 'internal'` for issues not ready for public disclosure.
To add or update an issue, edit [`data/knownIssues.js`](https://github.com/handpoint/doc/blob/internal-preview/data/knownIssues.js). Use `visibility: 'internal'` for issues not ready for public disclosure.

<KnownIssues />