From c1d3f6022fe0142be60f3043e595a0106eae49f4 Mon Sep 17 00:00:00 2001 From: Mateusz Urbanek Date: Sun, 24 May 2026 17:29:00 +0200 Subject: [PATCH] docs(plugins): add Tangled scm and pullrequest pages Document the new tangled scm kind and tangled/pullrequest action, including the atproto auth model (app password against the PDS) and the HTTPS-clone / SSH-push constraint imposed by Tangled knots. Signed-off-by: Mateusz Urbanek --- .../tangled_pullrequest/updatecli.yaml | 40 ++++++++++ .../docs/plugins/tangled/updatecli.yaml | 22 ++++++ content/en/docs/plugins/actions/tangled.adoc | 45 ++++++++++++ content/en/docs/plugins/scm/tangled.adoc | 73 +++++++++++++++++++ 4 files changed, 180 insertions(+) create mode 100644 assets/code_example/docs/plugins/actions/tangled_pullrequest/updatecli.yaml create mode 100644 assets/code_example/docs/plugins/tangled/updatecli.yaml create mode 100644 content/en/docs/plugins/actions/tangled.adoc create mode 100644 content/en/docs/plugins/scm/tangled.adoc diff --git a/assets/code_example/docs/plugins/actions/tangled_pullrequest/updatecli.yaml b/assets/code_example/docs/plugins/actions/tangled_pullrequest/updatecli.yaml new file mode 100644 index 000000000..9fe462dd5 --- /dev/null +++ b/assets/code_example/docs/plugins/actions/tangled_pullrequest/updatecli.yaml @@ -0,0 +1,40 @@ +# updatecli.yaml +# updatecli diff --config updatecli.yaml +# +name: Show Tangled pipeline example + +scms: + tangled: + kind: tangled + spec: + owner: alice.tangled.sh + repository: updatecli-mirror + branch: main + handle: alice.tangled.sh + appPassword: '{{ requiredEnv "TANGLED_APP_PASSWORD" }}' + +# Sources are responsible to fetch information from third location such as npm registry. +sources: + updatecli: + name: Get latest axios version + kind: npm + spec: + name: axios + +# Targets are responsible to update targeted files such as a yaml file. +targets: + npm: + name: Update e2e test file + kind: yaml + sourceid: updatecli + scmid: tangled + spec: + file: e2e/updatecli.d/success.d/npm.yaml + key: $.conditions.axios.spec.version + +# Actions such as tangled/pullrequest are triggered when a target is updated. +actions: + default: + kind: tangled/pullrequest + scmid: tangled + title: Bump axios version diff --git a/assets/code_example/docs/plugins/tangled/updatecli.yaml b/assets/code_example/docs/plugins/tangled/updatecli.yaml new file mode 100644 index 000000000..e9548c520 --- /dev/null +++ b/assets/code_example/docs/plugins/tangled/updatecli.yaml @@ -0,0 +1,22 @@ +--- +name: Test Tangled scm + +scms: + tangled: + kind: tangled + spec: + owner: alice.tangled.sh + repository: updatecli-mirror + branch: main + handle: alice.tangled.sh + # atproto app password used to author pull request records on the user's PDS. + # Generate one from your PDS's web UI (Bluesky: https://bsky.app/settings/app-passwords). + appPassword: '{{ requiredEnv "TANGLED_APP_PASSWORD" }}' + +sources: + license: + name: Retrieve license file content + kind: file + scmid: tangled + spec: + file: LICENSE diff --git a/content/en/docs/plugins/actions/tangled.adoc b/content/en/docs/plugins/actions/tangled.adoc new file mode 100644 index 000000000..aa6d33dc8 --- /dev/null +++ b/content/en/docs/plugins/actions/tangled.adoc @@ -0,0 +1,45 @@ +--- +title: "Tangled Pull Request" +description: "Open a Tangled Pull Request" +lead: "kind: tangled/pullrequest" +date: 2026-05-24T00:00:00+00:00 +draft: false +images: [] +menu: + docs: + parent: "plugin-actions" +toc: true +plugins: + - actions +--- + +// +:toc: +// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key +:toclevels: 4 + +== Description + +The `actions` section describes the link:https://tangled.sh[Tangled] Pull Requests that updatecli is expected to open (or update) when the manifest is applied. + +Tangled pull requests are atproto records (`sh.tangled.repo.pull`) written on the author's Personal Data Server (PDS). The plugin: + +. Resolves the target repository DID by reading the `repoDid` field of the matching `sh.tangled.repo` record on the owner's PDS (or uses the explicit `repoDid` from the action spec when set). The appview indexes pull request records by this knot-minted DID, not by the owner DID. +. Lists existing `sh.tangled.repo.pull` records on the author's PDS, cross-references them against `sh.tangled.repo.pull.status` records, and skips creation only when an *open* pull request already targets the same source/target branch pair. Closed or merged pulls do not block creation of a replacement. +. Runs `git format-patch ..` inside the scm working directory and gzip-compresses the resulting patch. +. Uploads the gzipped patch as an atproto blob via `com.atproto.repo.uploadBlob`. +. Writes the `sh.tangled.repo.pull` record via `com.atproto.repo.putRecord`. + +Authentication uses an atproto app password against the configured PDS (defaults to `https://bsky.social`; override with `pds` when your account lives elsewhere). Generate the app password from your PDS's web UI — never paste your account password into the manifest. + +== Parameters + +{{< resourceparameters "actions" "tangled/pullrequest" >}} + +== Example + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/tangled.adoc b/content/en/docs/plugins/scm/tangled.adoc new file mode 100644 index 000000000..e2befc845 --- /dev/null +++ b/content/en/docs/plugins/scm/tangled.adoc @@ -0,0 +1,73 @@ +--- +title: "Tangled" +description: "Interact with Tangled repositories" +lead: "Tangled scm" +date: 2026-05-24T00:00:00+00:00 +draft: false +images: [] +menu: + docs: + parent: "plugin-scm" +toc: true +plugins: + - scm +--- + +// +:toc: +// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key +:toclevels: 4 + +== Description + +The Tangled scm plugin is used to manage git repositories hosted on link:https://tangled.sh[Tangled], an AT protocol based git host. Depending on the stage, it can be used for different purposes: + +**source**: Retrieve data from a git repository, such as a file content + +**condition**: Ensure data exist on a git repository, such as a file content + +**target**: Ensure data is up to date on a git repository + +== Authentication + +Tangled repositories live on knots (git servers) while pull request records are stored as atproto records on the author's Personal Data Server (PDS). + +* Git clone and push both go through SSH. Tangled knots reject HTTPS pushes, so the plugin uses an `ssh://`-style URL for both directions. For the default knot (`knot1.tangled.sh`), the SSH gateway lives on `tangled.org`; self-hosted knots use the knot hostname directly. The plugin builds the URL automatically from `owner` and `repository`; override with `cloneURL` only if you need a different host or path. +* Authentication relies on your SSH agent. Make sure the key registered with your Tangled account is loaded (`ssh-add ~/.ssh/id_ed25519`); the underlying `go-git` transport does not read default identity files on its own. +* Pull request creation uses an atproto app password against the user's PDS (no token is sent to the knot itself). Generate the app password from your PDS's web UI (Bluesky users: https://bsky.app/settings/app-passwords). + +== Parameters + +{{< resourceparameters "scms" "tangled" >}} + +=== CommitMessage + +Updatecli uses conventional commits as described on link:https://www.conventionalcommits.org/[www.conventionalcommits.org]. + +[cols="1,1,1,4",options=header] +|=== +| Name | Required | Default | Description +| type ||chore| Specify commit type +| scope ||| Specify commit scope +| footer ||| Specify commit footer message +| title ||| Override default body message +| hideCredit ||| Remove "Made with ❤️️ by updatecli" from commit message +| body ||| Override default body message +|=== + +=== GPG + +Updatecli can sign commits using a private GPG key if configured accordingly. + +[cols="1,1,1,4",options=header] +|=== +| Name | Required | Default | Description +| signingkey ||| Defines the armored private gpg key +| password ||| Defines the gpg key password +|=== + +== Example + +[source,yaml] +---- +# updatecli.yaml +{{}} +----