GitHub Actions Tutorial — Publishing to Marketplace

Publishing to Marketplace

The GitHub Actions Marketplace is where you share your custom actions with the community. Any public repository with an action.yml file can be published.

---

Prerequisites

Before publishing:

• Repository is public
• action.yml exists in the repository root
• action.yml has name, description, and branding
• README.md documents usage, inputs, and outputs
• Action is tested and working

---

Publishing Steps

1. Create a Release

Go to your action’s repository → Releases → Create a new release.

Tag: v1.0.0
Title: v1.0.0
Description: Initial release

☑ Publish this Action to the GitHub Marketplace

Check the “Publish this Action to the GitHub Marketplace” checkbox. GitHub validates your action.yml before publishing.

2. Create a Major Version Tag

# Create the release tag
git tag v1.0.0
git push origin v1.0.0

# Create/update the major version tag
git tag -fa v1 v1.0.0
git push origin v1 --force

Users reference @v1 for the latest stable minor/patch version.

3. Update the Major Tag on New Releases

git tag v1.1.0
git push origin v1.1.0

# Move v1 tag forward
git tag -fa v1 v1.1.0
git push origin v1 --force

---

Versioning Best Practices

Version	When to Bump	Example Change
v1.0.0 → v1.0.1	Bug fix	Fix input validation
v1.0.0 → v1.1.0	New feature	Add optional input
v1.0.0 → v2.0.0	Breaking change	Rename input, change behavior

Always maintain major version tags (v1, v2) so users get patches automatically.

---

README Template for Actions

# My Action Name

Short description of what the action does.

## Usage

```yaml
- uses: my-org/my-action@v1
  with:
    input-name: 'value'
```

## Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `input-name` | Yes | — | What it does |

## Outputs

| Output | Description |
|--------|-------------|
| `result` | What it returns |

## Examples

### Basic

```yaml
- uses: my-org/my-action@v1
  with:
    input-name: 'basic-value'
```

## License

MIT

---

Automated Release Workflow

Automate publishing with a workflow:

name: Release Action

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Build (if needed)
        run: npm ci && npm run build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

      - name: Update major version tag
        run: |
          VERSION=${GITHUB_REF#refs/tags/}
          MAJOR=$(echo "$VERSION" | cut -d. -f1)
          git tag -fa "$MAJOR" "$VERSION"
          git push origin "$MAJOR" --force

Push a tag like v1.2.0 and this workflow creates the release and updates the v1 tag automatically.

---

Common Mistakes

Mistake	Fix
Marketplace checkbox not showing	Ensure action.yml has name, description, branding
Name already taken	Action names must be unique on Marketplace
Users on @v1 don’t get updates	Force-push the v1 tag to new releases
Breaking change affects all users	Bump to v2 for breaking changes

---

Quick Reference

Step	Command/Action
Tag release	git tag v1.0.0 && git push origin v1.0.0
Major tag	git tag -fa v1 v1.0.0 && git push origin v1 --force
Marketplace	Check “Publish” checkbox in GitHub Releases UI
Users reference	uses: my-org/my-action@v1

---

← Previous: Action Metadata

Next: Practice Exercises →