fix docs publish

[eschultink]

Fixes

• publish tool failing bc Gitbook perms on duplicated site don't propagate instantly, so gives 403

Features

• eliminate prompt for version, if next patch and prior patch exists

Change implications

• dependencies added/changed? no
• something important to note in future release notes? no

[Copilot]

Pull request overview

This PR fixes issues with the GitBook documentation publishing tool by addressing permission propagation delays and adding automatic version detection. The main issue was that duplicated GitBook spaces don't immediately receive proper permissions, causing 403 errors. Additionally, the script now automatically detects the previous patch release version to duplicate from, eliminating manual prompts when possible.

Changes:

• Added automatic detection of the previous patch release version (e.g., 0.5.17 → 0.5.16) to eliminate user prompts when the prior version exists
• Added a 10-second delay after space duplication to allow GitBook permissions to propagate before making subsequent API calls
• Implemented retry logic with additional delays for both space title updates and site-space additions to handle transient permission errors
• Enhanced error handling and logging throughout the GitBook API interactions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PATCH request to update the space title no longer includes the "parent" field that was present in the original code. This field was previously set to the GITBOOK_PROXY_DOCS_SITE_ID. If this field is required by the GitBook API to properly associate the space with the parent site, removing it could cause the space to not be properly nested or organized. Consider whether this field should be retained or if its removal was intentional.

Suggested change

	PATCH_RES=$(curl -s -X PATCH https://api.gitbook.com/v1/spaces/${SPACE_ID} -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"title": "'$NUMERIC_RELEASE'"}')
	if echo "$PATCH_RES" | grep -q '"error"'; then
	printf "${RED}Error updating space title:${NC}\n"
	echo "$PATCH_RES" | jq .
	printf "${YELLOW}Retrying after 5 more seconds...${NC}\n"
	sleep 5
	PATCH_RES=$(curl -s -X PATCH https://api.gitbook.com/v1/spaces/${SPACE_ID} -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"title": "'$NUMERIC_RELEASE'"}')
	PATCH_RES=$(curl -s -X PATCH https://api.gitbook.com/v1/spaces/${SPACE_ID} -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"title": "'$NUMERIC_RELEASE'", "parent": "'$GITBOOK_PROXY_DOCS_SITE_ID'"}')
	if echo "$PATCH_RES" | grep -q '"error"'; then
	printf "${RED}Error updating space title:${NC}\n"
	echo "$PATCH_RES" | jq .
	printf "${YELLOW}Retrying after 5 more seconds...${NC}\n"
	sleep 5
	PATCH_RES=$(curl -s -X PATCH https://api.gitbook.com/v1/spaces/${SPACE_ID} -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"title": "'$NUMERIC_RELEASE'", "parent": "'$GITBOOK_PROXY_DOCS_SITE_ID'"}')

[Copilot]

The retry logic for updating the space title should also include the "parent" field if it was intentionally removed from line 119. However, if the "parent" field is needed, both the initial attempt and retry should include it. Verify whether the "parent" field was intentionally removed or if it should be present in the retry attempt as well.

[Copilot]

Inconsistent indentation detected. Lines 156-160 use 5 spaces for indentation, while the rest of the file appears to use 2 spaces. This should be corrected to maintain consistent formatting throughout the script.

Suggested change

	# maybe it uses spaceId? rollback and retry
	printf "${YELLOW}Trying with spaceId payload...${NC}\n"
	POST_SITE_SPACE_RES=$(curl -s -X POST https://api.gitbook.com/v1/orgs/${GITBOOK_ORGANIZATION_ID}/sites/${GITBOOK_PROXY_DOCS_SITE_ID}/site-spaces -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"spaceId": "'$SPACE_ID'"}')
	SITE_SPACE_ID=$(echo "$POST_SITE_SPACE_RES" | jq -r '.uid // .id // empty')
	# maybe it uses spaceId? rollback and retry
	printf "${YELLOW}Trying with spaceId payload...${NC}\n"
	POST_SITE_SPACE_RES=$(curl -s -X POST https://api.gitbook.com/v1/orgs/${GITBOOK_ORGANIZATION_ID}/sites/${GITBOOK_PROXY_DOCS_SITE_ID}/site-spaces -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"spaceId": "'$SPACE_ID'"}')
	SITE_SPACE_ID=$(echo "$POST_SITE_SPACE_RES" | jq -r '.uid // .id // empty')

[Copilot]

Inconsistent indentation detected. Line 170 uses 8 spaces for indentation instead of the expected 4 spaces (2 space increments). This should be corrected to maintain consistent formatting.

Suggested change

	printf "${RED}Failed again to add space to site. Giving up. Response:${NC}\n"
	echo "$POST_SITE_SPACE_RES" | jq .
	exit 1
	printf "${RED}Failed again to add space to site. Giving up. Response:${NC}\n"
	echo "$POST_SITE_SPACE_RES" | jq .
	exit 1

[Copilot]

The retry mechanism at line 167 retries with the "space" field, but this is the same as what was already tried at line 152. If the first attempt with "space" failed at line 152 and the fallback to "spaceId" at line 158 also failed, retrying with "space" again may not be effective. Consider whether this retry should use "spaceId" instead, or if there should be logic to alternate between both approaches in the retry.

Suggested change

	POST_SITE_SPACE_RES=$(curl -s -X POST https://api.gitbook.com/v1/orgs/${GITBOOK_ORGANIZATION_ID}/sites/${GITBOOK_PROXY_DOCS_SITE_ID}/site-spaces -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"space": "'$SPACE_ID'"}')
	POST_SITE_SPACE_RES=$(curl -s -X POST https://api.gitbook.com/v1/orgs/${GITBOOK_ORGANIZATION_ID}/sites/${GITBOOK_PROXY_DOCS_SITE_ID}/site-spaces -H "Authorization: Bearer ${GITBOOK_API_TOKEN}" -H "Content-Type: application/json" -d '{"spaceId": "'$SPACE_ID'"}')