Should actions be stored in a separate repo or nested in another

user_2709980 0
Viewed 281

What are the best practices around creating a Github Action?

There seem to be roughly three approaches

One repo = one Action

From these examples I clearly derive that 1 action = 1 repo.

action-repo
  action.yml
  ...

With usage:

uses: org/action-repo@tag

"Normal" repo with nested Action

Some tend to just add the action to their repo like so:

repo
  github-action
    action.yml
    ...

Probably also with more than one action. This gives already longer imports like:

uses: org/repo/github-action@tag

"Normal" repo with nested/hidden action

This is the most special case I have seen:

repo
  .github
    actions
      action1
        action.yml
        ...
      action2
        action.yml
        ...

This setup leads to some weird imports in the usage of the actions like

uses: org/repo/.github/actions/action1@tag

Has anyone seen official docs around this?

github-actions
2 Answers

Two weeks into GHA, seeing dozens of repositories I dare to self-answer my question.

As the initial comments suggested, the approach you choose depends mainly on your use case.

Let me re-use also part of that comment to finalize my summary (anyone feel free to comment I will take the argument into my list).

Approaches

org/action-repo

above called "1 action = 1 repo"

  • ➕  Certainly, the most seen standard, many "best of breed" actions (e.g. checkout, setup-xyz, etc.) use this approach
  • ➕  Transparent versioning
  • ➕  Straight forward uses (no nested paths)
  • ➕  Follow UNIX philosophy of doing one thing well
  • ➕  Easy to document, have issues, and pull requests for your action only

  • ➖  Additional repo

This is a suitable approach for when you expect your action to be adopted by a large community or you just feel like "public needs that".

org/repo/action

above called nested action

➕➖  The above comparison the other way around.

This approach is mainly suitable to maintain some smaller actions that you just casually want to offer from within your project. We use it in our case now to accumulate some mono-repo-specific actions in one place.

org/repo/.github/action(s)

This approach admittedly is the most special one and a derivation of the second. Generally, there is no real use case for it - conjuring one up it is possible e.g. in a mono-repo to abstract all actions into the .github folder to kind of collect them. On the other hand, you can do that too in org/repo/action(s).

Feel free to complete my list by commenting.

user_27099800

You can always refer to the documentation:

If you're developing an action for other people to use, we recommend keeping the action in its own repository instead of bundling it with other application code. This allows you to version, track, and release the action just like any other software.

Storing an action in its own repository makes it easier for the GitHub community to discover the action, narrows the scope of the code base for developers fixing issues and extending the action, and decouples the action's versioning from the versioning of other application code.

If you're building an action that you don't plan to make available to the public, you can store the action's files in any location in your repository. If you plan to combine action, workflow, and application code in a single repository, we recommend storing actions in the .github directory. For example, .github/actions/action-a and .github/actions/action-b.

user_15294220
Related