GitHub action to deploy your API documentation on Bump
MIT License
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.
Start with creating a documentation on Bump.sh.
Once you've got an API Documentation set up, go to Settings > CI Deployment, copy the access token, then add it to GitHub Settings > Secrets > Actions as a new environment variable called BUMP_TOKEN
.
Then you can pick from one of the three following API workflow files.
This is the most common worklow that we recommend using, 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}}
Important: 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
).
If you only need to deploy documentation changes on push then you can use this workflow instead:
.github/workflows/bump.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
Important: 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
).
If you only want to have API diff posted on pull requests use this workflow:
.github/workflows/bump.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}}
Important: 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
).
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.
BUMP_TOKEN
and paste your Bump.sh token in the value field.file
: Relative path to the documentation file. Default: api-contract.yml
hub
(optional): Hub slug or id. Needed when deploying to a documentation attached to a Hub. Can be found in the hub settings on https://bump.sh
branch
(optional): Branch name used during deploy
or diff
commands. This can be useful to maintain multiple API reference history and make it available in your API documentation.
command
: Bump.sh command to execute. Default: deploy
deploy
: deploy a new version of the documentationdiff
: automatically comment your pull request with the API diffdry-run
: dry-run a deployment of the documentation filepreview
: create a temporary previewexpires
(optional): Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use never
to keep the result live indefinitely.
fail_on_breaking
(optional): Mark the action as failed when a breaking change is detected with the diff command. This is only valid with diff
command.
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.
The scripts and documentation in this project are released under the MIT License.
Everyone interacting in the Bump github-action
project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.