If you're using GitHub, 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.
Once you are set up with your workspace and connect a repository, go to GitHub and install it on your repositories.
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.
Trigger a Swimm Commit by clicking 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.
Swimm’s GitHub app alerts you to relevant docs on PRs, recommending documentation to review when code changes.
Examples of when a doc may be recommended:
- a fragile piece of code changes referencing an Incident Report
- whenever someone changes a covered testing in an E2E testing guide
- when someone changes a configuration script in CI deployment documentation
Swimm Verify Check on PR changes only
Swimm’s GitHub app has an option to run Swimm Verify only on files that are changed in the 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.
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; stay tuned!
Doc Hooks - Alpha
Swimm is currently developing a new feature — Doc Hooks — which will allow you to set a doc recommendation when a certain path is changed.
A few examples of Doc Hooks:
- Addition of a new database migration file → link to your database migration policy
- Modification of a configuration file → link to your environment variable update process walkthrough
- Addition of a new record in your infrastructure as a code setting → link to your explainer on how to verify it will be deployed correctly
Permissions needed for Swimm’s GitHub App
Swimm requests the following permissions for our GitHub App:
- 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.
- 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:
- 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.
- 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.
Reach out to us to request Swimm’s SOC 2 Type II report.