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
230 changes: 204 additions & 26 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,88 +1,266 @@
# Builds, signs, and publishes a release from a pushed tag vX.Y.Z that matches
# manifest.json "version".
#
# The signature is a GitHub artifact attestation (Sigstore keyless). Its
# certificate records this workflow at the tag, which is the identity Silo
# servers and the approved community catalog check, so releases run only from a
# tag push.
#
# Artifacts are not trusted between jobs: any job in the run can replace an
# artifact by name. The checksums and the Sigstore bundle travel as job
# outputs, the signing job attests those checksums without downloading or
# running anything from the repository, and the release job checks the
# downloaded files against the same checksums before publishing.
name: Release

on:
push:
tags:
- 'v*'
workflow_dispatch:

permissions:
contents: write
permissions: {}

jobs:
release:
build:
name: Build release assets
runs-on: ubuntu-24.04
timeout-minutes: 45
permissions:
contents: read
outputs:
tag: ${{ steps.version.outputs.tag }}
version: ${{ steps.version.outputs.version }}
checksums: ${{ steps.assets.outputs.checksums }}
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
fetch-depth: 0
persist-credentials: false

# No module or build cache: a signed release must not consume cache
# entries that other workflow runs in the repository could have written.
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version-file: go.mod
cache: false

- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: '3.13'

- name: Determine version
- name: Check the tag against manifest.json
id: version
env:
EVENT_NAME: ${{ github.event_name }}
REF: ${{ github.ref }}
run: |
if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
tag="${GITHUB_REF_NAME}"
else
latest=$(git tag -l 'v*' --sort=-v:refname | head -n1)
if [ -z "$latest" ]; then
version=$(jq -r '.version' manifest.json)
else
base="${latest#v}"
IFS='.' read -r major minor patch <<< "$base"
version="${major}.${minor}.$((patch + 1))"
fi
tag="v${version}"
git tag "$tag"
git push origin "refs/tags/${tag}"
set -euo pipefail
if [ "$EVENT_NAME" != "push" ] || [[ "$REF" != refs/tags/v* ]]; then
echo "::error::Releases run only from a pushed tag vX.Y.Z (got '${EVENT_NAME}' on '${REF}')."
exit 1
fi
echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
tag="${REF#refs/tags/}"
version="${tag#v}"
manifest_version="$(jq -er '.version' manifest.json)"
if [ "$manifest_version" != "$version" ]; then
echo "::error file=manifest.json::manifest.json version is '${manifest_version}', but the tag is ${tag}."
exit 1
fi
# The approved community catalog lists a release signed by this
# workflow only when its commit is on the default branch, so a tag
# on an unmerged branch is refused here, before anything is built.
git rev-parse --verify --quiet refs/remotes/origin/main >/dev/null || {
echo "::error::origin/main was not fetched."
exit 1
}
if ! git merge-base --is-ancestor "$GITHUB_SHA" refs/remotes/origin/main; then
echo "::error::Tag ${tag} (${GITHUB_SHA}) is not on main. Merge the release commit first, then tag it."
exit 1
fi
echo "version=${version}" >> "$GITHUB_OUTPUT"
echo "tag=${tag}" >> "$GITHUB_OUTPUT"

- name: Build release archives
run: make dist VERSION="${{ steps.version.outputs.version }}"
env:
VERSION: ${{ steps.version.outputs.version }}
run: make dist VERSION="$VERSION"

