docs: add global install documentation

README.md

@@ -10,6 +10,15 @@ The plugin contains a Git credential helper, enabled for the current step via an
 The credential helper calls `chinmina-bridge` when credentials for a GitHub
 repository are requested, supplying the result to Git in its expected format.
 
+> [!IMPORTANT]
+>
+> In order for this plugin to work for a whole pipeline, it must be enabled on
+> every step. **This includes any steps configured in the [pipeline
+> configuration](https://buildkite.com/docs/pipelines/defining-steps).**
+>
+> Alternatively, the plugin may be enabled globally by the agent: see
+> instructions below.
+
 ## Example
 
 Add the following to your `pipeline.yml`:
@@ -18,9 +27,9 @@ Add the following to your `pipeline.yml`:
 steps:
   - command: ls
     plugins:
-      - jamestelfer/github-app-auth#v0.1.0:
-          vendor-url: "https://your-vendor-agent"
-          audience: "github-app-auth:your-buildkite-organization"
+      - jamestelfer/github-app-auth#v1.0.0:
+          vendor-url: "https://chinmina-bridge-url"
+          audience: "chinmina-bridge:your-github-organization"
 ```
 
 ## Configuration
@@ -35,15 +44,66 @@ your Buildkite agents.
 
 **Default:** `github-app-auth:default`
 
-The value of the `aud` claim of the OIDC JWT that will be sent to the helper
-agent. This must correlate with the value configured in the vendor agent
-settings.
+The value of the `aud` claim of the OIDC JWT that will be sent to
+[`chinmina-bridge`][chinmina-bridge]. This must correlate with the value
+configured in the `chinmina-bridge` settings.
 
-A recommendation: `github-app-auth:your-github-organization`. This is specific
+A recommendation: `chinmina-bridge:your-github-organization`. This is specific
 to the purpose of the token, and also scoped to the GitHub organization that
-tokens will be vended for. The agent's GitHub app is configured for a particular
-GitHub organization/user, so if you have multiple organizations, multiple agents
-will need to be running.
+tokens will be vended for. `chinmina-bridge`'s GitHub app is configured for a
+particular GitHub organization/user, so if you have multiple organizations,
+multiple agents will need to be running.
+
+## Global agent configuration
+
+In order to enable the plugin automatically, consider changing the Buildkite
+agent configuration such that the plugin is installed and enabled by default.
+
+> [!NOTE]
+>
+> Credential helpers are only used by Git for HTTP, not for SSH. This
+> configuration does not change behaviour for SSH connections.
+
+One way to do this is to clone the plugin when the agent is bootstrapped, then
+call the plugin's environment hook directly from the agent's environment hook.
+
+The two scripts below accomplish this:
+
+### Agent `bootstrap` hook additions
+
+```bash
+#!/usr/bin/env bash
+
+echo "installing Github credential plugin"
+
+plugin_repo="https://github.com/jamestelfer/github-app-auth-buildkite-plugin.git"
+plugin_version="v1.0.1"
+plugin_dir="/buildkite/plugins/github-app-auth-buildkite-plugin"
+
+[[ -d "${plugin_dir}" ]] && rm -rf "${plugin_dir}"
+
+GIT_CONFIG_COUNT=1 \
+GIT_CONFIG_KEY_0=advice.detachedHead \
+GIT_CONFIG_VALUE_0=false \
+  git clone --depth 1 --single-branch --no-tags \
+    --branch "${plugin_version}" -- \
+    "${plugin_repo}" "${plugin_dir}"
+```
+
+### Agent `environment` hook additions
+
+```bash
+#
+# executing this script from your infrastructure's environment agent hook will
+# configure Github App Auth for every build
+#
+# Changing the parameters supplied will be necessary to ensure that agents can
+# connect to the service and include the correct audience.
+#
+BUILDKITE_PLUGIN_GITHUB_APP_AUTH_VENDOR_URL="https://chinmina-bridge-url" \
+BUILDKITE_PLUGIN_GITHUB_APP_AUTH_AUDIENCE="chinmina-bridge:your-github-org" \
+    source /buildkite/plugins/github-app-auth-buildkite-plugin/hooks/environment
+```
 
 ## Developing