Integrate Bump.sh with your workflow
How to integrate your documentation deployment to your Continuous Integration (CI) workflow.
Available tools #
There are multiple ways to integrate with Bump.sh:
- Using the Github Action
- Using other CI examples
- Manually using the CLI
- More advanced usage can be done with the API
Steps to integrate in your CI #
We are presenting the process recommended to our users, but feel free to adapt it to your own workflow/requirements.
We advise to setup two steps in your automation flow:
- a validation and diff step during development
- followed by a deployment step on production merges.
API diff & validation of the documentation file #
When suggesting a change to your API, you probably follow a pull request flow (also known as merge request) and make the changes on a development branch. You can integrate Bump.sh at this stage to generate an API diff or only validate your changed API document.
With our Github Action, you can receive automatic API diff comments directly on your GitHub pull requests. With other source code management systems, you can use our CLI within your CI with the bump diff
command to run each time a development branch is created or updated.
This step will fail the build if the documentation file is not valid. You can also ask our tools to fail if a breaking change is detected on your API (Thanks to the fail_on_breaking:
Github Action input parameter or --fail-on-breaking
CLI option).
Deploy your API document #
Once your branch has been merged into your main branch (generally the master
or main
one) you will want to deploy your new documentation file and make it live.
Examples #
Github Action #
The GitHub action example uses a dedicated action we crafted especially for you. You may find more information for both steps described above on our dedicated GitHub Action page.
- Recommended: Deploy Documentation & Diff on Pull Requests
- API diff & validation step
- Deploy to your documentation
Other Continuous Integration tools (CI) #
The CI examples are here to help you build a similar process described with our GitHub action. We try to keep some specially crafted scripts for you to build the same experience for your own tools:
- Example Gitlab CI pipelines.
- Example delivery process with a CircleCI config file.
- Example Travis CI Build Configuration
CLI #
The CLI can be used in your custom CI scripts with the two available recommendeded steps:
bump diff
to check the changes & validate the API documentbump deploy
to publish to your Bump.sh documentation
Recommendation #
Note that if you don’t want to keep the private token and documentation id in your code base, you should use environment variables. Our CLI and Github-Action automatically recognizes these 3 variables:
BUMP_ID
: your documentation public slug or idBUMP_TOKEN
: your documentation private tokenBUMP_HUB_ID
: if using hubs, your hub public slug or id