- name: Prepare release assets
id: assets
# The Silo plugin catalog and server install raw binaries named
# plugin-<os>-<arch> and verify them against checksums.txt. Publish
# those alongside the reproducible ZIP archives from `make dist`.
env:
VERSION: ${{ steps.version.outputs.version }}
run: |
set -euo pipefail
version="${{ steps.version.outputs.version }}"
mkdir -p release
cp dist/*.zip release/
cp dist/checksums.txt release/checksums.txt
for platform in linux-amd64 linux-arm64 darwin-arm64; do
archive="dist/silo-plugin-tailscale-${version}-${platform}.zip"
archive="dist/silo-plugin-tailscale-${VERSION}-${platform}.zip"
unzip -p "$archive" plugin > "release/plugin-${platform}"
chmod 0755 "release/plugin-${platform}"
(cd release && sha256sum "plugin-${platform}" >> checksums.txt)
done
cat release/checksums.txt
# checksums.txt lists every published file except itself and the
# bundle, and is the attestation's subject list. base64 keeps the
# multi-line file a single-line job output.
echo "checksums=$(base64 -w0 release/checksums.txt)" >> "$GITHUB_OUTPUT"
rm release/checksums.txt

- name: Upload release assets
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: release-assets
path: release/
if-no-files-found: error
retention-days: 5

# Holds the signing permission. It checks nothing out, downloads nothing,
# and runs no repository code: its subjects are the checksums the build job
# returned as an output.
attest:
name: Sign release assets
needs: build
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: read
id-token: write
attestations: write
outputs:
bundle: ${{ steps.bundle.outputs.bundle }}
steps:
- name: Write and check the subject list
env:
CHECKSUMS: ${{ needs.build.outputs.checksums }}
VERSION: ${{ needs.build.outputs.version }}
run: |
set -euo pipefail
file="${RUNNER_TEMP}/subjects.txt"
printf '%s' "$CHECKSUMS" | base64 -d > "$file"
if grep -Evx '[0-9a-f]{64} [A-Za-z0-9._-]+' "$file"; then
echo "::error::The build job's checksums have an unexpected line (above)."
exit 1
fi
expected=""
for platform in linux-amd64 linux-arm64 darwin-arm64; do
expected+="plugin-${platform}"$'\n'"silo-plugin-tailscale-${VERSION}-${platform}.zip"$'\n'
done
expected="$(printf '%s' "$expected" | sort)"
actual="$(awk '{print $2}' "$file" | sort)"
if [ "$expected" != "$actual" ]; then
echo "::error::The build job's checksums do not list exactly the release assets."
printf 'expected:\n%s\nactual:\n%s\n' "$expected" "$actual"
exit 1
fi
cat "$file"

- name: Attest build provenance
id: attest
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-checksums: ${{ runner.temp }}/subjects.txt

- name: Return the bundle
id: bundle
env:
BUNDLE_PATH: ${{ steps.attest.outputs.bundle-path }}
run: |
set -euo pipefail
jq -e '.mediaType' "$BUNDLE_PATH" >/dev/null
encoded="$(base64 -w0 "$BUNDLE_PATH")"
# Job outputs are capped at 1 MB per job, counted as UTF-16.
if [ "${#encoded}" -gt 400000 ]; then
echo "::error::The Sigstore bundle is too large to return as a job output (${#encoded} base64 characters)."
exit 1
fi
echo "bundle=${encoded}" >> "$GITHUB_OUTPUT"

release:
name: Publish release
needs: [build, attest]
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: write
steps:
- name: Download release assets
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: release-assets
path: release

- name: Check assets against the build job's checksums
env:
CHECKSUMS: ${{ needs.build.outputs.checksums }}
BUNDLE: ${{ needs.attest.outputs.bundle }}
run: |
set -euo pipefail
printf '%s' "$CHECKSUMS" | base64 -d > "${RUNNER_TEMP}/checksums.txt"
if grep -Evx '[0-9a-f]{64} [A-Za-z0-9._-]+' "${RUNNER_TEMP}/checksums.txt"; then
echo "::error::The build job's checksums have an unexpected line (above)."
exit 1
fi
expected="$(awk '{print $2}' "${RUNNER_TEMP}/checksums.txt" | sort)"
actual="$(find release -mindepth 1 -maxdepth 1 -printf '%f\n' | sort)"
if [ "$expected" != "$actual" ]; then
echo "::error::The downloaded artifact does not hold exactly the expected files."
printf 'expected:\n%s\nactual:\n%s\n' "$expected" "$actual"
exit 1
fi
cp "${RUNNER_TEMP}/checksums.txt" release/checksums.txt
(cd release && sha256sum --check --strict checksums.txt)
printf '%s' "$BUNDLE" | base64 -d > release/plugin.sigstore.json
jq -e '.mediaType' release/plugin.sigstore.json >/dev/null

# Checks the bundle the way Silo servers and the approved community
# catalog do, pinned to this workflow at the tag, so a release they
# would refuse is never published.
- name: Verify the bundle against this workflow's identity
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ needs.build.outputs.tag }}
run: |
set -euo pipefail
signer="https://github.com/Silo-Community/silo-plugin-tailscale/.github/workflows/release.yml@refs/tags/${TAG}"
for asset in $(awk '{print $2}' release/checksums.txt); do
gh attestation verify "release/${asset}" \
--bundle release/plugin.sigstore.json \
--repo Silo-Community/silo-plugin-tailscale \
--cert-identity "$signer" \
--cert-oidc-issuer https://token.actions.githubusercontent.com \
--source-ref "refs/tags/${TAG}" \
--deny-self-hosted-runners
done

- name: Create GitHub Release
uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
with:
tag_name: ${{ steps.version.outputs.tag }}
tag_name: ${{ needs.build.outputs.tag }}
files: |
release/plugin-linux-amd64
release/plugin-linux-arm64
release/plugin-darwin-arm64
release/*.zip
release/checksums.txt
release/plugin.sigstore.json
generate_release_notes: true

- name: Notify approved community catalog
# Separate from release so a failed dispatch can be re-run on its own.
dispatch:
name: Notify approved community catalog
needs: [build, release]
runs-on: ubuntu-24.04
timeout-minutes: 5
permissions: {}
steps:
- name: Send plugin_release_published
env:
DISPATCH_TOKEN: ${{ secrets.SILO_PLUGINS_DISPATCH_TOKEN }}
TAG: ${{ needs.build.outputs.tag }}
run: |
if [ -z "$DISPATCH_TOKEN" ]; then
echo "::warning::SILO_PLUGINS_DISPATCH_TOKEN is not set; catalog was not notified."
Expand All @@ -94,4 +272,4 @@ jobs:
-H "Authorization: Bearer ${DISPATCH_TOKEN}" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/repos/Silo-Community/silo-plugins/dispatches \
-d "$(printf '{"event_type":"plugin_release_published","client_payload":{"repo":"Silo-Community/silo-plugin-tailscale","tag":"%s"}}' "${{ steps.version.outputs.tag }}")"
-d "$(printf '{"event_type":"plugin_release_published","client_payload":{"repo":"Silo-Community/silo-plugin-tailscale","tag":"%s"}}' "$TAG")"
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Access Silo over HTTPS through your Tailscale network. No separate Tailscale dae

Requires a Silo server with network-access plugin support, with MagicDNS and HTTPS certificates enabled in Tailscale.

1. Install **Tailscale** from the plugin catalog in Silo (enable **Include approved community plugins** in plugin settings). To install manually instead, [build the plugin](docs/DEVELOPMENT.md#build-and-verify), extract the ZIP, and upload its `plugin` executable.
1. Install **Tailscale** from the plugin catalog in Silo (enable **Include approved community plugins** in plugin settings). To install manually instead, download `plugin-<os>-<arch>` from a [release](https://github.com/Silo-Community/silo-plugin-tailscale/releases) and [verify its signature](docs/DEVELOPMENT.md#releases), or [build the plugin](docs/DEVELOPMENT.md#build-and-verify) and extract the ZIP, then upload the `plugin` executable.
2. Enable the plugin, choose a hostname, and optionally enter a Tailscale auth key.
3. Save, then select **Connect** in **Settings > Network Access**. Sign in if prompted.
4. Open the reported HTTPS URL from a device running Tailscale. Silo apps with server discovery find a server whose hostname is `silo` on their own; for another hostname, type just that name. Check the hostname in the reported URL: if an older `silo` machine is still in your tailnet (for example after a reinstall), the new node is named `silo-1`, and apps probing `silo` reach the old one. Remove the stale machine in the Tailscale admin console. Turn **Discovery** off to keep port 80 closed.
Expand Down
26 changes: 26 additions & 0 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,32 @@ Real-tailnet/server playback QA has not been performed by the automated tests.
No Apple or Android API changes are needed: clients install Tailscale separately
and use the provider's reported server URL.

## Releases

Releases run only from a pushed tag. Bump `version` in `manifest.json` and the
`VERSION` default in the Makefile, merge that to `main`, then tag the merged
commit `vX.Y.Z` with the same version and push the tag. The release workflow
refuses a tag that does not equal `manifest.json` `version`, or whose commit
is not on `main`.

The workflow builds with `make dist`, then signs the raw binaries
`plugin-<os>-<arch>` and the ZIP archives with a GitHub artifact attestation.
Signing runs in a separate job that holds the signing token and runs no
repository code. The release carries the Sigstore bundle as
`plugin.sigstore.json` beside the binaries, archives, and `checksums.txt`, and is
published only after every file verifies against that bundle. Silo servers check
the signature before installing when the approved community catalog lists the
bundle.

To verify a download yourself:

```sh
gh attestation verify plugin-linux-amd64 --repo Silo-Community/silo-plugin-tailscale --source-ref refs/tags/vX.Y.Z --deny-self-hosted-runners
```

Add `--bundle plugin.sigstore.json` to verify against the bundle from the release
instead of the copy GitHub stores.

## HTTPS and tags

The plugin automatically serves Silo over HTTPS using an embedded `tsnet` node. It does not require or configure a separate host `tailscaled` process or `tailscale serve` command. Enable MagicDNS and HTTPS certificates in the tailnet before connecting. A node can join the tailnet before its HTTPS certificate is ready. The plugin reports that distinction and retries certificate issuance with backoff from 15 seconds to five minutes, honoring a longer certificate-authority retry delay. It advertises a usable HTTPS origin only after certificate acquisition and listener setup succeed.
Expand Down