This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new c48aaab Document the script to simplify file signing
c48aaab is described below
commit c48aaab557022e34c1dd5821ca5847063af3d04e
Author: Sean B. Palmer <[email protected]>
AuthorDate: Wed Jan 7 20:39:18 2026 +0000
Document the script to simplify file signing
---
atr/docs/code-conventions.md | 2 ++
atr/docs/index.md | 1 +
atr/docs/running-the-server.md | 2 +-
atr/docs/signing-artifacts.md | 71 ++++++++++++++++++++++++++++++++++++++++++
atr/docs/user-guide.md | 4 +++
5 files changed, 79 insertions(+), 1 deletion(-)
diff --git a/atr/docs/code-conventions.md b/atr/docs/code-conventions.md
index 971c278..fe3b59b 100644
--- a/atr/docs/code-conventions.md
+++ b/atr/docs/code-conventions.md
@@ -12,6 +12,8 @@
* [HTML](#html)
* [Markdown](#markdown)
* [JavaScript](#javascript)
+* [Shell](#shell)
+* [OCI container files ("dockerfiles")](#oci-container-files-dockerfiles)
## Python code
diff --git a/atr/docs/index.md b/atr/docs/index.md
index 70eaca7..c180ff1 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -8,6 +8,7 @@ NOTE: This documentation is a work in progress.
* `1.` [Introduction to ATR](introduction-to-atr)
* `2.` [User guide](user-guide)
+ * `2.1.` [Signing artifacts](signing-artifacts)
* `3.` [Developer guide](developer-guide)
* `3.1.` [Running the server](running-the-server)
* `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/running-the-server.md b/atr/docs/running-the-server.md
index c3dcfdc..757b86a 100644
--- a/atr/docs/running-the-server.md
+++ b/atr/docs/running-the-server.md
@@ -2,7 +2,7 @@
**Up**: `3.` [Developer guide](developer-guide)
-**Prev**: (none)
+**Prev**: `2.1.` [Signing artifacts](signing-artifacts)
**Next**: `3.2.` [Overview of the code](overview-of-the-code)
diff --git a/atr/docs/signing-artifacts.md b/atr/docs/signing-artifacts.md
new file mode 100644
index 0000000..864760e
--- /dev/null
+++ b/atr/docs/signing-artifacts.md
@@ -0,0 +1,71 @@
+# 2.1. Signing artifacts
+
+**Up**: `2.` [User guide](user-guide)
+
+**Prev**: (none)
+
+**Next**: `3.1.` [Running the server](running-the-server)
+
+**Sections**:
+
+* [Introduction](#introduction)
+* [How to sign artifacts](#how-to-sign-artifacts)
+* [Optional steps](#optional-steps)
+* [Security considerations](#security-considerations)
+
+## Introduction
+
+The ASF Infrastructure team provide an [extensive guide to signing
artifacts](https://infra.apache.org/release-signing.html) which should be
followed.
+
+For users who prefer a faster route to signing artifacts, such as novice
release managers, this page provides a very quick guide. We sacrifice some
security and comprehensiveness in the process, but this guide does not replace
or supplant the ASF Infra guide above. Please refer to that for further detail.
+
+## How to sign artifacts
+
+### Step 1: Install the requirements
+
+Install GnuPG 2.1 or higher in your package manager. The `gpg` and `gpgconf`
commands must be available in your `PATH`, with those exact names. Some package
managers install GnuPG 2 with the `gpg2` command, so double check this.
+
+[Download the `gpgsign.sh` shell
script](https://release-test.apache.org/static/sh/gpgsign.sh) that we make
available as part of ATR. The rest of this guide will assume that it is
available on your path as `gpgsign`, but you can call it using `sh gpgsign.sh`
etc.
+
+### Step 2: Generate an OpenGPG keypair
+
+Choose where to write your OpenPGP keys. This can be anywhere, but you will
need to keep your private key secure. This guide will put them in the home
directory.
+
+```shell
+gpgsign issue "Alice Bao" [email protected] ~/.public.asc ~/.private.asc
+```
+
+### Step 3: Sign your files with your private key
+
+Say you want to sign all `.tar.gz` files in the present directory. You can do
that by using:
+
+```shell
+for fn in *.tar.gz
+do
+ gpgsign sign ~/.private.asc "$fn"
+done
+```
+
+This will create `.tar.gz.asc` files, which is standard. Supply an extra
argument to `gpgsign sign` if you want to choose different filenames.
+
+### Step 4: Upload your key to ATR
+
+Go to [add your OpenPGP key](https://release-test.apache.org/keys/add) on ATR
and upload your _public_ key. Do not upload your private key. You must not
reveal your private key to anyone, or store it on untrusted equipment.
+
+## Optional steps
+
+That's all that you need to do, but you can also take the following step.
+
+### Step 5: Verify the signatures (optional)
+
+Optionally, you can check the signatures that you just created. This can
guard, for example, against having accidentally created empty signature files.
ATR will also validate your signatures for you, but for example you can run:
+
+```shell
+gpgsign verify ~/.public.asc example.tar.gz
+```
+
+Assuming that the signature is at `example.tar.gz.asc`. Otherwise you can
supply an extra argument for the signature file path.
+
+## Security considerations
+
+For ease of use, this script creates a key without password protection. For
enhanced security, please follow the [extensive guide to signing
artifacts](https://infra.apache.org/release-signing.html) by ASF Infra. This
script has not been audited, and has not been tested in a wide range of
environments. There is one known potential race condition, and temporary
directories are generated using an insecure pseudorandom value. These are
limitations of the script to make it portable.
diff --git a/atr/docs/user-guide.md b/atr/docs/user-guide.md
index cfac4de..10dea15 100644
--- a/atr/docs/user-guide.md
+++ b/atr/docs/user-guide.md
@@ -6,6 +6,10 @@
**Next**: `3.` [Developer guide](developer-guide)
+**Pages**:
+
+* `2.1.` [Signing artifacts](signing-artifacts)
+
**Sections**:
* [Introduction](#introduction)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
