A developer builds a genuinely useful GitHub Action, writes the action.yml file, tags a release, and tries to publish it to the Marketplace. The publish fails. Not because of a bug in the code. Because the name they chose already exists, or matches an existing GitHub username, or collides with a reserved category name. GitHub's naming rules for Marketplace actions are stricter than most developers expect, and almost nobody checks them before writing the action itself. The rules aren't hidden. They sit in GitHub's own documentation the whole time, plainly written out. Almost nobody reads them until a rejected publish forces the question, usually right when a release was supposed to ship.
The rules GitHub actually enforces (not suggestions, hard blocks)
GitHub states these rules directly in its own documentation. To publish an action to the GitHub Marketplace, the name in the action's metadata file must be unique across the entire Marketplace. The name cannot match an existing GitHub username or organization name unless that user or organization owns the action. The name cannot match an existing Marketplace category. And GitHub reserves the names of its own features entirely, meaning an action cannot be named github unless GitHub itself publishes it.
These checks run at publish time. They are not suggestions sitting in a style guide somewhere, and they are not soft warnings you can dismiss and move past anyway. An action that fails any of these checks simply cannot be published until it's renamed, full stop. This is meaningfully stricter than naming a plain repository, where the only real constraint is uniqueness within your own account. A Marketplace action name has to clear a bar set by every other publisher on the entire platform, not just your own history of repo names, and that bar doesn't move for anyone.
A real, unresolved debate among GitHub's own users
A developer asked directly in GitHub's own community discussions whether there is an official naming convention for GitHub Actions, specifically about input names, pointing out the inconsistency between my_input and my-input across actions maintained by GitHub's own team. Other developers replied confirming they had run into the same confusion themselves, some admitting they had switched patterns mid-project more than once. One described a personal preference for underscores while acknowledging that most upstream actions use hyphens instead. As of now, GitHub has not published a definitive answer to settle it either way, and the thread has sat open for years without one.
This means a genuinely careful developer, someone who actually wants to follow official convention instead of guessing, cannot find one to follow. The practical answer isn't that there's a right way GitHub prescribes. It's that you pick one pattern and apply it with total consistency across your own repository, because half of GitHub's own actions do not agree with the other half. This same discipline, picking one pattern and never mixing it, applies to naming conventions well beyond just GitHub Actions, including the same consistency principle covered in NameKit's repo naming guide.
Three separate names inside a single GitHub Action
A single GitHub Action actually carries three separate names, and they can drift out of sync with each other without anyone noticing until a contributor gets confused. Only one of them is checked against the Marketplace's uniqueness rule directly. The other two are just as easy to get wrong, and getting them wrong causes a quieter, longer-running kind of friction than a failed publish, the kind that shows up months later in a confused issue thread instead of at publish time.
The action name in action.yml
This is the name field in your metadata file, and it's what the Marketplace uniqueness rule applies to directly. It should be lowercase, hyphenated, and describe the action's function plainly, similar to a well chosen npm package name. A GitHub Action name lives in a YAML file the same way a CLI command lives in a terminal, and the same typing ergonomics apply. Both reward the same lowercase, lowercase discipline that keeps a command fast to type and a name easy to reference later. Since this name has to survive a uniqueness check against every other published action on the platform, checking availability early saves a rename later.
The repository name
The repository housing the action can technically differ from the action name in the metadata file, but keeping them identical or very close avoids the same confusion covered in npm package naming, where a mismatch between the package name and the repo name creates permanent friction for anyone trying to reference or find the project later. That's the same mismatch problem covered in NameKit's npm naming guide, just applied to a different registry with a different set of rules. A contributor searching for your action by its Marketplace name should land on a matching repository without guesswork, not one that requires an explanation buried in the README.
The input and output parameter names
This is where the unresolved hyphen versus underscore debate actually lives. GitHub Actions expressions and YAML syntax both technically support either pattern for parameter names, so the choice is a matter of internal consistency, not correctness. Pick one pattern for all inputs and outputs across your action and never mix them within a single action.yml file. A workflow author calling your action shouldn't have to remember that three inputs use underscores while two others use hyphens instead. Mixing patterns inside one file is worse than choosing the less common pattern consistently, since a consistent file stays predictable even when it disagrees with someone else's convention entirely.
What to check before you write the action.yml file
Run through these five checks before the metadata file exists at all, not after a failed publish attempt forces the question. Each one maps directly to a rule GitHub actually enforces or a debate it has never resolved, so skipping one just moves the problem later, closer to a release date.
- 01Search the GitHub Marketplace directly for your candidate action name and close variants, since the uniqueness check happens at publish time, not at any earlier warning stage.
- 02Check whether the name matches any existing GitHub username or organization, since the Marketplace blocks this unless you own that account.
- 03Check the current list of GitHub Marketplace categories and confirm your candidate name does not match one of them exactly.
- 04Decide your input and output parameter naming pattern, hyphens or underscores, before writing the first parameter, and write it down somewhere so future contributors follow the same pattern.
- 05Confirm the repository name and the action name in the metadata file are identical or close enough that referencing one clearly identifies the other.
Name it once, publish it clean
GitHub Marketplace enforces real, strict naming rules at publish time, and the parameter naming convention is genuinely unresolved even within GitHub's own ecosystem. Consistency inside your own action matters more than chasing an official answer that doesn't exist, because that answer simply isn't coming. NameKit's GitHub Repository Name Generator is a solid starting point for generating a candidate name before checking it against the Marketplace yourself.
Frequently asked questions
Why did my GitHub Action fail to publish to the Marketplace?
The most common reason is a name conflict. GitHub requires the action name in your metadata file to be unique across the entire Marketplace, and it cannot match an existing username, organization, or Marketplace category. Check the Marketplace directly for your exact name before troubleshooting anything else in the workflow.
Should I use hyphens or underscores for GitHub Action input names?
There is no official GitHub standard. A public discussion among GitHub's own community confirms the inconsistency exists even within actions maintained by GitHub itself. Pick one pattern and apply it consistently across your own action rather than searching for an authoritative answer that does not currently exist anywhere.
Can my action name match my GitHub username?
Yes, but only if you are the owner of that username or organization. GitHub Marketplace blocks any action name that matches an existing username or organization unless the action is being published by that same account, no exceptions beyond that.
Does the action name need to match the repository name?
Not strictly, but keeping them identical avoids the same confusion that comes from mismatched npm package and repository names. Anyone referencing your action by its Marketplace name should be able to find the matching repository without guesswork or an extra search.
What happens if I delete a published GitHub Action?
The Marketplace listing is deleted along with the repository, and the unique name identifier becomes available again for anyone else to use. This means abandoned action names can eventually be reclaimed, but there is no guarantee of when or by whom it happens.