Automating software development workflows is no longer a luxury but a necessity in modern DevOps pipelines. GitHub Actions serves as the backbone for this automation, enabling developers to execute tests, deploy code, publish packages, and manage complex release cycles directly within the repository ecosystem. While the GitHub Marketplace hosts a vast library of community-created actions, specialized requirements often necessitate the creation of custom tools. Publishing these custom actions to the marketplace allows teams to share reusable logic, enforce consistency across projects, and contribute to the broader developer community. This process involves careful configuration of metadata, rigorous version control strategies, and the integration of specific release automation tools to ensure stability and discoverability.
Configuring Action Metadata and Branding
The foundation of a publishable GitHub Action lies in its definition file, typically named action.yml or action.yaml. This file is not merely a technical descriptor but also the primary interface for how the action appears in the GitHub ecosystem. Proper configuration of this file triggers the visibility features on the repository page. When an action.yml file is correctly set up in the root of a repository, GitHub detects its presence and displays a prominent banner at the top of the repository page. This banner serves as the gateway to the publishing workflow, offering options to "Draft a release" or manage the action's visibility.
To make an action stand out in the GitHub Marketplace, visual branding is essential. The action.yml file supports a branding section that allows developers to define an icon and a color theme. This metadata ensures that the action has a professional appearance when discovered by other users. The configuration requires specific keys: icon and color. The icon value must correspond to one of the FontAwesome icons available through GitHub’s icon library, such as activity, star, or check. The color value is a hex code or a named color that defines the action's visual theme in the marketplace listing.
yaml
branding:
icon: 'activity'
color: 'green'
This configuration adds a distinct visual identity to the action, making it easily recognizable in workflow editors and marketplace searches. The availability of specific icons is documented in GitHub’s resources, allowing developers to choose symbols that semantically match the action’s function, such as a rocket for deployment actions or a shield for security checks.
The Publishing Workflow and Release Management
Publishing an action is not a simple commit operation; it involves a structured release process that ensures users can reference stable versions. Once the repository is configured with the necessary metadata and the action.yml file is in place, the developer initiates the publication process by clicking the "Draft a release" button on the repository banner. This action directs the user to a release creation page where critical information must be filled out.
A well-documented README.md file is a prerequisite for a successful publication. The release page often highlights missing or incomplete information, prompting the developer to provide comprehensive documentation, usage examples, and input/output descriptions. This documentation becomes the primary resource for other developers attempting to integrate the action into their workflows.
During the release configuration, the developer must make a strategic decision regarding the action's distribution scope. There are two distinct paths:
- Publish the action only to the repository, making it available for use by anyone who knows the repository URL but not visible in the general Marketplace search.
- Publish the action to the GitHub Marketplace, making it discoverable to the entire community through search and category browsing.
Once the metadata, documentation, and scope are finalized, the developer clicks the green "Publish release" button. This action officially makes the action available for consumption. Other developers can then reference the action in their own workflows by specifying the repository name, the owner, and a specific version tag or branch reference.
yaml
jobs:
label:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@main
- uses: Balastrong/gh-aciton-test@latest
with:
gh-token: ${{ secrets.GITHUB_TOKEN }}
label: needs-review
In the example above, a workflow named "Label PR" triggers on pull request opening or reopening events. It utilizes a custom action Balastrong/gh-aciton-test@latest to apply a "needs-review" label. The @latest tag ensures the workflow always uses the most recent stable version, though pinning to a specific major version tag is often recommended for production stability to avoid breaking changes.
Versioning Strategies and Rollback Procedures
Managing the lifecycle of a published action requires robust versioning strategies. GitHub Actions supports semantic versioning, but the implementation of updates, particularly major versions, introduces complexity. For automated publishing workflows, such as those using the actions/publish-action tool, the behavior differs based on the version type. Minor and patch updates can often be automated, but major version updates typically require manual approval to prevent unintended breaking changes from propagating to dependent workflows.
The actions/publish-action repository provides a workflow file, release-new-action-version.yml, which serves as a template for automating version releases. This automation ensures that new versions are tagged correctly and published without manual intervention for minor updates. However, the safety net of manual approval for major versions is critical for maintaining ecosystem stability.
In the event of a critical failure or customer impact caused by a new release, rollback procedures are necessary. The publish-action workflow supports manual triggering to restore a previous stable tag. By specifying the previous stable tag during the manual workflow execution, developers can revert the active version of the action, minimizing downtime and confusion for downstream users.
Security and permissions are paramount when configuring these automated workflows. The publish-action requires specific permissions to interact with the repository’s release assets and tags. The workflow file must explicitly declare the contents: write permission to allow the action to create tags and publish releases.
yaml
permissions:
contents: write # access to publish release
Without this permission, the publishing step will fail, as the GitHub token will lack the necessary authority to modify repository contents. Additionally, the actions/publish-action project itself is released under the MIT License, indicating its open-source nature, although the maintainers do not accept external contributions until the action reaches a production-ready state.
Alternative Release Automation: Publish Release Action
While actions/publish-action is designed specifically for publishing other actions, there is a broader need to publish general releases for repositories, including binaries, archives, and other assets. The eregon/publish-release action serves this purpose by providing a robust mechanism to publish draft releases. This action is particularly valuable because it ensures that the "latest release" link on a GitHub repository always points to a fully-built, stable artifact, rather than a work-in-progress draft.
A key advantage of using publish-release is the stability of release asset URLs. When a release is marked as a prerelease, the latest link may point to incomplete or unstable software. By using publish-release to finalize a draft release, developers guarantee that https://github.com/owner/repo/releases/latest resolves to a production-ready version. This enables the creation of stable, permanent URLs for download assets, such as https://github.com/owner/repo/releases/latest/download/asset-filename.tar.gz. These URLs are documented in GitHub’s help resources and are essential for distribution scenarios where users need a reliable link to the most recent stable binary.
yaml
jobs:
release:
runs-on: ubuntu-latest
steps:
- name: Create Draft Release
id: create_release
uses: actions/create-release@v1
- name: Publish Release
uses: eregon/publish-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
release_id: ${{ steps.create_release.outputs.id }}
The workflow above demonstrates a minimal example where a draft release is first created, and then eregon/publish-release is used to finalize it. The release_id from the creation step is passed to the publish step. It is important to note that the release must not be marked as a prerelease for the latest link strategy to work correctly.
Migration from Archived Actions
The GitHub Actions ecosystem is dynamic, with older actions occasionally being archived or deprecated due to security concerns or technological obsolescence. Notably, actions/create-release and actions/upload-release-asset have been archived. These legacy actions relied on outdated versions of Node.js, posing potential security and compatibility risks.
Developers migrating away from these archived actions have several alternatives. The eregon/publish-release action serves as a direct, modern replacement for finalizing releases. Additionally, the gh CLI tool, which is natively available in GitHub Actions runners, provides a powerful, built-in mechanism for managing releases. Using the gh CLI allows for more granular control and reduces dependency on external actions for simple tasks.
bash
gh release create v1.0.0 --generate-notes
This command, executed within a workflow, can create and publish releases without the need for additional action wrappers. However, for complex workflows involving draft releases and specific asset uploads, dedicated actions like publish-release remain the superior choice due to their specialized handling of release states and URL stability.
Conclusion
Publishing a GitHub Action involves a careful balance of technical configuration, documentation, and release management. By leveraging the action.yml file for branding and metadata, developers can create professional, discoverable tools for the community. The distinction between publishing to a private repository versus the public Marketplace allows for flexible distribution strategies. Furthermore, understanding the nuances of versioning, rollback procedures, and permission scopes ensures that automated publishing workflows remain secure and stable. As legacy actions like actions/create-release are archived, tools like eregon/publish-release and the native gh CLI provide modern, reliable alternatives for managing the entire release lifecycle. Ultimately, the ability to publish custom actions empowers organizations to share best practices, streamline development operations, and contribute to the robustness of the GitHub ecosystem.