GitHub Action
Steps to add a Bump GitHub Action
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.
Start by creating a documentation on Bump. Then add one of the following workflow file to your GitHub project.
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.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/[email protected]
- name: Deploy API documentation
uses: bump-sh/github-[email protected]
with:
doc: <BUMP_DOC_ID>
token: ${{secrets.BUMP_TOKEN}}
file: doc/api-documentation.yml
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
jobs:
api-diff:
name: Check API diff on Bump
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/[email protected]
- name: Comment pull request with API diff
uses: bump-sh/github-[email protected]
with:
doc: <BUMP_DOC_ID>
token: ${{secrets.BUMP_TOKEN}}
file: doc/api-documentation.yml
command: diff
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
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
jobs:
deploy-doc:
if: ${{ github.event_name == 'push' }}
name: Deploy API documentation on Bump
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/[email protected]
- name: Deploy API documentation
uses: bump-sh/github-[email protected]
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/[email protected]
- name: Comment pull request with API diff
uses: bump-sh/github-[email protected]
with:
doc: <BUMP_DOC_ID>
token: ${{secrets.BUMP_TOKEN}}
file: doc/api-documentation.yml
command: diff
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
doc
(required): Documentation slug (or id). Can be found in the documentation settings on https://bump.sh/docstoken
(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 documentationdiff
: automatically comment your pull request with the API diffdry-run
: validate the documentation file before a deploymentpreview
: create a temporary preview
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.
Everyone interacting in the Bump
github-action
project codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.Last modified 1yr ago