What's changed: New GH-200 Chapter 3 (creating custom actions = JavaScript/Docker/composite types and selection, action.yml metadata, inputs/outputs, workflow commands, troubleshooting; distribution & maintenance = public/private/Marketplace, Marketplace publishing, tags/releases/moving major tag/SHA pinning, avoiding @main, immutable actions)
3.2Distributing, Publishing, and Versioning Actions
Understand action distribution models (public, private, Marketplace), publishing to the GitHub Marketplace, and versioning/release strategies using tags, releases, a major-version tag, and commit-SHA pinning, plus the concept of immutable actions on hosted runners.
Once you build an action, choose its distribution model—use within the same repo, share via a private repo in the org, make a public repo so anyone can reference it via uses:, or publish to the GitHub Marketplace for discoverability. Consumers pin a version via the @ref in uses: owner/repo@ref, so how you cut versions strongly affects maintainability and safety.
3.2.1Publishing to the Marketplace
To publish to the Marketplace, place the action in a public repo, include action.yml at the root (name, description, branding), and create a release in the repo. During publishing you pick Marketplace categories and accept the terms. The action name must be unique within the Marketplace. After publishing, users can find it in the Marketplace and add it to workflows via uses:.
3.2.2Versioning and release strategies
Consumers usually reference a major-version tag (like @v4). Providers move the major tag (v4) to the latest commit with each patch/minor release so consumers on @v4 keep getting fixes (semantic versioning + a moving major tag is the norm). Conversely, consumers wanting maximum security pin to a commit SHA (@a1b2c3... full SHA)—since tags are reassignable, an immutable SHA reliably prevents tampering or surprise changes. The safe default is to avoid floating refs like @main.
| Reference | Example | Characteristic |
|---|---|---|
| Major tag | @v4 | Auto-receive fixes; convenient (provider moves it) |
| Full SHA | @a1b2c3d… | Tamper-proof; most secure (immutable) |
| Floating ref | @main | Unpredictable; generally avoid |
3.2.3Immutable actions
GitHub is advancing immutable actions on hosted runners. The idea is to make a released action version unchangeable so a version a consumer referenced cannot later be swapped (distribution backed by a package registry). This lowers the "tag reassignment changes contents" risk and, with SHA pinning, strengthens supply-chain safety. Expect this in the context of "version-reference stability and tamper resistance."
Common: (1) Distribution = same-repo / private (org) / public / Marketplace. (2) Marketplace publish = public repo + action.yml (branding) + create a release; unique name. (3) Consumers get fixes via @major tag (v4); providers move the major tag to latest. (4) Maximum security = pin to commit SHA; avoid @main. (5) Immutable actions = unchangeable versions for supply-chain safety.
Watch out: (1) @main can change unexpectedly—use a major tag or SHA in production. (2) Major tags are reassignable—for maximum tamper resistance, pin to a full SHA. (3) Marketplace publishing requires creating a release (a tag alone is insufficient). (4) Don’t confuse private distribution with public/Marketplace—internal-only means private + access settings.
3.2.4Section summary
- Distribution = same-repo/private(org)/public/Marketplace; reference via uses: owner/repo@ref
- Marketplace publish = public repo + action.yml (branding) + create a release; unique name
- Use @major tag (v4) to get fixes (provider moves it); max safety is SHA pinning; avoid @main
- Immutable actions prevent version rewrites and strengthen supply-chain safety
Sign in to track progress — Log in.
Quick check
(just a quick review)Q1. Using a third-party action in a production workflow, you want maximum protection against tampering and surprise changes. What is the safest reference?
Q2. You want consumers on @v3 to automatically receive your action’s patch fixes. What is the correct provider practice?
Q3. Which is a correct requirement to publish your action to the GitHub Marketplace?
Q4. You want an action used only by internal teams to be usable from other repos in the org without making it public. Which distribution fits?
Q5. What is the main risk of referencing an action with @main?
Q6. What does the concept of "immutable actions" most improve?