{"id":14986692,"url":"https://github.com/bump-sh/github-action","last_synced_at":"2025-07-29T15:34:47.543Z","repository":{"id":36968352,"uuid":"239773663","full_name":"bump-sh/github-action","owner":"bump-sh","description":"GitHub action to deploy your API documentation on Bump","archived":false,"fork":false,"pushed_at":"2025-07-17T10:41:31.000Z","size":12261,"stargazers_count":43,"open_issues_count":8,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-17T13:54:06.916Z","etag":null,"topics":["api-documentation","asyncapi","asyncapi-specification","github-actions","openapi","openapi-specification"],"latest_commit_sha":null,"homepage":"https://bump.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bump-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-11T13:52:15.000Z","updated_at":"2025-07-17T10:41:34.000Z","dependencies_parsed_at":"2024-02-02T10:42:46.406Z","dependency_job_id":"39058cfd-1a87-400a-9931-5e0b553f2cd0","html_url":"https://github.com/bump-sh/github-action","commit_stats":{"total_commits":262,"total_committers":12,"mean_commits":"21.833333333333332","dds":"0.38167938931297707","last_synced_commit":"205cb29bab5ba763b996918f5f010d480ac6e392"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/bump-sh/github-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fgithub-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fgithub-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fgithub-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fgithub-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bump-sh","download_url":"https://codeload.github.com/bump-sh/github-action/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fgithub-action/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267709527,"owners_count":24131904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","asyncapi","asyncapi-specification","github-actions","openapi","openapi-specification"],"created_at":"2024-09-24T14:13:21.880Z","updated_at":"2025-07-29T15:34:47.526Z","avatar_url":"https://github.com/bump-sh.png","language":"TypeScript","readme":"# Deploy API documentation at each code commit, and review diffs\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"20%\" src=\"https://bump.sh/icon-default-maskable-large.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.bump.sh/help/\"\u003eHelp\u003c/a\u003e |\n  \u003ca href=\"https://bump.sh/users/sign_up\"\u003eSign up\u003c/a\u003e\n\u003c/p\u003e\n\nBump.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.\n\nBump.sh keeps your API docs always synchronized with your codebase. With this [Github Action](https://github.com/actions) your API reference is automatically generated - with changelog and diff - on [Bump.sh](https://bump.sh) from any [OpenAPI](https://github.com/OAI/OpenAPI-Specification) or [AsyncAPI](https://github.com/asyncapi/asyncapi) file.\n\n## Table of contents\n\n* [Usage](#usage)\n* [Inputs](#inputs)\n* [Contributing](#contributing)\n* [License](#license)\n* [Code Of Conduct](#code-of-conduct)\n\n## Usage\n\nStart with creating a documentation on [Bump.sh](https://bump.sh).\n\nOnce you've got an API Documentation set up, go to Settings \u003e CI Deployment, copy the access token, then add it to GitHub Settings \u003e Secrets \u003e Actions as a new environment variable called `BUMP_TOKEN`.\n\nThen you can pick from one of the three following API workflow files.\n\n- **Recommended:** [Deploy documentation \u0026 diff on pull requests](#deploy-documentation--diff-on-pull-requests)\n- [Deploy documentation only](#deploy-documentation-only)\n- [Diff on pull requests only](#diff-on-pull-requests-only)\n\n### Deploy documentation \u0026 diff on pull requests\n\nThis is the most common worklow that we [recommend using](https://docs.bump.sh/help/continuous-integration/), which will create two steps in your automation flow: a validation \u0026 diff step on code reviews, followed by a deployment step on merged changes.\n\n`.github/workflows/bump.yml`\n\n```yaml\nname: Check \u0026 deploy API documentation\n\non:\n  push:\n    branches:\n      - main\n\n  pull_request:\n    branches:\n      - main\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  deploy-doc:\n    if: ${{ github.event_name == 'push' }}\n    name: Deploy API documentation on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Deploy API documentation\n        uses: bump-sh/github-action@v1\n        with:\n          doc: \u003cBUMP_DOC_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: doc/api-documentation.yml\n\n  api-diff:\n    if: ${{ github.event_name == 'pull_request' }}\n    name: Check API diff on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Comment pull request with API diff\n        uses: bump-sh/github-action@v1\n        with:\n          doc: \u003cBUMP_DOC_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: doc/api-documentation.yml\n          command: diff\n        env:\n          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}\n```\n\n**Important:** make sure you adapt the name of the branch your deployment will target, _aka_ your destination branch if relevant (`main` in the example above), replace `\u003cBUMP_DOC_ID\u003e` with your Bump.sh documentation slug or id, and point `file:` to your local API definition file (`doc/api-documentation.yml`).\n\n### Deploy documentation only\n\nIf you only need to deploy documentation changes on push then you can use this workflow instead:\n\n`.github/workflows/bump.yml`\n\n```yaml\nname: Deploy documentation\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy-doc:\n    name: Deploy API doc on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Deploy API documentation\n        uses: bump-sh/github-action@v1\n        with:\n          doc: \u003cBUMP_DOC_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: doc/api-documentation.yml\n```\n\n**Important:** make sure you adapt the name of the branch your deployment will target, _aka_ your destination branch if relevant (`main` in the example above), replace `\u003cBUMP_DOC_ID\u003e` with your Bump.sh documentation slug or id, and point `file:` to your local API definition file (`doc/api-documentation.yml`).\n\n### Diff on pull requests only\n\nIf you only want to have API diff posted on pull requests use this workflow:\n\n`.github/workflows/bump.yml`\n\n```yaml\nname: API diff\n\npermissions:\n  contents: read\n  pull-requests: write\n\non:\n  pull_request:\n    branches:\n      - main\n\njobs:\n  api-diff:\n    name: Check API diff on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n      - name: Comment pull request with API diff\n        uses: bump-sh/github-action@v1\n        with:\n          doc: \u003cBUMP_DOC_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: doc/api-documentation.yml\n          command: diff\n        env:\n          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}\n```\n\n**Important:** make sure you adapt the name of the branch your deployment will target, _aka_ your destination branch if relevant (`main` in the example above), replace `\u003cBUMP_DOC_ID\u003e` with your Bump.sh documentation slug or id, and point `file:` to your local API definition file (`doc/api-documentation.yml`).\n\n### Deploy a single documentation on a hub\n\nYou can deploy a documentation inside a hub by adding a `hub` slug or id. \nNote that the documentation will be automatically created if it doesn't exist by using the slug you defined with the `doc:` input.\n\n`.github/workflows/bump.yml`\n\n```yaml\nname: Deploy documentation\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy-doc:\n    name: Deploy API doc on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Deploy API documentation\n        uses: bump-sh/github-action@v1\n        with:\n          doc: \u003cBUMP_DOC_ID\u003e\n          hub: \u003cBUMP_HUB_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: doc/api-documentation.yml\n```\n\n**Important:** make sure you adapt the name of the branch your deployment will target, _aka_ your destination branch if relevant (`main` in the example above), replace `\u003cBUMP_DOC_ID\u003e` with your Bump.sh documentation slug or id, `\u003cBUMP_HUB_ID\u003e` with your Bump.sh hub slug or id and point `file:` to your local API definition file (`doc/api-documentation.yml`).\n\n### Deploy multiple documentation at once on a hub\n\nYou can deploy multiple documentation inside a hub from a **source directory** by adding a `hub` slug or id and specifying a directory name in the `file:` input. Note that documentation will be automatically created if they don't exist.\n\n`.github/workflows/bump.yml`\n\n```yaml\nname: Deploy documentation\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy-doc:\n    name: Deploy API doc on Bump.sh\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Deploy API documentation\n        uses: bump-sh/github-action@v1\n        with:\n          hub: \u003cBUMP_HUB_ID\u003e\n          token: ${{secrets.BUMP_TOKEN}}\n          file: docs/\n```\n\n**Important:** make sure you adapt the name of the branch your deployment will target, _aka_ your destination branch if relevant (`main` in the example above), replace `\u003cBUMP_HUB_ID\u003e` with your Bump.sh hub slug or id and point `file:` to your local API definition file folder (`docs/`).\n\n\n## Inputs\n\n* `doc` (required unless you deploy a directory on a hub): Documentation slug or id. Can be found in the documentation settings on https://bump.sh/dashboard\n\n* `token` (required): Do not add your documentation token here, but create an [encrypted secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets) that holds your documentation token.\n\n  * Your Bump.sh token can be found in the documentation settings on [your API dashboard](https://bump.sh/dashboard). Copy it for later usage.\n  * In your GitHub repository, go to your “Settings”, and then “Secrets”.\n  * Click the button “New repository secret”, name the secret `BUMP_TOKEN` and paste your Bump.sh token in the value field.\n\n* `file`: Relative path to the API definition file or the API definition file folder. _Default: `api-contract.yml`_\n\n* `hub` (optional): Hub slug or id. Needed when deploying documentation in a Hub. Can be found in the hub settings on https://bump.sh/dashboard\n\n* `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.\n\n* `overlay` (optional): Path or URL of overlay file(s) to apply before running the `deploy` command. Follows the OpenAPI Overlay specification, and accepts multiple overlays separated by comma.\n\n* `command`: Bump.sh command to execute. _Default: `deploy`_\n\n  * `deploy`: deploy a new version of the documentation\n  * `diff`: automatically comment your pull request with the API diff\n  * `dry-run`: dry-run a deployment of the documentation file\n  * `preview`: create a temporary preview\n\n* `expires` (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.\n\n* `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.\n\n## Contributing\n\nBug 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](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe scripts and documentation in this project are released under the [MIT License](LICENSE).\n\n## Code of Conduct\n\nEveryone interacting in the Bump `github-action` project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bump-sh/github-action/blob/master/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbump-sh%2Fgithub-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbump-sh%2Fgithub-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbump-sh%2Fgithub-action/lists"}