GitHub Action

Generate your API documentation & changelog #

Bump.sh helps you build a branded single source of truth, cataloging all your APIs. We’ve created the reference point for teams consuming and building APIs, no matter which technology they rely on.

Bump.sh keeps your API docs always synchronized with your codebase. With this Github Action your API reference is automatically generated - with changelog and diff - on Bump.sh from any OpenAPI or AsyncAPI file.

Usage #

Start with creating a documentation on Bump.sh.

Once you’ve set up an API Documentation, go to Settings > CI Deployment, copy the access token, then add it to GitHub Settings > Secrets > Actions as a new repository secret called BUMP_TOKEN.

Then you can pick from one of the three following API workflow files.

Deploy Documentation & Diff on Pull Requests #

This is the recommend workflow, which will create two steps in your automation flow: a validation & diff step on code reviews, followed by a deployment step on merged changes.

.github/workflows/bump.yml

name: Check & deploy API documentation

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - main

permissions:
  contents: read
  pull-requests: write

jobs:
  deploy-doc:
    if: ${{ github.event_name == 'push' }}
    name: Deploy API documentation on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Deploy API documentation
        uses: bump-sh/github-action@v1
        with:
          doc: <BUMP_DOC_ID>
          token: ${{secrets.BUMP_TOKEN}}
          file: doc/api-documentation.yml

  api-diff:
    if: ${{ github.event_name == 'pull_request' }}
    name: Check API diff on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Comment pull request with API diff
        uses: bump-sh/github-action@v1
        with:
          doc: <BUMP_DOC_ID>
          token: ${{secrets.BUMP_TOKEN}}
          file: doc/api-documentation.yml
          command: diff
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

make sure to change your destination branch name (main in the example above), replace <BUMP_DOC_ID> with your Bump.sh documentation slug or id, and point file: to your local API description document (doc/api-documentation.yml).

Deploy Documentation only #

If you only need to deploy documentation changes on push, then you can use this workflow instead:

.github/workflows/bump-deploy.yml

name: Deploy documentation

on:
  push:
    branches:
      - main

jobs:
  deploy-doc:
    name: Deploy API doc on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Deploy API documentation
        uses: bump-sh/github-action@v1
        with:
          doc: <BUMP_DOC_ID>
          token: ${{secrets.BUMP_TOKEN}}
          file: doc/api-documentation.yml

make sure to change your destination branch name (main in the example above), replace <BUMP_DOC_ID> with your Bump.sh documentation slug or id, and point file: to your local API description document (doc/api-documentation.yml).

Diff on pull requests only #

If you only want to have API diff posted on pull requests, use this workflow:

.github/workflows/api-diff.yml

name: API diff

permissions:
  contents: read
  pull-requests: write

on:
  pull_request:
    branches:
      - main

jobs:
  api-diff:
    name: Check API diff on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Comment pull request with API diff
        uses: bump-sh/github-action@v1
        with:
          doc: <BUMP_DOC_ID>
          token: ${{secrets.BUMP_TOKEN}}
          file: doc/api-documentation.yml
          command: diff
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

make sure to change your destination branch name (main in the example above), replace <BUMP_DOC_ID> with your Bump.sh documentation slug or id, and point file: to your local API description document (doc/api-documentation.yml).

Inputs #

Contributing #

Bug reports and pull requests are welcome on GitHub at https://github.com/bump-sh/github-action. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License #

The scripts and documentation in this project are released under the MIT License.

Code of Conduct #

Everyone interacting in the Bump.sh github-action project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.