From 78e730293b99416a04e6518c2384a8d730173d20 Mon Sep 17 00:00:00 2001
From: Jason Hall <jason@chainguard.dev>
Date: Sun, 28 Jan 2024 10:58:41 -0500
Subject: [PATCH] add README

Signed-off-by: Jason Hall <jason@chainguard.dev>
---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..033aa0b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# `octo-sts`
+
+This action federates the Github actions identity token for a Github App token
+according to the Trust Policy in the target organization or repository.
+
+## Usage
+
+```yaml
+permissions:
+  id-token: write # Needed to federate tokens.
+
+steps:
+- uses: chainguard-dev/actions/octo-sts@main
+  id: octo-sts
+  with:
+    # environment determines the environment from which to download the chainctl
+    # binary from.
+    # Optional (default is enforce.dev)
+    scope: your-org/your-repo
+
+    # identity holds the ID for the identity this workload should assume when
+    # speaking to Chainguard APIs.
+    identity: foo
+
+- env:
+    GH_TOKEN: ${{ steps.octo-sts.outputs.token }}
+  run: |
+    gh repo list
+```
+
+The above will load a "trust policy" from `.github/chainguard/foo.sts.yaml` in
+the repository `your-org/your-repo`.  Suppose this contains the following, then
+workflows in `my-org/my-repo` will receive a token with the specified
+permissions on `my-org/my-repo`.
+
+```yaml
+issuer: https://token.actions.githubusercontent.com
+subject: repo:my-org/my-repo:ref:refs/heads/main
+
+permissions:
+  contents: read
+  issues: write
+```