Documentation

README.md

@@ -5,3 +5,85 @@ It attempts to simulate user interactions with Science Platform services continu
 It can be used for both monitoring and synthetic load testing.
 
 mobu is developed with the [Safir](https://safir.lsst.io/) framework.
+
+A full-blown [Documenteer](https://documenteer.lsst.io/) site with more detailed documentation is coming soon.
+
+## Developers
+
+### GitHub Integration
+
+#### Auto-refresh notebook flocks
+
+*Problem*
+
+You have a GitHub repo filled with Python notebooks.
+You've already configured Mobu to run a flock that executes these notebooks.
+But every time you commit changes to the notebooks in this repo, you have to restart Mobu to get it to pick up the changes!
+
+*Solution*
+
+Enable a GitHub app for your repo, and Mobu will automatically pick up any changes!
+
+##### Configuration
+
+There is a `mobu refresh (<env url>)` GitHub app for every environment that runs Mobu (Except environments behind a VPN).
+For every environment in which you want your repo to auto refresh, you have to:
+
+*Install the app in your repo's organization, if it's not already installed*
+1. Have a Mobu autorun flock configured and running
+1. Install that environment's `mobu refresh` app in your repo's GitHub organization. Someone with appropriate permissions can do that from the [app's homepage](#mobu-refresh-github-app-urls)
+1. Add your organization to the `accetped_github_orgs` list in the Mobu configuration in Phalanx for the matching env
+
+*Enable the app for your repo*
+1. Go to your repo's organization settings page in GitHub, and go to the "GitHub Apps" page in the "Third-party Access" section in the left sidebar. [Here](https://github.com/organizations/lsst-sqre/settings/installations) is that page for the `lsst-sqre` organization
+1. Click the `Configure` button in the `mobu refresh (<env url>)` row
+1. In the "Repository access" section, click the "Select repositories" dropdown and add your repository
+
+##### Optional Configuration
+You can have mobu ignore changed notebooks in certain directories in these CI checks by listing them in a file named `mobu.yaml` at the root of your repo, like this:
+
+```yaml
+exclude_dirs:
+- somedir
+- some/other/dir
+```
+With this configuration, no notebooks in the `somedir`, or `some/other/dir` directories, or any of their descendant directories, will be executed, even if they changed in the commit.
+
+##### Mobu Refresh GitHub App URLs
+* [data-dev.lsst.cloud](https://github.com/apps/mobu-refresh-data-dev-lsst-cloud)
+
+#### Run notebooks in Mobu as a GitHub CI check
+
+*Problem*
+
+You have a GitHub repo filled with Python notebooks.
+You've already configured Mobu to run a flock that executes these notebooks.
+You want to make sure that any changes to these notebooks don't cause them to break when they run in Mobu, but you don't want to have to commit the possibly-broken changes just to get Mobu to run them to test the changes.
+
+*Solution*
+
+Enable a GitHub app for your repo, and Mobu will create a GitHub Actions check that runs changed notebooks in Mobu on any commit associated with a pull request!
+
+##### Configuration
+There is a `mobu CI (<env url>)` GitHub app for every non-production environment that runs Mobu (Except environments behind a VPN).
+For every environment in which you want to run your changed notebooks on every PR commit, you have to:
+*Install the app in your repo's organization, if it's not already installed*
+1. Install that environment's `mobu CI` app in your repo's GitHub organization. Someone with appropriate permissions can do that from the [app's homepage](#mobu-ci-github-app-urls)
+1. Add your organization to the `accetped_github_orgs` list in the Mobu configuration in Phalanx for the matching env
+
+*Enable the app for your repo*
+1. Go to your repo's organization settings page in GitHub, and go to the "GitHub Apps" page in the "Third-party Access" section in the left sidebar. [Here](https://github.com/organizations/lsst-sqre/settings/installations) is that page for the `lsst-sqre` organization
+1. Click the `Configure` button in the `mobu CI (<env url>)` row
+1. In the "Repository access" section, click the "Select repositories" dropdown and add your repository
+
+##### Troubleshooting
+There is a small chance that a GitHub check could get stuck in a forever-in-progress state for a given commit if the stars align in a very specific way when mobu restarts.
+If this happens, you can push a commit to your branch, and it will start a new check run.
+If you don't have any actual changes to commit, you can push an empty commit like this:
+```
+git commit --allow-empty -m "Empty commit"
+```
+You can squash that commit later if you want a clean history.
+
+##### Mobu CI GitHub App URLs
+* [data-dev.lsst.cloud](https://github.com/apps/mobu-ci-data-dev-lsst-cloud)