From 5fc159b53f15beabd57d2c825d967854c6dd6903 Mon Sep 17 00:00:00 2001 From: Tauhid Date: Wed, 22 Oct 2025 11:43:35 +0530 Subject: [PATCH 1/6] Sync cloud docs workflow --- .../workflows/create-tfe-release-notes.yml | 4 +- .github/workflows/sync-docs-for-tfe.yml | 118 ++++++++++++++++++ 2 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/sync-docs-for-tfe.yml diff --git a/.github/workflows/create-tfe-release-notes.yml b/.github/workflows/create-tfe-release-notes.yml index ff93e9b026..f48ceeea1d 100644 --- a/.github/workflows/create-tfe-release-notes.yml +++ b/.github/workflows/create-tfe-release-notes.yml @@ -34,8 +34,8 @@ env: LAST_RELEASE_TAG: ${{ inputs.last-release-tag }} jobs: - copy-docs: - uses: ./.github/workflows/copy-cloud-docs-for-tfe.yml + sync-docs: + uses: ./.github/workflows/sync-docs-for-tfe.yml with: version: ${{ inputs.version }} secrets: inherit diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml new file mode 100644 index 0000000000..f9dbc9b144 --- /dev/null +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -0,0 +1,118 @@ +name: Sync Cloud Docs For TFE + +on: + workflow_dispatch: + inputs: + version: + description: 'The TFE version for the upcoming TFE release, format is either vYYYYMM-# or MAJOR.MINOR.PATCH (without a "v" prefix).' + required: true + type: string + workflow_call: + inputs: + version: + description: 'The TFE version for the upcoming TFE release, format is either vYYYYMM-# or MAJOR.MINOR.PATCH (without a "v" prefix).' + required: true + type: string + outputs: + release_branch_name: + description: 'The name of the branch created for the new TFE version docs.' + value: ${{ jobs.copy-docs.outputs.release_branch_name }} + release_branch_pr_url: + description: 'The URL of the release branch created for the new TFE version docs.' + value: ${{ jobs.copy-docs.outputs.release_branch_pr_url }} + diff_branch_pr_url: + description: 'The URL of the diff branch created for the new TFE version docs.' + value: ${{ jobs.copy-docs.outputs.diff_branch_pr_url }} + +jobs: + sync-docs: + name: Sync Cloud Docs + runs-on: ubuntu-latest + outputs: + release_branch_name: ${{ steps.check-docs-pr.outputs.docs_branch_name }} + release_branch_pr_url: ${{ steps.check-docs-pr.outputs.release_branch_pr_url }} + diff_branch_pr_url: ${{ steps.update-diff-branch.outputs.diff_branch_pr_url }} + steps: + - name: Series/Release Summary + run: | + echo "# Summary" >> $GITHUB_STEP_SUMMARY + echo "**Workflow ref**: ${{github.ref_name}}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Triggered by branch creation (or manual workflow):" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "---" >> $GITHUB_STEP_SUMMARY + + - name: Checkout main for new docs version + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 + with: + path: '${{github.workspace}}/new-docs' + + - name: Check if new TFE version docs branch already exist + id: check-docs-pr + working-directory: '${{github.workspace}}/new-docs' + env: + docs_branch_name: tfe-release/${{inputs.version}} + diff_branch_name: HCPTF-diff/${{inputs.version}} + run: | + echo ${{ secrets.TFE_GITHUB_TOKEN }} | gh auth login --with-token + git config --global user.email "team-rel-eng@hashicorp.com" + git config --global user.name "tfe-release-bot" + + if [ "$(git ls-remote --heads origin ${{env.docs_branch_name}})" == "" ]; then + echo "❌ branch name ${{env.docs_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." + + echo "❌ branch name ${{env.docs_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." >> $GITHUB_STEP_SUMMARY + + exit 1 + fi + + if [ "$(git ls-remote --heads origin ${{env.diff_branch_name}})" == "" ]; then + echo "❌ branch name ${{env.diff_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." + + echo "❌ branch name ${{env.diff_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." >> $GITHUB_STEP_SUMMARY + + exit 1 + fi + + echo "docs_branch_name=${{env.docs_branch_name}}" >> $GITHUB_OUTPUT + docs_pr_url=$(gh pr view ${{env.docs_branch_name}} --json url --jq '.url') + echo "release_branch_pr_url=${docs_pr_url}" >> $GITHUB_OUTPUT + echo "**TFE Release PR URL**: ${docs_pr_url}" >> $GITHUB_STEP_SUMMARY + + - name: Generate version-metadata for workflow + working-directory: '${{github.workspace}}/new-docs' + run: | + npm i + npm run prebuild -- --only-build-version-metadata + + - name: Checkout HCPTF-diff for new docs version DIFF PR + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 + with: + path: '${{github.workspace}}/new-docs-diff-pr' + ref: 'HCPTF-diff/${{inputs.version}}' + + - name: Copy files for new docs version DIFF PR + uses: ./new-docs/.github/actions/copy-cloud-docs-for-tfe + with: + source_path: '${{github.workspace}}/new-docs' + target_path: '${{github.workspace}}/new-docs-diff-pr' + new_TFE_version: ${{inputs.version}} + + - name: Update existing docs version DIFF branch + id: update-diff-branch + working-directory: '${{github.workspace}}/new-docs-diff-pr' + env: + diff_branch_name: HCPTF-diff/${{inputs.version}} + run: | + echo ${{ secrets.TFE_GITHUB_TOKEN }} | gh auth login --with-token + git config --global user.email "team-rel-eng@hashicorp.com" + git config --global user.name "tfe-release-bot" + + git add . + git commit -m "HCP TF changes for TFE release" --no-verify + git push origin HEAD + + diff_pr_url=$(gh pr view --json url --jq '.url') + echo "diff_branch_pr_url=${diff_pr_url}" >> $GITHUB_OUTPUT + echo "**Updated DIFF branch**: ${{env.diff_branch_name}}" >> $GITHUB_STEP_SUMMARY From 4ca2b0b4b94c9ff03591405af0876c2542a2a41f Mon Sep 17 00:00:00 2001 From: Tauhid Date: Wed, 22 Oct 2025 11:49:45 +0530 Subject: [PATCH 2/6] fixing wofkflows --- .../workflows/create-tfe-release-notes.yml | 20 +++++++++---------- .github/workflows/sync-docs-for-tfe.yml | 20 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/.github/workflows/create-tfe-release-notes.yml b/.github/workflows/create-tfe-release-notes.yml index f48ceeea1d..b0956d8d31 100644 --- a/.github/workflows/create-tfe-release-notes.yml +++ b/.github/workflows/create-tfe-release-notes.yml @@ -40,14 +40,14 @@ jobs: version: ${{ inputs.version }} secrets: inherit release-notes: - needs: copy-docs + needs: sync-docs runs-on: ubuntu-latest steps: - - name: Print outputs from copy-docs + - name: Print outputs from sync-docs run: | - echo "release_branch_name: ${{ needs.copy-docs.outputs.release_branch_name }}" - echo "diff_branch_pr_url: ${{ needs.copy-docs.outputs.diff_branch_pr_url }}" - echo "release_branch_pr_url: ${{ needs.copy-docs.outputs.release_branch_pr_url }}" + echo "release_branch_name: ${{ needs.sync-docs.outputs.release_branch_name }}" + echo "diff_branch_pr_url: ${{ needs.sync-docs.outputs.diff_branch_pr_url }}" + echo "release_branch_pr_url: ${{ needs.sync-docs.outputs.release_branch_pr_url }}" - name: Only run in hashicorp/web-unified-docs-internal run: | @@ -59,7 +59,7 @@ jobs: - name: Checkout web-unified-docs repository uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 with: - ref: '${{ needs.copy-docs.outputs.release_branch_name }}' + ref: '${{ needs.sync-docs.outputs.release_branch_name }}' - name: Install and cache Ruby gems at root uses: ruby/setup-ruby@52753b7da854d5c07df37391a986c76ab4615999 # v1.191.0 @@ -74,7 +74,7 @@ jobs: - name: Turn branch into PR run: | - export RELEASE_BRANCH_NAME="${{ needs.copy-docs.outputs.release_branch_name }}" + export RELEASE_BRANCH_NAME="${{ needs.sync-docs.outputs.release_branch_name }}" RELEASE_NOTES_PR_URL=$(scripts/tfe-releases/ci/create-pull-request.sh) echo "RELEASE_NOTES_PR_URL=$RELEASE_NOTES_PR_URL" >> $GITHUB_ENV @@ -134,10 +134,10 @@ jobs: - ${{github.server_url}}/${{github.repository}}/actions/runs/${{github.run_id}} Changes since last release, diff PR: - - ${{ needs.copy-docs.outputs.diff_branch_pr_url }} + - ${{ needs.sync-docs.outputs.diff_branch_pr_url }} Release Notes PR: - - ${{ needs.copy-docs.outputs.release_branch_pr_url }} + - ${{ needs.sync-docs.outputs.release_branch_pr_url }} ❗ This is the Release PR that will be merged into main, once the release notes and diff PR are merged into it. ❗ @@ -149,5 +149,5 @@ jobs: git config --global user.email "team-rel-eng@hashicorp.com" git config --global user.name "tfe-release-bot" - gh pr edit ${{ needs.copy-docs.outputs.release_branch_pr_url }} \ + gh pr edit ${{ needs.sync-docs.outputs.release_branch_pr_url }} \ --body="${{env.docs_pr_body}}" diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml index f9dbc9b144..0c7c414530 100644 --- a/.github/workflows/sync-docs-for-tfe.yml +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -14,15 +14,15 @@ on: required: true type: string outputs: - release_branch_name: - description: 'The name of the branch created for the new TFE version docs.' - value: ${{ jobs.copy-docs.outputs.release_branch_name }} - release_branch_pr_url: - description: 'The URL of the release branch created for the new TFE version docs.' - value: ${{ jobs.copy-docs.outputs.release_branch_pr_url }} - diff_branch_pr_url: - description: 'The URL of the diff branch created for the new TFE version docs.' - value: ${{ jobs.copy-docs.outputs.diff_branch_pr_url }} + release_branch_name: + description: 'The name of the branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_name }} + release_branch_pr_url: + description: 'The URL of the release branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_pr_url }} + diff_branch_pr_url: + description: 'The URL of the diff branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.diff_branch_pr_url }} jobs: sync-docs: @@ -110,7 +110,7 @@ jobs: git config --global user.name "tfe-release-bot" git add . - git commit -m "HCP TF changes for TFE release" --no-verify + git commit -m "HCP TF changes for TFE release" --no-verify || echo "No changes to commit" git push origin HEAD diff_pr_url=$(gh pr view --json url --jq '.url') From f6e118d0d767192a5a37ce2421de3e2852004911 Mon Sep 17 00:00:00 2001 From: Tauhid Date: Wed, 22 Oct 2025 11:51:17 +0530 Subject: [PATCH 3/6] fixing wofkflow indentation --- .github/workflows/sync-docs-for-tfe.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml index 0c7c414530..e7df331738 100644 --- a/.github/workflows/sync-docs-for-tfe.yml +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -13,16 +13,16 @@ on: description: 'The TFE version for the upcoming TFE release, format is either vYYYYMM-# or MAJOR.MINOR.PATCH (without a "v" prefix).' required: true type: string - outputs: - release_branch_name: - description: 'The name of the branch created for the new TFE version docs.' - value: ${{ jobs.sync-docs.outputs.release_branch_name }} - release_branch_pr_url: - description: 'The URL of the release branch created for the new TFE version docs.' - value: ${{ jobs.sync-docs.outputs.release_branch_pr_url }} - diff_branch_pr_url: - description: 'The URL of the diff branch created for the new TFE version docs.' - value: ${{ jobs.sync-docs.outputs.diff_branch_pr_url }} + outputs: + release_branch_name: + description: 'The name of the branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_name }} + release_branch_pr_url: + description: 'The URL of the release branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_pr_url }} + diff_branch_pr_url: + description: 'The URL of the diff branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.diff_branch_pr_url }} jobs: sync-docs: From 19b00a822e4f181b4b9a6bf607494bd62126cb8d Mon Sep 17 00:00:00 2001 From: Tauhid Date: Wed, 22 Oct 2025 12:08:44 +0530 Subject: [PATCH 4/6] Outputting diff PR link as well --- .github/workflows/sync-docs-for-tfe.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml index e7df331738..37cd56a8e1 100644 --- a/.github/workflows/sync-docs-for-tfe.yml +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -116,3 +116,4 @@ jobs: diff_pr_url=$(gh pr view --json url --jq '.url') echo "diff_branch_pr_url=${diff_pr_url}" >> $GITHUB_OUTPUT echo "**Updated DIFF branch**: ${{env.diff_branch_name}}" >> $GITHUB_STEP_SUMMARY + echo "**TFE DIFF PR URL**: ${diff_branch_pr_url}" >> $GITHUB_STEP_SUMMARY From 0aa84ff99d7680da3beddc4c071fbce6dc531f57 Mon Sep 17 00:00:00 2001 From: Tauhid Date: Wed, 22 Oct 2025 12:13:53 +0530 Subject: [PATCH 5/6] Outputting diff PR link as well --- .github/workflows/sync-docs-for-tfe.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml index 37cd56a8e1..7a1f932055 100644 --- a/.github/workflows/sync-docs-for-tfe.yml +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -116,4 +116,4 @@ jobs: diff_pr_url=$(gh pr view --json url --jq '.url') echo "diff_branch_pr_url=${diff_pr_url}" >> $GITHUB_OUTPUT echo "**Updated DIFF branch**: ${{env.diff_branch_name}}" >> $GITHUB_STEP_SUMMARY - echo "**TFE DIFF PR URL**: ${diff_branch_pr_url}" >> $GITHUB_STEP_SUMMARY + echo "**TFE DIFF PR URL**: ${diff_pr_url}" >> $GITHUB_STEP_SUMMARY From 70315e246c948e42864067ffaddc62d43bd16dd9 Mon Sep 17 00:00:00 2001 From: Tauhid Date: Thu, 23 Oct 2025 12:56:36 +0530 Subject: [PATCH 6/6] updating the release artifacts generation process doc --- .../infrastructure-group/publish-tfe-docs.md | 34 ++++++++++++++----- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/workflows/infrastructure-group/publish-tfe-docs.md b/docs/workflows/infrastructure-group/publish-tfe-docs.md index 985e31859e..833e807ec8 100644 --- a/docs/workflows/infrastructure-group/publish-tfe-docs.md +++ b/docs/workflows/infrastructure-group/publish-tfe-docs.md @@ -6,6 +6,17 @@ This page describes the process for publishing Terraform Enterprise documentatio The team releases a milestone or major version once a quarter and releases patches as they become available. +## Artifacts for next major release + +After the release of a major verson, the release engineer runs a GitHub [workflow]((https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml)) in the `web-unified-docs-internal` repository that creates the following artifacts: + +- A branch named `tfe-release/..x` for assembling the release notes and documentation updates. This is the branch that you merge into `main` to publish the docs. +- A branch named `HCPTF-diff/..x` that contains a diff of all of the new content from HCP TF slated for the next Terraform Enterprise release. This branch will be updated with latest changes before next release. +- A PR named `HCP TF changes for TFE release ..x` for merging content updates into the release notes into the assembly branch. Review this PR and merge into the assembly branch. +- A PR named `TFE Release ..x` for merging the release notes into the assembly branch. + +Refer to the [TFE Release 1.0.0](https://github.com/hashicorp/web-unified-docs-internal/pull/299) to see examples of the app deadline artifacts. + ## Get the release date Check the `#proj-tfe-releases` channel for a message from the team manager about important dates. For example: @@ -20,14 +31,7 @@ More details - Ask for the dates in the channel if it has been more than six weeks since the last milestone or major version and the manager hasn't posted the dates yet. You should also verify that the dates haven't changed closer to the standing date. -**Application Code Deadline**: Also called **app deadline**, this is the Terraform Enterprise code freeze and occurs 1.5 to 2 weeks before the release date. App deadline is also when the release engineer runs a GitHub workflow in the `web-unified-docs-internal` repository that creates the following artifacts: - -- A branch named `tfe-release/..x` for assembling the release notes and documentation updates. This is the branch that you merge into `main` to publish the docs. -- A branch named `HCPTF-diff/..x` that contains a diff of all of the new content from HCP TF slated for the next Terraform Enterprise release. -- A PR named `HCP TF changes for TFE release ..x` for merging content updates into the release notes into the assembly branch. Review this PR and merge into the assembly branch. -- A PR named `TFE Release ..x` for merging the release notes into the assembly branch. - -Refer to the [TFE Release 1.0.0](https://github.com/hashicorp/web-unified-docs-internal/pull/299) to see examples of the app deadline artifacts. +**Application Code Deadline**: Also called **app deadline**, this is the Terraform Enterprise code freeze and occurs 1.5 to 2 weeks before the release date. App deadline is also when the release engineer runs a GitHub [workflow]((https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml)) in the `web-unified-docs-internal` repository. The workkflow creates the release notes and updates the `HCPTF-diff/..x` branch with latest changes from terraform common docs. **Backport Deadline**: This is an engineering deadline and isn't actionable for IPG team members. @@ -62,7 +66,19 @@ This section contains supplementary information for publishing Terraform Enterpr ### Manually create docs artifacts for the release -The [Create TFE Release Notes](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml) action creates the release notes PR and triggers the [Copy Cloud Docs For TFE](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml) action. These actions create the branches and PRs necessary for publishing a new version of the Terraform Enterprise documenation. Complete the following steps to manually run the actions: +#### Create the artifacts for next release + +The [Copy Cloud Docs For TFE](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml) action creates the branches and PRs necessary for publishing a new version of the Terraform Enterprise documenation. Complete the following steps to manually run the actions: + +1. Log into GitHub and navigate to the `web-unified-docs-internal` repository. +1. Click **Actions**, then choose **Copy Cloud Docs For TFE** from the **Actions** sidebar. +1. Open the **Run workflow** dropdown and choose the branch to use to run the workflow. This is `main` in almost all cases. +1. Specify the following values: + - Enter the upcoming version of the TFE release. + +#### Create the release notes PR + +The [Create TFE Release Notes](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml) action creates the release notes PR. Complete the following steps to manually run the actions: 1. Log into GitHub and navigate to the `web-unified-docs-internal` repository. 1. Click **Actions**, then choose **Create TFE Release Notes** from the **Actions** sidebar.