spring-doc-actions

A set of GitHub actions for Spring documentation.

bust-cloudflare-antora-cache

A GitHub action that busts the Cloudflare Cache for Spring based Antora docs.

inputs:
  context-root:
    description: The context root of the documentation (e.g. for https://docs.spring.io/spring-security/reference/ context-root is spring-security)
    required: true
  cloudflare-zone-id:
    description: The cloudflare zone id
    required: true
  cloudflare-cache-token:
    description: The cloudflare cache token
    required: true

Example usage:

github/workflows/deploy-docs.yml

    - name: Bust Clouflare Cache
      uses: spring-io/spring-doc-actions/[email protected]
      with:
        context-root: spring-security
        cloudflare-zone-id: ${{ secrets.CLOUDFLARE_ZONE_ID }}
        cloudflare-cache-token: ${{ secrets.CLOUDFLARE_CACHE_TOKEN }}

rsync-antora-reference

A GitHub action that syncs Antora reference documentation using rsync with support for syncing a single version. It deploys to the docs server using the GitHub repository in the path.

inputs:
  docs-username:
    description: The username to connect to the docs server
    required: true
  docs-host:
    description: The host of the docs server
    required: true
  docs-ssh-key:
    description: The ssh key used to connect to the docs-host
    required: true
  docs-ssh-host-key:
    description: The docs ssh host key used to connect to docs-host
    required: true
  dry-run:
    description: Set to false if should perform the sync, else a dry run is performed
    default: false
    required: false
  site-path:
    description: The path to the site that should be synced
    default: build/site
    required: false
  httpdocs-path:
    description: |
      The optional base httpdocs path (e.g. https://docs.spring.io/spring-security/reference would be /spring-security/reference)
      If this is set, then the project must own the directory by ensuring to have a .github-repository file with the
      <OWNER>/<REPOSITORY_NAME> as the content. The default is to use /\${REPOSITORY_NAME}/reference
      from `github.repository`
    required: false

Example usage:

github/workflows/deploy-docs.yml

    - name: Publish Docs
      uses: spring-io/spring-doc-actions/[email protected]
      with:
        docs-username: ${{ secrets.DOCS_USERNAME }}
        docs-host: ${{ secrets.DOCS_HOST }}
        docs-ssh-key: ${{ secrets.DOCS_SSH_KEY }}
        docs-ssh-host-key: ${{ secrets.DOCS_SSH_HOST_KEY }}
        dry-run: true

update-antora-ui-spring

A GitHub Action that detects if there is a new version of the Antora UI Spring artifact and creates a PR to update it.

inputs:
  docs-branch:
    description: The branch where the file containing the Antora UI Spring artifact is. Default is 'docs-build'
    default: 'docs-build'
  workflow-branch-suffix:
    description: The suffix for the branch that will be created by the workflow with the changes, resolves to ${docs-branch}_${workflow-branch-suffix}. Default is update-antora-ui-spring
    default: 'update-antora-ui-spring'
  antora-file-path:
    description: Path to the Antora file containing the Antora UI Spring artifact. Default is 'antora-playbook.yml'.
    default: 'antora-playbook.yml'
  token:
    description: Token with write permission to pull-requests, issues and contents
    required: true

Example usage:

github/workflows/update-antora-ui-spring.yml

permissions:
  pull-requests: write
  issues: write
  contents: write

jobs:
  update-antora-ui-spring:
    runs-on: ubuntu-latest
    name: Update on Supported Branches
    strategy:
      matrix:
        branch: [ '5.8.x', '6.1.x', '6.2.x', 'main' ]
    steps:
      - uses: spring-io/spring-doc-actions/[email protected]
        name: Update
        with:
          docs-branch: ${{ matrix.branch }}
          token: ${{ secrets.GITHUB_TOKEN }}
          antora-file-path: 'docs/antora-playbook.yml'
  update-antora-ui-spring-docs-build:
    runs-on: ubuntu-latest
    name: Update on docs-build
    steps:
      - uses: spring-io/spring-doc-actions/[email protected]
        name: Update
        with:
          docs-branch: 'docs-build'
          token: ${{ secrets.GITHUB_TOKEN }}

The PR will only be created if there is no open PR for the same branch, even if there is a newer version of Antora UI Spring. For example, if there is an open PR to update from version v0.4.11 to v0.4.12 and v0.4.13 is released, the workflow won’t open a new PR for v0.4.13 if the previous one is not closed.