DOC-1409 Add CI/CD pipeline for deploying and previewing API docs #2
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 |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * @redpanda-data/documentation |
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,220 @@ | ||
| name: Check and deploy API documentation | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - main | ||
|
|
||
| pull_request: | ||
| branches: | ||
| - main | ||
|
|
||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
|
|
||
| jobs: | ||
| determine-doc-ids: | ||
| runs-on: ubuntu-latest | ||
| outputs: | ||
| matrix: ${{ steps.set-matrix.outputs.matrix }} | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: Get changed files | ||
| id: changed-files | ||
| run: | | ||
| if [[ "${{ github.event_name }}" == "pull_request" ]]; then | ||
| CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}) | ||
| else | ||
| CHANGED_FILES=$(git diff --name-only ${{ github.event.before }} ${{ github.event.after }}) | ||
| fi | ||
| echo "CHANGED_FILES<<EOF" >> $GITHUB_ENV | ||
| echo "$CHANGED_FILES" >> $GITHUB_ENV | ||
| echo "EOF" >> $GITHUB_ENV | ||
|
|
||
| - name: Set matrix | ||
| id: set-matrix | ||
| run: | | ||
| DOCS=() | ||
|
|
||
| # Check for changes in API doc folders | ||
| if echo "$CHANGED_FILES" | grep -q "^admin/"; then | ||
| DOCS+=("admin") | ||
| fi | ||
| if echo "$CHANGED_FILES" | grep -q "^cloud-controlplane/"; then | ||
| DOCS+=("cloud-controlplane") | ||
| fi | ||
| if echo "$CHANGED_FILES" | grep -q "^cloud-dataplane/"; then | ||
| DOCS+=("cloud-dataplane") | ||
| fi | ||
| if echo "$CHANGED_FILES" | grep -q "^schema-registry/"; then | ||
| DOCS+=("schema-registry") | ||
| fi | ||
| if echo "$CHANGED_FILES" | grep -q "^http-proxy/"; then | ||
| DOCS+=("http-proxy") | ||
| fi | ||
| # Check for changes in shared resources that might affect all docs | ||
| if echo "$CHANGED_FILES" | grep -q "^shared/"; then | ||
| if [ ${#DOCS[@]} -eq 0 ]; then | ||
| # If only shared files changed and no specific doc files, include all docs | ||
| DOCS+=("admin" "cloud-controlplane" "cloud-dataplane" "schema-registry" "http-proxy") | ||
| fi | ||
| fi | ||
|
|
||
| # If no files changed in any monitored directories, abort the workflow | ||
| if [ ${#DOCS[@]} -eq 0 ]; then | ||
| echo "No relevant files were changed. Exiting workflow." | ||
| echo "matrix={\"doc_id\":[]}" >> $GITHUB_OUTPUT | ||
| exit 0 | ||
| fi | ||
|
|
||
| # Convert bash array to JSON array for GitHub Actions matrix | ||
| JSON_ARRAY=$(printf '"%s",' "${DOCS[@]}" | sed 's/,$//') | ||
| JSON_MATRIX="{\"doc_id\":[$JSON_ARRAY]}" | ||
| echo "matrix=$JSON_MATRIX" >> $GITHUB_OUTPUT | ||
| echo "Created matrix: $JSON_MATRIX" | ||
|
|
||
| deploy-doc: | ||
| if: ${{ github.event_name == 'push' && fromJson(needs.determine-doc-ids.outputs.matrix).doc_id[0] != null }} | ||
| needs: determine-doc-ids | ||
| name: Deploy API documentation on Bump.sh | ||
| runs-on: ubuntu-latest | ||
| strategy: | ||
| matrix: ${{fromJson(needs.determine-doc-ids.outputs.matrix)}} | ||
| fail-fast: false | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Determine file format | ||
| id: format | ||
| run: | | ||
| if [ -f "${{ matrix.doc_id }}/${{ matrix.doc_id }}.yaml" ]; then | ||
| echo "file_path=${{ matrix.doc_id }}/${{ matrix.doc_id }}.yaml" >> $GITHUB_OUTPUT | ||
| elif [ -f "${{ matrix.doc_id }}/${{ matrix.doc_id }}.json" ]; then | ||
| echo "file_path=${{ matrix.doc_id }}/${{ matrix.doc_id }}.json" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "No API definition file found for ${{ matrix.doc_id }}" | ||
| exit 1 | ||
| fi | ||
|
|
||
| - name: Determine overlays | ||
| id: overlays | ||
| run: | | ||
| OVERLAYS="" | ||
|
|
||
| # Function to add overlay path with comma if needed | ||
| add_overlay() { | ||
| local overlay_path="$1" | ||
| if [ -f "$overlay_path" ]; then | ||
| if [ -n "$OVERLAYS" ]; then | ||
| OVERLAYS="$OVERLAYS,$overlay_path" | ||
| else | ||
| OVERLAYS="$overlay_path" | ||
| fi | ||
| fi | ||
| } | ||
|
|
||
| # Check for doc-specific overlays (list each overlay file individually) | ||
| if [ -d "${{ matrix.doc_id }}/overlays" ]; then | ||
| find "${{ matrix.doc_id }}/overlays" -name "*.yaml" -type f | sort | while read overlay_file; do | ||
| add_overlay "$overlay_file" | ||
| done | ||
| fi | ||
|
|
||
| # Check for shared overlays - only apply to cloud APIs | ||
| if [[ "${{ matrix.doc_id }}" == "cloud-"* ]] && [ -d "shared/overlays" ]; then | ||
| find "shared/overlays" -name "*.yaml" -type f | sort | while read overlay_file; do | ||
| add_overlay "$overlay_file" | ||
| done | ||
| fi | ||
|
|
||
| echo "overlay_paths=$OVERLAYS" >> $GITHUB_OUTPUT | ||
| echo "Using overlays: $OVERLAYS" | ||
|
|
||
| - name: Deploy API documentation | ||
| uses: bump-sh/github-action@v1 | ||
| with: | ||
| hub: redpanda | ||
| doc: ${{ matrix.doc_id }} | ||
| token: ${{secrets.BUMP_TOKEN}} | ||
| file: ${{ steps.format.outputs.file_path }} | ||
| overlay: ${{ steps.overlays.outputs.overlay_paths }} | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
|
|
||
| api-diff: | ||
| if: ${{ github.event_name == 'pull_request' && fromJson(needs.determine-doc-ids.outputs.matrix).doc_id[0] != null }} | ||
| needs: determine-doc-ids | ||
| name: Check API diff on Bump.sh | ||
| runs-on: ubuntu-latest | ||
| strategy: | ||
| matrix: ${{fromJson(needs.determine-doc-ids.outputs.matrix)}} | ||
| fail-fast: false | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Determine file format | ||
| id: format | ||
| run: | | ||
| if [ -f "${{ matrix.doc_id }}/${{ matrix.doc_id }}.yaml" ]; then | ||
| echo "file_path=${{ matrix.doc_id }}/${{ matrix.doc_id }}.yaml" >> $GITHUB_OUTPUT | ||
| elif [ -f "${{ matrix.doc_id }}/${{ matrix.doc_id }}.json" ]; then | ||
| echo "file_path=${{ matrix.doc_id }}/${{ matrix.doc_id }}.json" >> $GITHUB_OUTPUT | ||
| elif [ -f "${{ matrix.doc_id }}/${{ matrix.doc_id }}-api.json" ]; then | ||
| echo "file_path=${{ matrix.doc_id }}/${{ matrix.doc_id }}-api.json" >> $GITHUB_OUTPUT | ||
| else | ||
| echo "No API definition file found for ${{ matrix.doc_id }}" | ||
| exit 1 | ||
| fi | ||
|
|
||
| - name: Determine overlays | ||
| id: overlays | ||
| run: | | ||
| OVERLAYS="" | ||
|
|
||
| # Function to add overlay path with comma if needed | ||
| add_overlay() { | ||
| local overlay_path="$1" | ||
| if [ -f "$overlay_path" ]; then | ||
| if [ -n "$OVERLAYS" ]; then | ||
| OVERLAYS="$OVERLAYS,$overlay_path" | ||
| else | ||
| OVERLAYS="$overlay_path" | ||
| fi | ||
| fi | ||
| } | ||
|
|
||
| # Check for doc-specific overlays (list each overlay file individually) | ||
| if [ -d "${{ matrix.doc_id }}/overlays" ]; then | ||
| find "${{ matrix.doc_id }}/overlays" -name "*.yaml" -type f | sort | while read overlay_file; do | ||
| add_overlay "$overlay_file" | ||
| done | ||
| fi | ||
|
|
||
| # Check for shared overlays - only apply to cloud APIs | ||
| if [[ "${{ matrix.doc_id }}" == "cloud-"* ]] && [ -d "shared/overlays" ]; then | ||
| find "shared/overlays" -name "*.yaml" -type f | sort | while read overlay_file; do | ||
| add_overlay "$overlay_file" | ||
| done | ||
| fi | ||
|
|
||
| echo "overlay_paths=$OVERLAYS" >> $GITHUB_OUTPUT | ||
| echo "Using overlays: $OVERLAYS" | ||
|
|
||
| - name: Comment pull request with API diff | ||
| uses: bump-sh/github-action@v1 | ||
| with: | ||
| hub: redpanda | ||
| doc: ${{ matrix.doc_id }} | ||
| token: ${{secrets.BUMP_TOKEN}} | ||
| file: ${{ steps.format.outputs.file_path }} | ||
| overlay: ${{ steps.overlays.outputs.overlay_paths }} | ||
| command: diff | ||
|
There was a problem hiding this comment. I'm curious about the diff comment that was added to the PR. I don't see changes to the API definitions (just the filenames if I'm understanding correctly) in the PR but it's identified a few changes to properties. Is this expected? There was a problem hiding this comment. It's diffing the content in this PR against what is currently uploaded on Bump. There was a problem hiding this comment. I assume since we did the PoC, the spec changed and this repo now contains some changes. |
||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
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.
Would it still be all right if the files in
shared/don't necessarily affect all docs? Right now the files in that directory really only apply to the Cloud APIs.