Document permissions and add example workflow / integration job

[stackptr]

Documents minimum permissions required for the action to run in repos with restricted default permissions for workflows or for PRs created by Dependabot. These were established by a bit of trial and error in https://github.com/freckle/megarepo/pull/30954 (private repository).

[pbrisbin]

Great idea! Maybe we should add this to any of our -actions template repositories?

Curious about the id-token though. Not sure why that'd be necessary.

[stackptr]

Great idea! Maybe we should add this to any of our -actions template repositories?

Yeah, this seems good to require as part of minimal documentation for new actions. Is there a repository besides freckle/typescript-action-template?

I think it would be a good rule of thumb for each action repo's CI workflow to specify the minimal required permissions, to flag changes that require more permissive workflow runs.

[pbrisbin]

Is there a repository besides freckle/typescript-action-template?

I trust your ability to search as well as mine, so probably not?

good rule of thumb for each action repo's CI workflow

By that you mean the action's "example" workflow? The permissions needed to CI an action vs use it would differ, so if this is meant to document usage that would be in the example, I think.

[stackptr]

Yeah, I was thinking of example.yml workflows (i.e., something that uses: ./. However, I think example.yml should show a representative/common use of the action in a workflow, which is different (in this case) to a test run that exercises the action as a form of CI. Particularly for this action, it's inconvenient to have on.pull_request.types: [opened] since it only runs a single time. Also, exercising the action requires a repo checkout, which is unnecessary for regular use.

I think two workflows are appropriate to add to this repo:

• example.yml complements or removes the existing section on Usage and wouldn't be expected to run in development PRs
• test.yml exercises the action with minimal permissions

[pbrisbin]

Oh yeah, this is interesting.

I think example.yml should show a representative/common use of the action in a workflow, which is different (in this case) to a test run that exercises the action as a form of CI

In my experience they are more often basically the same than they are different in meaningful ways, but I guess that doesn't need to stop us from making them distinct always. As an alternative to your suggestion, how about:

• example.yml as you describe, but it does run on PRs
• ci.yml as it is today, typically with unit test jobs, lint etc, but also with integration* Job(s) that exercise the action as necessary (i.e. with different arguments, happy/sad paths) and includes minimal permissions.

I prefer this because:

1. You really do need to exercise example on PRs IMO, otherwise it'll become broken without us knowing and be bad docs
2. We're talking about adding a form of CI, so I'd prefer extending the existing "CI" over creating a similarly-named "test"

[pbrisbin]

Oh.

I didn't realize this is what you meant, and it feels a bit weird. I see why you suggested not running this workflow on PRs -- it's not exercising the changed code. If I take back my suggestion to run this on PRs (there's no reason to if it's not running with uses: ./) then what is the benefit of this vs just leaving it to the README?

[stackptr]

The README could remove some of the YAML and refer to the example.yml instead. The workflow is validated and the configuration is parsed by those runs, so it provides slightly more assurance than YAML code blocks in the README, but I don't feel strongly it's a huge improvement.

[pbrisbin]

Hmm yeah, same here about not feeling strongly.