Launch a GitHub Action for Free: Marketplace Rules, Version Tags and Trust

No review, no shield: what that changes

GitHub’s Marketplace publishing page says actions are published immediately and are not reviewed by GitHub as long as they meet its requirements (read 13 November 2026). Compared with an extension store, that is a gift: nothing to wait for, no rejection to recover from. It is also a warning. Because nobody vets the listing, the reader has to, and the reader is about to hand your code the keys to their repository.

So the launch is less about getting listed and more about making a cautious maintainer comfortable. Everything below is organised around that.

What does the Marketplace listing require?

• A public repository that holds only the metadata file, the code and the files the action needs. A single repository per action lets you tag, release and package it as one unit.
• One metadata file, `action.yml` or `action.yaml`, at the root. Other action files in subfolders will not be listed automatically.
• A unique name. It cannot match an existing Marketplace action or Marketplace category, and it cannot match a user or organisation on GitHub unless that owner publishes the action. GitHub also reserves the names of its own features.
• The Marketplace Developer Agreement, accepted by the account that owns the repository. If the publish checkbox is greyed out, this is why, and an organisation owner has to accept it.

You publish by drafting a release on the repository’s page and selecting the option to publish the action to the Marketplace, then choosing a primary category. In action.yml, the optional branding key sets a colour and an icon from the Feather set for the badge shown beside the name. GitHub also hands a verified creator badge to partner organisations it has verified, so do not plan around having one.

Write the README as a workflow someone can paste

People do not read an action’s page; they scan for the snippet. Put a complete, minimal workflow at the top: the trigger, the checkout step if one is needed, your action with a version after the @, and every input it needs, with comments saying which are required. Under it, a table of inputs and outputs, then a second example for the second most common use.

## Check image sizes

Fails a pull request when an image grows past the limit you set.

```yaml
on: pull_request
permissions:
  contents: read
jobs:
  images:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: your-name/check-image-sizes@v1
        with:
          max-kb: 300
```

| Input | Required | Default | What it does |
| --- | --- | --- | --- |
| max-kb | no | 500 | Largest allowed file, in kilobytes |

Notice the permissions block. Showing the least privilege your action needs is a trust signal in itself, and it teaches users to grant no more.

Which version-tag strategy should you use?

GitHub’s documentation on releasing actions describes two approaches. If you enable immutable releases on the repository, you create a GitHub release with a specific tag such as v1.0.0, which can never be altered. If you want to move tags later, you do not create a release and instead keep tags pointing at the latest compatible version: a major tag such as v1 for the line, with minor and patch tags beneath. A moving major tag is convenient for users who want fixes automatically, and it is a convention many actions follow.

Support both kinds of reader. Publish immutable release tags for every version, and say in the README which tag follows the latest compatible release. Security-minded users will pin to a full commit or use a lockfile for workflow dependencies, which GitHub’s own security guidance recommends over trusting a moving tag, so give them clear, stable tags to point at.

What does a cautious maintainer check before adding your action?

GitHub’s secure-use guidance is blunt: a compromised action in a workflow could reach all secrets configured on the repository, and may be able to use the GITHUB_TOKEN to write to it. Anyone reading your page knows that. Answer the worry before it is voiced.

• Few dependencies, and a lockfile, so the code can be read in one sitting.
• No network calls the README does not mention, and none that carry secrets or repository contents to a service you run.
• A stated minimum permission set in the examples.
• Tests that run on your own repository with your own action, with a build badge on the page to prove it.
• A security contact in the repository, so a problem has somewhere to go.

An action that does one small job in readable code earns more trust than a clever one. If the job genuinely needs a hosted service, say so in the first paragraph.

Ten days from idea to listing

1. Days 1 to 3: write the action and use it on your own repository for a real job.
2. Day 4: add the README with the paste-ready workflow, then run it from a second, empty repository to confirm the snippet works.
3. Days 5 and 6: add tests, set permissions to the minimum, add branding and a licence.
4. Day 7: draft the release, tag v1.0.0, move v1 to it, and publish to the Marketplace.
5. Days 8 to 10: ask two maintainers who run the tool you wrap to try it on a real project, and fix what they hit.

Where does an action get found?

Through search on the Marketplace, through workflow files other people write, and through the communities of the tool you wrap. Write the first line of the README in the words a person would type when they have the problem, and post in the community of the tool the action supports, with a before-and-after workflow. A Show HN post can fit if the action does something interesting that people can try on their own repository.

A public page that is not on GitHub adds a second route in. You can launch the action free on this board, with one verified email, no queue and a followed link to the Marketplace page. The developer tool ideas show which pipeline problems builders are naming, the places to launch GitHub Actions list more venues, and the developer tool playbook is the general version of this page.