Skip to main content

Swimm's GitHub App

info

Swimm's GitHub App is the most convenient solution for GitHub.com repositories. If your repository is on GitHub Enterprise or another Git provider, please check out Swimm's CLI.

If you're using GitHub.com, Swimm’s GitHub App will help you streamline PRs to verify that your documentation is up to date.

To get the Swimm GitHub App, you first need to sign up for Swimm. You should use Swimm’s Web App to create documentation and configure the setting for our GitHub App.

Getting the GitHub App

Once you are set up with your workspace and have connected a repository, go to GitHub and install the app on your repository.

Swimm's GitHub App features​

Accepting Auto-synced changes from GitHub​

Swimm’s patented Auto-sync algorithm analyzes what happens in your codebase. When Swimm Verify check recognizes Auto-sync documentation changes, you’ll be notified via a comment on your pull request.

In case some changes to the relevant files are marked as "Auto-synced" by the algorithm (that is, no human interaction is required), you can ask the GitHub App to trigger a commit that accepts Auto-sync's suggestions. To do so, click the “Approve Auto-sync” button in the Check, which accepts all Auto-synced docs from the GitHub App.

Automatic Auto-sync approval​

Set up automatic Auto-sync approval in the GitHub App settings to automatically accept Auto-sync changes and commit them to your open pull request in a dedicated commit.

Go to GitHub App Settings and check the “Configure automatic Auto-sync Approval” box.

New doc notifications​

Set an alert on Slack or via email whenever a new document is created and merged to your main branch. This helps keep track of new documentation in your repo and allows you to invite other members of your organization to read and learn more about new documentation. We’ve found that this encourages a better overall understanding of the codebase.

Go to GitHub App Settings and add the requested email under "Email me when new docs are created".


Draft documents from pull requests​

When a pull request is interesting enough to document, Swimm’s GitHub App analyzes code changes and notifies you with a comment to create documentation.

To create a doc, click the Review draft in app button in our comment and go to Swimm’s Web App. All the code changes from your PR will be added to a document and then you’ll just need to explain the code.



Doc recommendations​

Swimm’s GitHub App alerts you to relevant docs on PRs, recommending documentation to review when code changes.

Swimm Verify Check on PR changes only​

Swimm’s GitHub App has the option to run Swimm Verify only on files that are changed in this specific PR.

  • When this option is disabled (this is the default setting), Swimm will show updates related to any outdated/out-of-sync docs.

  • When the setting under Configure Swimm Verify check is enabled from the GitHub App setting, it will notify you only when the changes in your PR have impacted Swimm docs.


When there are issues on your main branch, consider turning this option on until they are resolved. This feature will allow other engineers to avoid unnecessary delays while you can fix the broken document.

Disabling comments​

Swimm’s GitHub App has an option to disable comments to reduce the number of notifications that you’re sent.

If you don’t want to see Swimm Recommended Doc comments, you can disable it in the settings. And if you’d prefer not to get updates on your PRs when your documentation is outdated, you can set that preference in the settings as well.


Integrations with other tools​

Swimm is partnered with Atlassian Compass. Use Swimm’s Compass Integration to link Swimm documentation to the Compass component and see the latest documentation status for all your distributed services from a single place.

Additional integrations are on the way.

Permissions needed for Swimm’s GitHub App​

Swimm requests the following permissions for our GitHub App

Checks

  • We ask for read and write permissions to allow Swimm’s GitHub App to add the Swimm Verify check and update the check results once they are ready.

Content (from repos, commits, branches, downloads, releases, and merges)

  • Read permission to enable Swimm to verify your documentation is up to date as the code changes.

  • Write permission to allow Swimm to accept and commit suggested Auto-sync changes directly in GitHub. We won’t modify files in your repositories outside the .swm folder.

Issues

  • Read and write permissions on issues allow our GitHub App to (1) write comments on your pull requests when your documentation is out of date (2) recommend relevant documentation to read (3) suggest new documentation to create based on the PR.

  • Pull requests

  • Read and write permissions on requests to allow Swimm’s GitHub App to (1) write comments and annotations on your pull requests when your documentation is out of date, or (2) when we can recommend relevant documentation to read or suggest creating new documentation based on the pull request.

Swimm’s GitHub App pays attention to the following events in your codebase:​

Pull requests

  • To make sure we can verify the code in your pull requests and notify you when new documentation is included in a pull request that was merged, we require PR event permissions.

Check Runs

  • To keep track of our Swimm Verify Check status and react accordingly, as well as support some of our more advanced features such as approving Auto-synced changes directly from GitHub, we require Check Runs permissions.

Swimm is SOC 2 compliant and ISO 27001 certified. Read about security aspects of our GitHub App here.
Reach out to us at info@swimm.io to request Swimm’s SOC 2 Type II report.

This document is automatically kept up to date using Swimm.