chore: [CLI-936] Prepare documentation synchronization scripts for new Gitbook structure #5955
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,43 +1,108 @@ | ||
| name: Synchronize CLI Help to User Docs | ||
| on: | ||
| workflow_dispatch: | ||
| schedule: | ||
| - cron: '0 9 * * 1' # Monday at 9 | ||
|
|
||
| env: | ||
| DESTINATION_BRANCH: docs/automatic-gitbook-update-cli-help-${{ github.ref_name }} | ||
| COMMIT_MESSAGE: 'docs: synchronizing help from snyk/user-docs' | ||
|
|
||
| jobs: | ||
| build: | ||
| name: synchronize-help | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout user-docs repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: snyk/user-docs | ||
| path: user-docs | ||
| ref: main | ||
|
|
||
| - name: Checkout cli repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: snyk/cli | ||
| ref: ${{ github.ref_name }} | ||
| path: cli | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Configure git user | ||
| run: | | ||
| git config --global user.email "noreply@snyk.io" | ||
|
|
||
| # GITHUB_ACTOR: The name of the person or app that initiated the workflow. | ||
| git config --global user.name "$GITHUB_ACTOR" | ||
|
|
||
| - name: Create or checkout destination branch | ||
| run: | | ||
| cd cli | ||
| if git show-ref --verify --quiet refs/heads/${{ env.DESTINATION_BRANCH }}; then | ||
| echo "Branch ${{ env.DESTINATION_BRANCH }} already exists, checking out." | ||
| git checkout ${{ env.DESTINATION_BRANCH }} | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "Branch ${{ env.DESTINATION_BRANCH }} does not exist, creating and checking out." | ||
| git checkout -b ${{ env.DESTINATION_BRANCH }} | ||
|
|
||
| - name: Copy help documentation from user-docs to CLI | ||
| run: | | ||
| cp ./user-docs/docs/snyk-cli/commands/*.md ./cli/help/cli-commands/ | ||
|
|
||
| - name: Format help files with Prettier | ||
| run: | | ||
| cd ./cli | ||
| npm clean-install | ||
| npx prettier --write ./help/cli-commands/*.md | ||
|
|
||
| - name: Check for changes | ||
| id: check_changes | ||
| run: | | ||
| cd ./cli | ||
| if [[ -z "$(git status --porcelain)" ]]; then | ||
| echo "No documentation changes detected, exiting." | ||
| echo "continue=false" >> "$GITHUB_OUTPUT" | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "--- Documentation changes detected from GitBooks ---" | ||
| git --no-pager diff --color=always | ||
| echo "------------------------------------------------" | ||
|
|
||
| echo "continue=true" >> "$GITHUB_OUTPUT" | ||
|
|
||
| - name: Commit and push changes (if any) | ||
| if: steps.check_changes.outputs.continue == 'true' | ||
| run: | | ||
| cd ./cli | ||
| git add help | ||
| git commit -m "${{ env.COMMIT_MESSAGE }}" | ||
| git push --force --set-upstream origin ${{ env.DESTINATION_BRANCH }} | ||
|
|
||
| - name: Create or update a pull request | ||
| if: steps.check_changes.outputs.continue == 'true' | ||
| run: | | ||
| cd ./cli | ||
| PR_NUMBER=$(gh pr list \ | ||
| --head "${{ env.DESTINATION_BRANCH }}" \ | ||
| --json number \ | ||
| --jq '.[0].number' \ | ||
| --limit 1) | ||
|
|
||
| if [ -n "$PR_NUMBER" ]; then | ||
| echo "PR #$PR_NUMBER already exists. Updating it." | ||
| echo "Pushed changes to existing PR #$PR_NUMBER." | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "No existing PR found. Creating a new one." | ||
| gh pr create \ | ||
| --title="${{ env.COMMIT_MESSAGE }}" \ | ||
| --body="Automatic PR controlled by GitHub Action" \ | ||
| --head "${{ env.DESTINATION_BRANCH }}" \ | ||
| --base ${{ github.ref_name || 'main' }} | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| name: Synchronize README from GitBooks | ||
| on: | ||
| workflow_dispatch: | ||
| schedule: | ||
| - cron: '0 9 * * 1' # Monday at 9 | ||
|
|
||
| env: | ||
| DESTINATION_BRANCH: docs/automatic-gitbook-update-readme | ||
| COMMIT_MESSAGE: 'docs: synchronizing README from snyk/user-docs' | ||
|
|
||
| jobs: | ||
| build: | ||
| name: synchronize-readme | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout user-docs repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: snyk/user-docs | ||
| path: user-docs | ||
| ref: main | ||
|
|
||
| - name: Checkout cli repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: snyk/cli | ||
| path: cli | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Configure git user | ||
| run: | | ||
| git config --global user.email "noreply@snyk.io" | ||
|
|
||
| # GITHUB_ACTOR: The name of the person or app that initiated the workflow. | ||
| git config --global user.name "$GITHUB_ACTOR" | ||
|
|
||
| - name: Create or checkout destination branch | ||
| run: | | ||
| cd cli | ||
| if git show-ref --verify --quiet refs/heads/${{ env.DESTINATION_BRANCH }}; then | ||
| echo "Branch ${{ env.DESTINATION_BRANCH }} already exists, checking out." | ||
| git checkout ${{ env.DESTINATION_BRANCH }} | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "Branch ${{ env.DESTINATION_BRANCH }} does not exist, creating and checking out." | ||
| git checkout -b ${{ env.DESTINATION_BRANCH }} | ||
|
|
||
| - name: Retrieve GitBook content and update README | ||
| run: | | ||
| cp ./docs/snyk-cli/getting-started-with-the-snyk-cli.md ./cli/README.md | ||
|
|
||
|
|
||
| # GitBook Markdown files often use relative paths for assets (e.g., images) | ||
| # like `../.gitbook/assets/image.png`. When this README.md is viewed directly | ||
| # on GitHub, these relative paths won't resolve correctly. This `sed` command | ||
| # replaces those relative paths with the full, absolute URL to the assets | ||
| # hosted in the `snyk/user-docs` GitHub repository's raw content. | ||
| # | ||
| # - `-i`: Edits the file in-place, modifying the original README.md directly. | ||
| # - `-e`: Specifies the script to be executed. In this case, it's the 's' | ||
| # (substitute) command which replaces the old path with the new URL. | ||
| sed -i \ | ||
| -e "s|../.gitbook/assets/|https://github.com/snyk/user-docs/raw/HEAD/docs/.gitbook/assets/|g" \ | ||
| ./cli/README.md | ||
|
|
||
| - name: Format README with Prettier | ||
| run: | | ||
| cd ./cli | ||
| npx prettier --write README.md | ||
|
|
||
| - name: Check for changes | ||
| id: check_changes | ||
| run: | | ||
| cd ./cli | ||
| if [[ -z "$(git status --porcelain)" ]]; then | ||
| echo "No documentation changes detected, exiting." | ||
| echo "continue=false" >> "$GITHUB_OUTPUT" | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "--- Documentation changes detected from GitBooks (before Prettier) ---" | ||
| git --no-pager diff --color=always | ||
| echo "---------------------------------------------------------------------" | ||
|
|
||
| echo "continue=true" >> "$GITHUB_OUTPUT" | ||
|
|
||
| - name: Commit and push changes (if any) | ||
| if: steps.check_changes.outputs.continue == 'true' | ||
| run: | | ||
| cd ./cli | ||
| git add help | ||
| git commit -m "${{ env.COMMIT_MESSAGE }}" | ||
| git push --force --set-upstream origin ${{ env.DESTINATION_BRANCH }} | ||
|
|
||
| - name: Create or update a pull request | ||
| if: steps.check_changes.outputs.continue == 'true' | ||
| run: | | ||
| cd ./cli | ||
| PR_NUMBER=$(gh pr list \ | ||
| --head "${{ env.DESTINATION_BRANCH }}" \ | ||
| --json number \ | ||
| --jq '.[0].number' \ | ||
| --limit 1) | ||
|
|
||
| if [ -n "$PR_NUMBER" ]; then | ||
| echo "PR #$PR_NUMBER already exists. Updating it." | ||
| echo "Pushed changes to existing PR #$PR_NUMBER." | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "No existing PR found. Creating a new one." | ||
| gh pr create \ | ||
| --title="${{ env.COMMIT_MESSAGE }}" \ | ||
| --body="Automatic PR controlled by GitHub Action" \ | ||
| --head "${{ env.DESTINATION_BRANCH }}" \ | ||
| --base main | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,18 @@ | ||
| # CLI Help files | ||
|
|
||
| Snyk CLI Help files are managed by GitBook connected to the [snyk/user-docs](https://github.com/snyk/user-docs) | ||
| repository. | ||
|
|
||
| It's recommended to make all CLI Help changes there, as changes here will be overwritten by the next sync. | ||
|
|
||
| Changes from GitBook are automatically synced to the Snyk CLI repository with GitHub Actions: | ||
|
|
||
| - https://github.com/snyk/snyk/actions/workflows/sync-cli-help-to-user-docs.yml and | ||
| - https://github.com/snyk/snyk/actions/workflows/sync-cli-readme.yml | ||
|
|
||
| The actions create PRs that need to be approved and merged. This action could also be manually triggered. | ||
|
|
||
| If you need to make changes tied to a specific PR, you can make them in this repository first, merge the changes and | ||
| then move them over to the GitBook. | ||
|
|
||
| CLI help files are a standard Markdown. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
☝🏻 This part needs to change when the Gitbook CR has been merged. We are unsure about the file names until that happens.