Homogenize bin scripts

.credentials.template

@@ -0,0 +1,39 @@
+# All values in this files can be overriden by environment variables
+# with the same names, or by command line arguments.
+
+# Credentials for GitHub
+########################
+
+# First, create a GitHub app as described on https://develop.sentry.dev/integrations/github/.
+# This will give you the App ID and a private key you can save as a .pem file.
+# Then install the app on your account. You'll then find the installation ID
+# in the "Configure" URL listed on https://github.com/settings/installations.
+GITHUB_APP_ID=2876513
+GITHUB_PRIVATE_KEY_PATH=github.pem
+GITHUB_INSTALLATION_ID=120833184
+
+# Credentials for GitLab
+########################
+
+GITLAB_BASE_URL=https://gitlab.com
+# GitLab access token, from https://gitlab.com/-/user_settings/personal_access_tokens.
+GITLAB_ACCESS_TOKEN=
+
+# Credentials for RPC
+#####################
+SCM_RPC_SECRET=some-other-shared-secret-for-scm-etc
+
+# Default repositories
+######################
+
+# The GitLab project ID is a numeric identifier for your repository.
+# You can find it on the project page, in the "..." menu in the top right corner.
+GITLAB_PROJECT_ID=
+
+# For GitHub, the full repository name is used for bin/scm-client
+GITHUB_REPOSITORY_NAME={owner}/{repo}
+# but the repository ID is required for bin/sentry-client.
+# You can find it in the HTML code of the repository page, as:
+# <meta name="octolytics-dimension-repository_id" content="1234567890" />
+#                                                          ^^^^^^^^^^
+GITHUB_REPOSITORY_ID=

README.md

@@ -31,6 +31,75 @@ The SCM solves all the problems you don't want to care about.
 
 We have extensive documentation both inline in the Sentry codebase and on the [Sentry developer documentation](https://develop.sentry.dev/backend/source-code-management-platform/) portal. If you're interested in expanding your SCM usage or in enabling new service-providers for a limited amount of effort take a took at the SCM platform.
 
+### Interactive testing
+
+We provide a few command-line scripts for interactive testing.
+
+You'll need to create `.credentials` according to `.credentials.template` before using them.
+
+Both `bin/*-client` have the same subcommands (see [`add_commands`](src/scm/private/cli_support.py) or use the `--help` command-line option). Some subcommands will fail if attempted against a provider that doesn't implement them.
+
+#### Using the RCP, going through `bin/rpc-server`:
+
+```mermaid
+flowchart LR
+    bin/rpc-client --> bin/rpc-server
+    bin/rpc-server --> GitHub
+    bin/rpc-server --> GitLab
+```
+
+Example: run `bin/rpc-server` in a terminal, then `bin/rpc-client --provider gitlab get-app-installation | jq .data` in another to produce something like:
+
+```
+DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): localhost:8080
+DEBUG:urllib3.connectionpool:http://localhost:8080 "GET /api/0/internal/scm-rpc/ HTTP/1.1" 200 None
+DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): localhost:8080
+DEBUG:urllib3.connectionpool:http://localhost:8080 "POST /api/0/internal/scm-rpc/ HTTP/1.1" 200 None
+{
+  "has_read_access": true,
+  "has_write_access": true
+}
+```
+
+#### Using the RPC, going through a Sentry development environment:
+
+```mermaid
+flowchart LR
+    bin/sentry-client --> sentry
+    sentry --> GitHub
+    sentry --> GitLab
+```
+
+Example: with your sentry development environment running in a terminal (and the target repository configured via Sentry's "integrations" GUI), run `bin/sentry-client --provider github get-pull-request 2 | jq .data` from another terminal to produce something like:
+
+```
+DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): localhost:8000
+DEBUG:urllib3.connectionpool:http://localhost:8000 "GET /api/0/internal/scm-rpc/ HTTP/1.1" 200 217
+DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): localhost:8000
+DEBUG:urllib3.connectionpool:http://localhost:8000 "POST /api/0/internal/scm-rpc/ HTTP/1.1" 200 None
+{
+  "internal_id": "3329785233",
+  "id": "2",
+  "title": "Add blah",
+  "body": null,
+  "state": "open",
+  "merged": false,
+  "html_url": "https://github.com/jacquev6/test-Sentry-Integration-Dev-jacquev6/pull/2",
+  "head": {
+    "sha": "7497e018d01503b6abc3053b7896266115e631f6",
+    "ref": "topics/blah"
+  },
+  "base": {
+    "sha": "0941ee0a9eac9914cfddf5adec7a9558a2f1c447",
+    "ref": "main"
+  },
+  "author": {
+    "id": "327146",
+    "username": "jacquev6"
+  }
+}
+```
+
 # Releasing a New Version
 
 1. On the `getsentry/scm-platform` repository page click the `Actions` tab.