Swimm’s GitHub App helps developer teams create, maintain, and find documentation as part of the development workflow.
When our team at Swimm began designing Swimm’s GitHub app, we needed to identify the best moment to interact with users. We knew, for example, that running and notifying users on every open branch can be annoying, and we wanted to make the experience simple and enjoyable. Moreover, we understood that we had to find the window of opportunity for developers – the best time when software engineers were looking for checks, reviews, and comments.
Design of Swimm’s GitHub App
Our team at Swimm started designing the GitHub App integration in 2021, keeping in mind that most interactions happen during Pull Requests because it’s usually the last point the code can be verified before it is merged into the main branch and deployed. But it’s also the first time when software engineers push their code and mark it as ready for review.
The initial version of Swimm’s GitHub App ran our Swimm Verify check whenever a PR was opened or an open PR was updated. This allowed us to make sure the documentation on the branch would stay up to date so that code changes would not require an update to the documentation.
Continuously improving Swimm’s GitHub App
Since then, we have added quite a few capabilities and features. Today we’re covering Swimm’s GitHub App features one by one.
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, users are notified via a comment on your pull request. You can then 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
We’ve taken the Auto-sync feature one step further. In the GitHub app settings, you can set up automatic Auto-sync approval. Swimm’s GitHub App will automatically accept Auto-sync changes, committing them to your open pull request in a dedicated commit. Clients rely on Swimm’s trusted patented Auto-sync algorithm to automatically update their documentation with this feature.
New doc notifications
Since tracking and locating documentation is challenging, we designed a feature for New Doc Notifications: you can 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.
Draft documents from Pull Requests
We all know too well that documentation is usually an afterthought, or something completed after writing tests and making code review requested changes to your PR.
This is exactly why Swimm’s GitHub App analyzes your code changes, and when a Pull Request is interesting enough to document, we notify you with a comment and encourage you to create it. With a single click on the Review Draft in App button in our comment, you go into Swimm’s Web App. All the code changes from your Pull Request are added to a document, and all that’s left for you is explaining what the code does. There are no rules for how to do this, but ideally, you would want to arrange it in an order that tells a story.
Doc recommendations
When you change code that has relevant documentation, Swimm’s GitHub App recommends documentation for you to review. This helps users access documentation about specific code changes by alerting you to relevant documentation on PRs.
Here are a few examples you might see: a doc is recommended to you for your E2E testing guide whenever someone changes a covered test; the CI deployment documentation is recommended when someone changes a configuration script; a fragile piece of code changes, and you are alerted to documentation that references an Incident Report.
Swimm Verify on PR changes only
We created an option to run Swimm Verify only on files that are changed in the Pull Request.
Here’s why: because we know that sometimes things break on the main branch. Perhaps a merge conflict or two competing changes are going on simultaneously. And we know that this can happen with your documentation as well. While these changes might take some time to be fixed, they might otherwise fail our Swimm Verify check across your repository, even on unrelated Pull Requests. So we suggest that it is a worthwhile option to turn this feature on until issues with your main branch are resolved. This feature helps our clients avoid unnecessary delays.
Disabling comments
Our engineering teams work in a fast-paced environment; we move quickly, frequently break things, and always work on bug fixes.
Therefore, we designed Swimm’s GitHub App with an option to disable comments. This helps reduce the number of notifications that you’ll be sent during busy deadlines and crunch time. And then, of course, you always have the option to enable the comments again whenever you wish.
Integrations with other tools
Swimm partnered with Atlassian Compass – bringing Swimm to Compass’ ecosystem so that you can see your latest documentation status for all your distributed services from a single place. You can also use Swimm’s Compass Integration to link Swimm documentation to the Compass component.
Swimm is currently integrating additional tools to facilitate understanding the bigger picture of your software development status with your Swimm documentation included.
Doc rules
Getting recommendations for a relevant document to existing code is helpful. But what about newly added code? There should be a way to locate documentation in situations such as:
- When a new database migration is added → link to your database migration policy
- When the configuration file is modified → link to your environment variable update process walkthrough
- When a new record is added to your Infrastructure as a code setting → link to your explainer on how to verify it will be deployed correctly.
Our team at Swimm has created solutions to these exact problems that recommends a specific document when a certain file is changed or something is added to a folder. Admins can now automate workflows using Swimm’s GitHub App to set up conditions and actions to promote documentation.
FAQ
Answering some of your frequently asked questions about Swimm’s GitHub App here.
If you have additional questions, check out Swimm’s doc site. Also, please feel free to contact our team in Swimm’s Community Slack Channel.
How can I get the Swimm GitHub App?
To get the Swimm GitHub App, you first need to sign up for Swimm. Once you are set up with your workspace and connect a repository, go to https://github.com/apps/swimm-io and install it on your repositories.
Do I need to be registered with Swimm to use Swimm’s GitHub App?
The simple answer is yes. You should use Swimm’s Web App to create documentation and configure the setting for our GitHub App.
How much does Swimm’s GitHub App cost?
Swimm has three plans. Learn more about Swimm’s pricing plans here.
What permissions are 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.
Note that Swimm is SOC 2 and ISO 27001 certified. Read about security aspects of our GitHub App here. To request Swimm’s SOC 2 Type II report, reach out to us by email.
Swimm’s GitHub App helps keep your documentation up to date
Join engineering teams worldwide in bringing code-coupled documentation to the forefront of your development workflow with Swimm’s GitHub app. If you want to take Swimm for a spin but need a tour first, sign up for a product demo, and see the Swimm GitHub App in action!
