GitHub Actions has firmly established itself as the primary continuous integration and continuous deployment (CI/CD) platform for millions of developers worldwide. While the official Marketplace hosts thousands of pre-built actions that cover common use cases, enterprise and advanced developer workflows often demand logic that is too specific to be generalized. Building custom actions allows teams to encapsulate complex logic, share functionality seamlessly across repositories, and create reusable automation that aligns precisely with organizational standards. The decision to build a custom action is not merely about writing code; it is an architectural choice that impacts maintainability, security, and deployment speed. Understanding the nuances of JavaScript, Docker, and composite actions, along with the best practices for versioning, error handling, and publishing, is essential for constructing robust automation infrastructure.

Selecting the Right Action Architecture

Before writing a single line of code, developers must determine the most appropriate architecture for their custom action. The choice depends on factors such as startup speed, dependency management, language requirements, and the need for isolation. There are three distinct types of custom actions available in the GitHub Actions ecosystem, each serving a specific purpose.

JavaScript actions run directly on the runner machine. This architecture is inherently fast and lightweight because it does not require the overhead of container initialization. JavaScript actions are cross-platform by nature and have direct access to the runner environment, making them ideal for tasks that need to interact closely with the host system or require rapid execution. They are particularly effective when the runner already has Node.js installed, as is common in many modern development workflows.

Docker container actions package the action code along with its entire runtime environment. This approach ensures a consistent execution environment regardless of the underlying runner machine. Docker actions are the preferred choice when the task requires complex dependencies, specific library versions, or a language other than JavaScript. By bundling the environment, Docker actions eliminate the "it works on my machine" syndrome, guaranteeing that the action behaves identically across different CI/CD environments.

Composite actions offer a middle ground for developers who need to combine existing actions without writing new code from scratch. These actions do not require coding in a specific programming language but rather orchestrate other actions into a single, reusable unit. Composite actions are ideal for simplifying complex workflows by grouping multiple steps together. They provide simple reusability, allowing teams to reduce boilerplate in their workflow files while maintaining the flexibility of individual underlying actions.

Managing Action Repository Structure

The location and structure of action files play a critical role in versioning, discovery, and maintenance. If an action is intended for public consumption or use by other repositories within an organization, it is recommended to keep the action in its own dedicated repository. This separation allows the action to be versioned, tracked, and released independently, just like any other software product. A dedicated repository makes it easier for the broader GitHub community to discover the action, narrows the scope of the codebase for developers who may need to fix issues or extend functionality, and decouples the action's versioning lifecycle from the versioning of the application code that consumes it.

However, not every custom action needs to be public or even shared outside of a single repository. For private actions that are specific to a single project and not intended for external reuse, storing the action files within the application repository is a valid and efficient strategy. When combining action, workflow, and application code in a single repository, the recommended convention is to store actions in the .github directory. For example, actions might be located at .github/actions/action-a and .github/actions/action-b. This structure keeps the automation logic organized and separate from the main application source code, reducing clutter and improving navigability.

Private JavaScript actions are particularly well-suited for this single-repository approach. When the logic is highly specific to a particular task, such as composing a unique social media announcement from blog post data, keeping the code in the same repository as the workflow minimizes ceremony. It allows developers to iterate quickly without the overhead of managing separate repositories, especially when the runtime environment (such as Node.js) is already required for other parts of the build process.

Workflow Integration and Referencing

Once an action is created, it must be integrated into a workflow file. The method of referencing the action depends on whether it resides in the same repository or a separate one.

For actions located within the same repository, the uses key in the workflow step should reference the path to the action directory relative to the repository root. This path-based reference is straightforward and avoids network latency, as the action code is already part of the cloned repository.

```yaml

.github/workflows/deploy.yml

name: Deploy Application
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

  # Use a local action from the same repo
  - name: Setup project
    uses: ./.github/actions/setup-node-project
    with:
      node-version: '20'

  - name: Build and deploy
    run: npm run build && npm run deploy

  # Use another local action for notifications
  - name: Notify Slack
    if: always()
    uses: ./.github/actions/slack-notifier
    with:
      webhook-url: ${{ secrets.SLACK_WEBHOOK }}
      environment: production
      status: ${{ job.status }}

```

