git-attest 1.2.0

Verify a signed attestation that a test suite already passed on this exact tree, so CI can skip it
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# Verify a signed attestation, so a CI job can skip work that already ran.
#
# Composite, and deliberately WITHOUT a download step. The contract here is
# fail-open — every failure means "run the tests" — so a step that fetched a
# binary would turn a flaky network into a silently disabled gate. Everything
# below needs only `git` and `ssh-keygen`, which every runner already has.
#
# Forgejo uses the same file: `uses: https://github.com/fredericrous/attest@v1`.
# Forgejo Actions sets the same GITHUB_* variables this relies on.
name: attest
description: Skip a CI job when a signed note proves its gate already passed on this exact tree
branding:
  icon: check-circle
  color: green

inputs:
  signers:
    description: >-
      Path to an allowed_signers file, relative to the repository root.
      Default: .forgejo/allowed_signers, then .github/allowed_signers.
    required: false
    default: ""
  principal:
    description: >-
      Accept only an attestation signed by this identity. Default: whoever the
      signature says, provided that key is in the signers file — so a file
      naming a whole team just works, and there is nothing to keep in sync.
    required: false
    default: ""
  platform:
    description: >-
      Only accept an attestation minted on this platform, as <arch>-<os>
      (e.g. x86_64-linux). Default: the runner this step is on, so a matrix leg
      skips only work that really ran on its own platform. An OS alone
      (`linux`) accepts any architecture. Pass `any` to state that the whole
      suite's result does not depend on where it ran.
    required: false
    default: ""
  anywhere:
    description: >-
      Gate names, space-separated, whose result cannot depend on where they
      ran: formatting, shell lint, secret scanning, dependency audit. A
      verified attestation from ANY platform covers these, so a laptop's note
      skips them on every leg of a matrix. This is your committed statement
      about those checks, made once, here. Never list a check that compiles or
      executes the product — tests, clippy, a typecheck under cfg, a build —
      whatever its name says.
    required: false
    default: ""

outputs:
  gates:
    description: >-
      The covered gate names as a JSON array — `[]` when nothing is covered.
      USE THIS ONE, in an `if:` expression:
      "not contains(fromJSON(steps.attest.outputs.gates), 'your-gate')".
      `contains` over an array matches ELEMENTS; over the `covered` string
      below it matches substrings, so an unrelated gate named
      `pre-push-cargo-test-slow` would satisfy a check for
      `pre-push-cargo-test` and skip the real suite. See the README for the
      expression written out — it cannot be spelled here, because GitHub
      EVALUATES a dollar-brace expression inside this description rather than
      displaying it, and the action then fails to load.
    value: ${{ steps.verify.outputs.gates }}
  covered:
    description: >-
      The same names, space-separated. Kept only so workflows written against
      the older inline templates keep working; prefer `gates`.
    value: ${{ steps.verify.outputs.covered }}

runs:
  using: composite
  steps:
    - id: verify
      shell: bash
      env:
        ATTEST_SIGNERS: ${{ inputs.signers }}
        ATTEST_PRINCIPAL: ${{ inputs.principal }}
        ATTEST_PLATFORM: ${{ inputs.platform }}
        ATTEST_ANYWHERE: ${{ inputs.anywhere }}
      run: |
        set -u
        # Positional parameters rather than a bash array: macOS runners can
        # still put bash 3.2 first on PATH, where an empty array under `set -u`
        # is an error. `"$@"` is exempt from nounset in every POSIX shell.
        set --
        if [ -n "$ATTEST_SIGNERS" ];   then set -- "$@" --signers   "$ATTEST_SIGNERS";   fi
        if [ -n "$ATTEST_PRINCIPAL" ]; then set -- "$@" --principal "$ATTEST_PRINCIPAL"; fi
        if [ -n "$ATTEST_PLATFORM" ];  then set -- "$@" --platform  "$ATTEST_PLATFORM";  fi
        if [ -n "$ATTEST_ANYWHERE" ];  then set -- "$@" --anywhere  "$ATTEST_ANYWHERE";  fi
        # Reasons go to stderr and land in the job log. When an expected skip
        # does not happen, that log says which of tree, platform, signature or
        # signers was the reason — the alternative is a silent non-answer.
        bash "$GITHUB_ACTION_PATH/verify.sh" --github-output "$@" >> "$GITHUB_OUTPUT"