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.
In all the examples below, make sure to change the branch name mainwith 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.ymlwith your api specification file path.
​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
1
name: Deploy documentation
2
​
3
on:
4
  push:
5
    branches:
6
      - main
7
​
8
jobs:
9
  deploy-doc:
10
    name: Deploy API doc on Bump
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Checkout
14
        uses: actions/[email protected]
15
      - name: Deploy API documentation
16
        uses: bump-sh/github-[email protected]
17
        with:
18
          doc: <BUMP_DOC_ID>
19
          token: ${{secrets.BUMP_TOKEN}}
20
          file: doc/api-documentation.yml
Copied!
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
1
name: API diff
2
​
3
on:
4
  pull_request:
5
    branches:
6
      - main
7
​
8
jobs:
9
  api-diff:
10
    name: Check API diff on Bump
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Checkout
14
        uses: actions/[email protected]
15
      - name: Comment pull request with API diff
16
        uses: bump-sh/github-[email protected]
17
        with:
18
          doc: <BUMP_DOC_ID>
19
          token: ${{secrets.BUMP_TOKEN}}
20
          file: doc/api-documentation.yml
21
          command: diff
22
        env:
23
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
Copied!
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
1
name: Check & deploy API documentation
2
​
3
on:
4
  push:
5
    branches:
6
      - main
7
​
8
  pull_request:
9
    branches:
10
      - main
11
​
12
jobs:
13
  deploy-doc:
14
    if: ${{ github.event_name == 'push' }}
15
    name: Deploy API documentation on Bump
16
    runs-on: ubuntu-latest
17
    steps:
18
      - name: Checkout
19
        uses: actions/[email protected]
20
      - name: Deploy API documentation
21
        uses: bump-sh/github-[email protected]
22
        with:
23
          doc: <BUMP_DOC_ID>
24
          token: ${{secrets.BUMP_TOKEN}}
25
          file: doc/api-documentation.yml
26
​
27
  api-diff:
28
    if: ${{ github.event_name == 'pull_request' }}
29
    name: Check API diff on Bump
30
    runs-on: ubuntu-latest
31
    steps:
32
      - name: Checkout
33
        uses: actions/[email protected]
34
      - name: Comment pull request with API diff
35
        uses: bump-sh/github-[email protected]
36
        with:
37
          doc: <BUMP_DOC_ID>
38
          token: ${{secrets.BUMP_TOKEN}}
39
          file: doc/api-documentation.yml
40
          command: diff
41
        env:
42
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
Copied!
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.
Continuous integration
OpenAPI support
Last modified 7mo ago
Copy link
Contents
Generate your API documentation & changelog