Skip to main content

GitHub Action

Generate your API documentation & changelog​

Bump is a Continuous Documentation Platform: it lets you keep your API doc always synchronized with your codebase. With this Github Action you can automatically generate your API reference (with changelog and diff) on Bump from any OpenAPI or AsyncAPI file.

Usage​

Start by creating a documentation on Bump. Then add one of the following workflow file to your GitHub project.

info

In all the examples below, make sure to change the branch name main_with the name of your repository main destination branch, replace <BUMP_DOC_ID> with your Bump documentation slug or id and change the filepathdoc/api-documentation.yml_with your api specification file path.

caution

actions/checkout has to be called before our action.

Deploy on git push​

If you only need to deploy the documentation on push you can use this workflow file:

.github/workflows/bump-deploy.yml

name: Deploy documentation

on:
  push:
    branches:
      - main

jobs:
  deploy-doc:
    name: Deploy API doc on Bump
    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 on pull requests​

If you only want to have API diff summary sent as a comment on your pull requests:

.github/workflows/bump-diff.yml

name: API diff

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read
  pull-requests: write

jobs:
  api-diff:
    name: Check API diff on Bump
    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}}

API diff on pull requests & Deploy on push​

This is the most common workflow that we recommend, 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
    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
    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}}
info

Since February 2nd, 2023, the default GITHUB_TOKEN permissions are set to read-only for every new repository.

Permissions have to be explicitly defined in your workflows, as illustrated above.

Input parameters​

  • doc (required): Documentation slug (or id). Can be found in the documentation settings on https://bump.sh/docs

  • token (required): Do not add your documentation token here, but create an encrypted secret that holds your documentation token.

    • Your Bump token can be found in the documentation settings on https://bump.sh. Copy it for later usage.
    • In your GitHub repository, click Settings, and then Secrets.
    • Click the button “New repository secret”, name the secret BUMP_TOKEN and paste your Bump token in the value field.

  • file: Relative path to the documentation file. Default: api-contract.yml.

  • command: Bump command to execute. Default: __deploy

    • deploy deploy a new version of the documentation
    • diff: automatically comment your pull request with the API diff
    • dry-run: validate the documentation file before a deployment
    • preview: create a temporary preview

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 github-action project codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.