# Publishing Githical

Githical's unsigned release and package-manager pipeline can run without paid
Apple, Microsoft, Linux distribution, or package-manager accounts. Because the
repository is public, standard Linux, macOS, and Windows hosted runners and
GitHub artifact attestations are available without Actions minute charges.

## Release Pipeline

Pushing a `v*` tag runs `.github/workflows/release.yml`:

1. Run formatting checks and the Go test suite.
2. Run `scripts/build-dist.sh` to build the six portable archives and an
   immutable source archive.
3. Install pinned nFPM `v2.47.0` and run `scripts/package-linux.sh` to create
   `.deb` and `.rpm` packages for AMD64 and ARM64. These packages depend on
   `git`.
4. Run `scripts/generate-package-metadata.sh` to create a source-based Homebrew
   formula and WinGet portable-package manifests.
5. Validate the WinGet manifests with the current `winget validate` command.
6. Execute the Linux, macOS, and Windows release binaries on matching AMD64 and
   ARM64 GitHub-hosted runners.
7. Attest every release archive, native package, and `checksums.txt` with
   GitHub's OIDC-backed artifact attestation service.
8. Create the GitHub Release only after every smoke test and manifest validation
   succeeds.
9. Publish the Homebrew formula and submit the WinGet update when their
   optional repository settings are enabled.

The Homebrew formula and WinGet manifests are also included in
`githical_<version>_package-managers.tar.gz`, so they can be inspected or
submitted manually.

## Homebrew Tap

Homebrew taps are free Git repositories. The tap uses a write-enabled SSH deploy
key so the release workflow does not need a personal access token:

1. Create the public repository `essenciary/homebrew-tap`.
2. Add the deploy key's public half to that repository with write access.
3. Add its private half to this repository as the Actions secret
   `HOMEBREW_TAP_SSH_KEY`.
4. Add the Actions variable `HOMEBREW_TAP_REPOSITORY` with the value
   `essenciary/homebrew-tap`.

On every later tag, the `publish-homebrew` job writes the generated formula to
`Formula/githical.rb`. Users can then install with:

```sh
brew install essenciary/tap/githical
```

The formula builds from the checksummed source release and lets Homebrew install
the required `git` dependency.

## WinGet

The first version is submitted as a normal pull request. This has no fee:

1. Download `githical_<version>_package-managers.tar.gz` from the first release.
2. Copy its three WinGet files into
   `manifests/e/Essenciary/Githical/<version>/` in a fork of
   `microsoft/winget-pkgs`.
3. Validate the directory with `winget validate`, test the local manifest, and
   open the upstream pull request.
4. Complete Microsoft's contributor license agreement when prompted.

After the first manifest is accepted:

1. Create a classic GitHub personal access token with the `public_repo` scope.
   WinGetCreate does not currently support fine-grained tokens.
2. Add it as the Actions secret `WINGET_CREATE_GITHUB_TOKEN`.
3. Add the Actions variable `WINGET_PUBLISH` with the value `true`.

Later tags run the gated `publish-winget` job. WinGetCreate updates
`Essenciary.Githical` with both Windows release URLs and opens the upstream pull
request. The token is read from the `WINGET_CREATE_GITHUB_TOKEN` environment
variable rather than placed on the command line. The manifest declares
`Git.Git` as a package dependency, and users can install with:

```powershell
winget install --id Essenciary.Githical --exact
```

## Linux Packages

The `.deb` and `.rpm` files are normal GitHub Release assets and require no
distribution account. They provide dependency-aware installation but not an
APT or DNF update repository. A signed repository can be added later if demand
justifies hosting and key-management work.

## Attestation Verification

Checksums detect corruption. GitHub attestations additionally bind each artifact
to this repository, commit, and release workflow. Verify an artifact with:

```sh
gh attestation verify <downloaded-file> --repo essenciary/githical
```

Attestations do not replace Apple notarization or Windows Authenticode signing;
those are separate paid publisher-identity systems.