GitHub Action for Install gibo

Documentation

• Release process

Usage

steps:
- uses: actions/checkout@v4
- uses: gitignore-in/install-gibo@16003b5d1278dde15995459d9b4a01b146ec7798  # v0.1.0+

Pinning: Pin to a specific commit SHA for reproducible, supply-chain-safe usage. @main is a mutable ref and may change without notice. Check the releases page for the latest tagged release, or use a commit SHA pointing to the tip of main.

Prerequisites

The action runs as a composite shell: bash step. The runner must provide:

Tool	Required when	Notes
bash	always	Used as the step shell
curl	always	Downloads gibo release archive and checksums file from github.com
sha256sum	always	Verifies archive integrity; must be GNU coreutils sha256sum (not macOS shasum)
tar	Linux / macOS	Extracts the .tar.gz archive
unzip	Windows	Extracts the .zip archive
git	update: 'true' or boilerplates-ref set	gibo update and boilerplates-ref checkout both invoke git

Network: the action contacts github.com at two points — to download the gibo release archive from simonwhitaker/gibo and (when update: 'true') to clone or pull simonwhitaker/gitignore-boilerplates. Both require outbound HTTPS and git transport to github.com. Set update: 'false' and restore the boilerplates database from actions/cache to eliminate the second network call.

Self-hosted runners: gibo update writes $HOME/.gitignore-boilerplates/. On self-hosted runners the $HOME directory persists across jobs; see Parallel jobs on self-hosted runners for the lock-based serialization this action provides and the recommended caching strategy.

GitHub-hosted runners satisfy all of the above requirements out of the box.

Inputs

Input	Default	Description
version	(action pin)	gibo release tag (e.g. v3.0.22). Leave empty to use the version pinned by the action.
update	'true'	Run gibo update after install. Set to 'false' to skip the unconditional database refresh, e.g. when caching the boilerplates database externally.
boilerplates-ref	''	Optional git ref to check out in the boilerplates database. With update: 'true', the action updates before checkout; with update: 'false', it checks out from the database already present on the runner. Use a commit SHA to make later gibo dump output reproducible.

Outputs

Output	Description
version	gibo release tag that was installed.
bin-dir	Directory containing the gibo executable (already on PATH).
boilerplates-dir	Directory where gibo stores its boilerplates database, as reported by gibo root.
boilerplates-commit	Resolved commit of the boilerplates database, when present.

Pinning the boilerplates database

By default, gibo update follows the current upstream boilerplates database HEAD. Pin boilerplates-ref to a commit SHA when downstream steps need byte-reproducible gibo dump output. The checkout runs after any requested update, or from the database already present on the runner when update is 'false':

steps:
- uses: actions/checkout@v4
- id: gibo
  uses: gitignore-in/install-gibo@16003b5d1278dde15995459d9b4a01b146ec7798  # v0.1.0+
  with:
    boilerplates-ref: 0123456789abcdef0123456789abcdef01234567

- run: |
    echo "database commit: ${{ steps.gibo.outputs.boilerplates-commit }}"
    gibo dump Python > .gitignore
  shell: bash

When update is 'true' and boilerplates-ref is empty, the action emits a GitHub Actions notice that includes the resolved boilerplates-commit. The notice is informational: the action succeeded, but later gibo dump output can change when the upstream boilerplates database changes. Set boilerplates-ref to the reported commit, or any other intended boilerplates commit, to make the run reproducible and suppress the notice.

Caching the boilerplates database

gibo update clones / pulls the upstream boilerplates database on every run. Pair the action with actions/cache and a cache-populator action step to keep that database across runs:

steps:
- uses: actions/checkout@v4

- id: gibo
  uses: gitignore-in/install-gibo@16003b5d1278dde15995459d9b4a01b146ec7798  # v0.1.0+
  with:
    update: 'false'

- id: gibo-cache
  uses: actions/cache@v4
  with:
    path: ${{ steps.gibo.outputs.boilerplates-dir }}
    key: gibo-boilerplates-${{ steps.gibo.outputs.version }}-${{ github.run_id }}
    restore-keys: |
      gibo-boilerplates-${{ steps.gibo.outputs.version }}-

- if: steps.gibo-cache.outputs.cache-hit != 'true'
  uses: gitignore-in/install-gibo@16003b5d1278dde15995459d9b4a01b146ec7798  # v0.1.0+

Keep the cache miss update inside this action rather than running gibo update in a separate shell step. The action serializes writes to the shared boilerplates database on self-hosted runners; an external gibo update does not use that lock.

Concurrency notes

Multiple calls in the same job

Calling this action twice in the same job (e.g., to install two different versions side-by-side) is supported. Each version is installed into its own directory ($RUNNER_TEMP/gibo/<version>/bin), so installations do not overwrite each other. Both versions are added to PATH; the first entry wins for unqualified gibo calls. Use outputs.bin-dir from each step to invoke a specific version explicitly.

Parallel jobs on self-hosted runners

When multiple jobs run concurrently on a self-hosted runner sharing the same user account, they share $HOME/.gitignore-boilerplates. This action serializes access to the shared boilerplates database with an atomic lock directory placed next to that database. The lock protects against both concurrent writers (update: 'true' or boilerplates-ref) and the case where a writer is mid-checkout while a reader job would proceed to gibo dump. Any job that finds an existing boilerplates database also acquires the lock so that gibo dump only runs against a fully consistent snapshot. If another process holds the lock for too long, the action exits with a timeout instead of running an unsafe concurrent operation.

Recommended mitigation for self-hosted runners:

• Cache the boilerplates database and set update: 'false' (see Caching above). On a cache miss, call this action again as the cache populator so the update uses the action's lock. Subsequent jobs restore from cache without writing to the shared directory.
• Or use GitHub-hosted runners, where each job gets an isolated VM.

Security model

The action downloads release artifacts from upstream simonwhitaker/gibo, which does not publish cosign/SLSA signatures. To avoid a self-referential trust chain (where both the archive and its checksums file come from the same release URL and can be swapped together), the action pins the SHA256 of upstream's checksums.txt / checksums.windows.txt for the default version directly in action.yml. The trust anchor is therefore this repository's git history (commit review, branch protection) rather than the upstream release URL.

The pinned version is intentionally not managed by Renovate. A version-only automation PR would leave the checksum anchors stale, causing either a failed anchor check or a tempting bypass back to self-referential trust. Update the default version and both checksum anchors together in the same reviewed commit.

What this defends against, for the default version:

• Upstream tag rewrite or release artifact replacement after publish
• TLS / CDN MITM that rewrites both archive and checksums in flight

What it does not defend against:

• Upstream compromise that occurs before the pinned anchor was committed to this repository
• A future version bump (with matching anchor update) merged into this repository under a compromised review process

When you set inputs.version to anything other than the action's pinned default, the action falls back to the original self-referential verification (both files trusted because they were fetched from the same release URL), and prints a warning on stderr. Pinning a non-default version does not disable archive verification — sha256sum --check still runs against the downloaded checksums file — but the anchor step is skipped.

License

MIT