Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ jobs:
persist-credentials: false
- name: Each unit the README enables has an [Install] section
run: sh test/units/install-sections.sh
- name: CI runs every install command of the README
# The README marks its install blocks; the install-loop job runs
# them as written. An install command outside a marked block fails.
run: sh test/units/readme-block.sh --check
- name: Check the example scripts and units
run: |
set -eu
Expand Down Expand Up @@ -128,6 +132,26 @@ jobs:
# units as the README says, and each must be enabled (issue #20).
run: sudo sh test/units/first-run.sh "${RUNNER_TEMP}/pullgate"

install-loop:
name: README install and a full loop under the units
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
- name: Build
run: CGO_ENABLED=0 go build -trimpath -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate
- name: The README install, then a good commit and a failed one
# The install commands come from README.md itself. Root and the
# listener are different users, under the real units. A tap on a
# fake Telegram applies a commit; a failing commit rolls back
# (DESIGN.md section 14, issue #27).
run: sudo sh test/units/full-loop.sh "${RUNNER_TEMP}/pullgate"

lint:
runs-on: ubuntu-latest
steps:
Expand All @@ -150,7 +174,7 @@ jobs:
echo "${SHELLCHECK_SHA256} $dir/shellcheck.tar.xz" | sha256sum --strict -c -
tar -xJf "$dir/shellcheck.tar.xz" -C "$dir"
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh test/units/first-run.sh test/units/install-sections.sh
"$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh test/units/*.sh
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version-file: go.mod
Expand Down
74 changes: 74 additions & 0 deletions .github/workflows/install-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
name: Install a release

# Installs a published release with its own install.sh, as a user does,
# and runs the README install and a full loop under the units of that
# release (test/units/full-loop.sh, DESIGN.md section 14, issue #27).
#
# The Release workflow calls this after it publishes. A release that the
# Release workflow publishes with GITHUB_TOKEN starts no "release" event,
# so the call is the path that runs. "release: published" covers a release
# published by hand. Run it by hand for any release from v0.3.0 on (older
# tags have no test/units/full-loop.sh).

on:
release:
types: [published]
workflow_call:
inputs:
version:
description: "The version to install, X.Y.Z"
required: true
type: string
workflow_dispatch:
inputs:
version:
description: "The version to install, X.Y.Z"
required: true
type: string

permissions:
contents: read