For actions hosted in a separate repository, the reference must include the owner, repository name, and the version tag or branch. This pattern is essential for reusable actions that are shared across multiple projects. It is critical to pin these references to a specific version to ensure workflow stability and reproducibility.

yaml - name: Run security scan uses: your-org/security-scanner@v1 with: scan-path: ./src severity-threshold: high

Platform Compatibility and API Access

Developers building actions that may be used in enterprise environments must consider platform compatibility. Many organizations access GitHub through GitHub Enterprise Server (GHE) or custom domains rather than the public github.com domain. Actions that contain hard-coded references to API URLs, such as https://api.github.com, will fail in these environments.

To ensure compatibility across public GitHub and private enterprise instances, actions should never hard-code API endpoints. Instead, they must utilize environment variables provided by the GitHub Actions runner. For REST API interactions, the GITHUB_API_URL environment variable should be used to construct dynamic endpoints. This variable automatically resolves to the correct API base URL for the current environment, whether it is the public cloud or a self-hosted enterprise server.

When querying GitHub's API for complex data, such as deployment statuses, developers have access to both REST (v3) and GraphQL (v4) APIs. Both APIs support a wide range of fields and actions, allowing developers to construct precise queries that retrieve exactly the data needed for their automation logic. For example, a custom action might query the GitHub API to find the latest Vercel deployment status, avoiding the need to rebuild the application multiple times within a single workflow. This level of integration is often necessary when existing marketplace actions do not provide the specific data retrieval capabilities required by a unique workflow.

Best Practices for Development and Publishing

Creating a high-quality custom action requires adherence to several best practices that ensure reliability, usability, and maintainability.

Single Responsibility: Actions should be focused on a single responsibility. It is better to have multiple small, specialized actions than one monolithic action that attempts to do everything. Small actions are easier to test, debug, and reuse. For instance, one action might handle environment setup, while another handles Slack notifications.

Error Handling: Actions must handle errors gracefully and provide meaningful error messages. In JavaScript actions, the core.setFailed() function should be used to properly signal failures to the GitHub Actions runner. This ensures that the workflow fails with a clear, actionable message rather than a cryptic stack trace.

Documentation: Inputs and outputs must be documented thoroughly in the action.yml file. This metadata is crucial because it appears in the GitHub Marketplace and provides helpful hints in IDE integrations when users configure the action in their workflows. Clear documentation reduces the learning curve for consumers of the action.

Testing: Actions should be tested before publishing. Developers should create a test workflow that exercises different input combinations to ensure the action behaves as expected under various conditions. This proactive testing prevents broken workflows in production environments.

Versioning: Actions should be versioned using semantic versioning and git tags. Users should always be able to pin to a specific version of an action to prevent breaking changes from disrupting their CI/CD pipelines. When publishing an action to the GitHub Marketplace, adding branding to the action.yml file, such as an icon and color, enhances its visibility and professional appearance. Creating a release in the repository will prompt GitHub to publish the action to the marketplace if the metadata is properly configured.

Conclusion

Building custom GitHub actions is a powerful strategy for extending the platform's capabilities to meet specific organizational needs. Whether leveraging the speed of JavaScript actions, the consistency of Docker containers, or the simplicity of composite actions, developers can create automation that is both robust and reusable. By adhering to best practices in repository structure, API compatibility, error handling, and versioning, teams can ensure their custom actions are reliable and maintainable. As workflows grow in complexity, the ability to abstract logic into well-documented, versioned actions becomes a critical component of a mature CI/CD strategy.

Sources

1. OneUptime: GitHub Actions Custom Actions
2. Microsoft Learn: Create custom GitHub Actions
3. GitHub Docs: Manage custom actions
4. Damir's Corner: Implementing Private JavaScript GitHub Action
5. Dor Shinar: Creating GitHub Actions