Docs clarification on ORGANIZATION_ADMIN_TOKEN for non-organization accounts

[asgrim]

Q	A
Documentation	yes
Bugfix	no
BC Break	no
New Feature	no
RFC	no
QA	no

Description

It appears the ORGANIZATION_ADMIN_TOKEN was being used in the example release-on-milestone-closed.yml for the Create and/or Switch to new Release Branch step. This caught me out as I was rolling out automatic-releases to a personal (non-organisation) repository, and I didn't spot the usage of ORGANIZATION_ADMIN_TOKEN.

UPDATE since the original proposal was wrong because docs misunderstanding (see discussion below), this PR is now a docs update to clarify the ORGANIZATION_ADMIN_TOKEN meaning when working in the context of a non-organization (i.e. regular user account) repository.

[Ocramius]

It appears the ORGANIZATION_ADMIN_TOKEN was being used in the example release-on-milestone-closed.yml for the Create and/or Switch to new Release Branch step.

That is correct though: the switch-default-branch-to-next-minor command only works if the given token is an organization token, while GITHUB_TOKEN cannot perform administrative tasks, and will fail if used in this step.

[asgrim]

It appears the ORGANIZATION_ADMIN_TOKEN was being used in the example release-on-milestone-closed.yml for the Create and/or Switch to new Release Branch step.

That is correct though: the switch-default-branch-to-next-minor command only works if the given token is an organization token, while GITHUB_TOKEN cannot perform administrative tasks, and will fail if used in this step.

Hmm, seems I've misunderstood the docs. I was under the impression release-on-milestone-closed.yml can be used where ORGANIZATION_ADMIN_TOKEN cannot (e.g. a regular user repo, rather than a repo in an organization).

In that case, I'd propose updating the docs to

1. Instead of starting if you use the file... (which suggests the ORGANIZATION_ADMIN_TOKEN is optional, which I have now discovered is not the case), remove that first section (I misread it as if you use the file from examples/.github/workflows/release-on-milestone-closed-triggering-release.yml instead of if you use the file from examples/.github/workflows/release-on-milestone-closed.yml - the actual text)
2. clarify usage on personal (non-org) repos - the wording only applies to organizations at the moment

[Ocramius]

(e.g. a regular user repo, rather than a repo in an organization).

If you are a regular user, then ORGANIZATION_ADMIN_TOKEN would be a personal token with admin rights: that indeed does need improvement of docs, if unclear.

[asgrim]

Updated this PR to now be a docs clarification only (I've rebased the original workflow edit out)

[Ocramius]

Thanks @asgrim!