jobs:
install:
name: install ${{ inputs.version || github.event.release.tag_name }} and a full loop
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
env:
# Through env, never put into the script text.
INPUT_VERSION: ${{ inputs.version }}
RELEASE_TAG: ${{ github.event.release.tag_name }}
steps:
- name: The version
id: version
shell: bash
run: |
set -eu
v="${INPUT_VERSION:-${RELEASE_TAG#v}}"
# The whole string, so a value with a newline does not pass.
if ! [[ "$v" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::The version is not X.Y.Z. Give the version without the v, for example 0.3.0."
exit 1
fi
echo "version=$v" >>"$GITHUB_OUTPUT"
# The tag of the release: its install.sh, README and units, as a user
# gets them.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: refs/tags/v${{ steps.version.outputs.version }}
persist-credentials: false
- name: install.sh --version, as the README says
# install.sh checks the SHA-256 and the build attestation, and
# installs nothing when a check fails. It needs no GitHub login.
env:
VERSION: ${{ steps.version.outputs.version }}
run: |
set -eu
sudo env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh ./install.sh --version "$VERSION"
/usr/local/bin/pullgate --version
- name: The README install and a full loop under the units
env:
VERSION: ${{ steps.version.outputs.version }}
run: sudo sh test/units/full-loop.sh --installed "$VERSION"
12 changes: 12 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -177,3 +177,15 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
run: gh release edit "$TAG" --draft=false --repo "$GITHUB_REPOSITORY"

# Installs the published release with its install.sh and runs a full
# loop (install-release.yml). A failure here does not undo the release:
# it means the release needs a fix release (docs/releasing.md).
install-test:
needs: [release-please, publish]
if: needs.release-please.outputs.release_created == 'true'
permissions:
contents: read
uses: ./.github/workflows/install-release.yml
with:
version: ${{ needs.release-please.outputs.version }}
36 changes: 36 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -752,6 +752,42 @@ that cannot be enabled, fails CI. Without root, CI also runs
checks that each unit the README tells you to enable has an `[Install]`
section with `WantedBy=`.

`test/units/full-loop.sh` (CI job `install-loop`, on each pull request
and on `main`) is the path a user takes, as root on the throwaway runner:

1. It runs the install commands **from README.md itself**: each install
block has a comment line `<!-- install-test:NAME -->` (`binary`,
`setup`, `start`) before its `sh` block, and the script runs the block
as written, with `NAME` set to `config-repo`.
`test/units/readme-block.sh --check` fails when a block is missing, or
when an install command (`useradd`, `groupadd`, `install -X`, `chown`,
`chmod`, `cp contrib/systemd`, `systemctl enable`) is in an unmarked
fenced block. So
the README cannot drift from what CI runs.
2. A local bare repo is the remote. A fake Telegram on `127.0.0.1`
(`test/units/faketg.py --tap`) records each message and taps Apply on
each question as the owner.
3. A good commit: `pullgate run` under `pullgate-run@.service` asks (with
`check` and `summary` as the check user), the listener (user
`pullgate`) sends the question and writes the approval,
`pullgate-apply@.service` applies it, and `pullgate status` shows it as
applied.
4. It restarts the listener and checks that it polls again.
5. A commit whose apply fails: the rollback runs, and its notice reaches
the fake Telegram.
6. Each unit of the README `start` block is `enabled` and `active`.

After each loop, the outbox must be empty and the listener must have
logged no error and no warning. So a message that root writes and the
listener cannot read fails the job.

The workflow **Install a release** (`install-release.yml`) runs the same
script against a published release: it installs the release with the
tag's own `install.sh --version X.Y.Z`, then runs
`full-loop.sh --installed X.Y.Z` with the README and units of the tag.
The Release workflow calls it after it publishes; it also runs on
`release: published` and by hand.

## 15. Not in version 0.1

- Self-update of pullgate. `install.sh` updates it only when root runs
Expand Down
14 changes: 13 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,12 @@ what it trusts: [DESIGN.md](DESIGN.md) section 16 and

**By hand.** Download a release and check it as
[docs/releasing.md](docs/releasing.md) says (section "Verify a download").
Then, as root: `install -m 0755 pullgate /usr/local/bin/pullgate`.
Then, as root:

<!-- install-test:binary -->
```sh
install -m 0755 pullgate /usr/local/bin/pullgate
```

**From the source**, with Go 1.26 or newer. Then install it as above:

Expand All @@ -83,6 +88,7 @@ CGO_ENABLED=0 go build -trimpath -o pullgate ./cmd/pullgate
Then, as root, make the users and the directories, and copy the units from
[contrib/systemd/](contrib/systemd/):

<!-- install-test:setup -->
```sh
useradd --system --no-create-home --shell /usr/sbin/nologin pullgate
# One check user per instance, never the listener user:
Expand All @@ -106,6 +112,7 @@ cp contrib/systemd/* /etc/systemd/system/
the examples below.
6. Start it:

<!-- install-test:start -->
```sh
systemctl daemon-reload
systemctl enable --now pullgate-listen.service
Expand Down Expand Up @@ -305,6 +312,11 @@ golangci-lint run --build-tags e2e
go test -race -tags e2e ./test/e2e/...
```

CI runs the install commands of this README as written: each install
block above has an `<!-- install-test:… -->` comment before it, and
`test/units/full-loop.sh` runs those blocks as root, then a full loop
under the units. Keep that comment when you change a block.

The rules for changes are in [AGENTS.md](AGENTS.md).

## License
Expand Down
10 changes: 10 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,16 @@ workflow checks it.
build provenance attestation (`pullgate_<version>.sigstore.json`),
checks the tarballs with it, uploads everything to the draft release and
publishes it. The release is never public without its files.
6. The `install-test` job runs the **Install a release** workflow
(`install-release.yml`): on a fresh runner, it installs the release
with its own `install.sh --version`, runs the README install commands
of the tag, and a full loop under the units (`test/units/full-loop.sh`).
A failure here does not undo the release: fix it in a `fix:` pull
request and make a new release. You can also start this workflow by
hand, with a version from 0.3.0 on. The Release run keeps its
concurrency group until this job ends (up to 20 minutes): do not merge
other pull requests in that time, so no Release run waits and gets
cancelled.

If `build` or `publish` fails, the release stays a draft. Fix the problem
in a new `fix:` pull request and merge the next release pull request.
Expand Down
98 changes: 84 additions & 14 deletions test/units/faketg.py
Original file line number Diff line number Diff line change
@@ -1,38 +1,96 @@
#!/usr/bin/env python3
"""A tiny fake Telegram Bot API for test/units/first-run.sh.
"""A tiny fake Telegram Bot API for the tests in test/units/.

It listens on 127.0.0.1:PORT. It answers every method with "ok", gives no
updates, and appends the name of each method it gets to LOG, one per line.
It never prints a request, so the test token never shows.
It listens on 127.0.0.1:PORT. It appends the name of each method it gets
to LOG, one per line. It never prints a request path, so the test token
never shows.

Usage: python3 -I faketg.py PORT LOG
Without --tap it answers every method with "ok" and gives no updates
(first-run.sh).

With --tap TEXTS (full-loop.sh) it also:
- appends the text of each sendMessage to TEXTS, as one JSON string per
line, so a test can wait for "Applied" or "Rolled back";
- taps the Apply button of each question it gets, two seconds later, as
the owner (user 4242) in the chat 4242, through getUpdates.

Usage: python3 -I faketg.py PORT LOG [--tap TEXTS]
"""

import json
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

PORT = int(sys.argv[1])
LOG = sys.argv[2]
TEXTS = None
if len(sys.argv) == 5 and sys.argv[3] == "--tap":
TEXTS = sys.argv[4]
elif len(sys.argv) != 3:
sys.exit("usage: faketg.py PORT LOG [--tap TEXTS]")
CHAT = 4242
OWNER = 4242
# The listener saves a question after sendMessage returns. A tap that came
# before that would find no question, so the tap waits a little.
TAP_DELAY = 2.0

lock = threading.Lock()
state = {"next_msg": 1, "next_update": 1, "updates": []}

class Handler(BaseHTTPRequestHandler):
next_id = 1

def apply_button(req):
"""The callback data of the Apply button of a question, or None."""
rows = (req.get("reply_markup") or {}).get("inline_keyboard") or []
for row in rows:
for b in row:
data = b.get("callback_data", "")
if data.startswith("a:"):
return data
return None


class Handler(BaseHTTPRequestHandler):
def do_POST(self):
length = int(self.headers.get("Content-Length") or 0)
self.rfile.read(length)
raw = self.rfile.read(length)
try:
req = json.loads(raw or b"{}")
except ValueError:
req = {}
method = self.path.rsplit("/", 1)[-1]
with open(LOG, "a", encoding="utf-8") as f:
f.write(method + "\n")
with lock:
with open(LOG, "a", encoding="utf-8") as f:
f.write(method + "\n")
if method == "getUpdates":
time.sleep(1)
result = []
result = self.updates(int(req.get("offset") or 0))
elif method == "sendMessage":
result = {"message_id": Handler.next_id, "chat": {"id": CHAT}, "text": ""}
Handler.next_id += 1
text = str(req.get("text", ""))
with lock:
mid = state["next_msg"]
state["next_msg"] += 1
if TEXTS is not None:
with open(TEXTS, "a", encoding="utf-8") as f:
f.write(json.dumps(text, ensure_ascii=False) + "\n")
data = apply_button(req)
if data is not None:
state["updates"].append({
"at": time.monotonic() + TAP_DELAY,
"update": {
"update_id": state["next_update"],
"callback_query": {
"id": "tap-%d" % mid,
"from": {"id": OWNER},
# The text that this fake gives back, so
# the listener's text hash matches.
"message": {"message_id": mid, "chat": {"id": CHAT}, "text": text},
"data": data,
},
},
})
state["next_update"] += 1
result = {"message_id": mid, "chat": {"id": CHAT}, "text": text if TEXTS is not None else ""}
else:
result = True
body = json.dumps({"ok": True, "result": result}).encode()
Expand All @@ -42,6 +100,18 @@ def do_POST(self):
self.end_headers()
self.wfile.write(body)

def updates(self, offset):
"""The updates from offset on that are due. Waits up to a second."""
end = time.monotonic() + 1
while True:
now = time.monotonic()
with lock:
state["updates"] = [u for u in state["updates"] if u["update"]["update_id"] >= offset]
due = [u["update"] for u in state["updates"] if u["at"] <= now]
if due or now >= end:
return due
time.sleep(0.1)

def log_message(self, *args):
pass

Expand Down
Loading
Loading