chore(ci): refactor release workflow

[am29d]

Description of your changes

In this PR we refactor the release workflow to reduce the permission scope and add additional review step for the layer arn docs changes. The changes include

• add create-tag because we don't do it with lerna any more
• add create-pr step after layer prod deployment to review doc changes
• use github.sha for commit hash checkout
• publish from-package in detached head with a sha, because we tag in the next
• change layer doc updates to PR review
• scope down permissions to contents: read

Related issues, RFCs

Issue number: #1799

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[heitorlessa]

just wanted to say... great work @am29d !!

Abiding to our implicit tenet of working in public, we briefly discussed about the seal+checkout process, so here's the reasoning:

• Prevent in-between commits to slip in. One of the issues we've had having versioning being bumped outside the release process was that we didn't have guarantees that another commit could've been pushed between bump and release. The solution was to always checkout code from the release commit (immutable), bump the version in the first step, seal the changed source code along w/ integrity hash, and restore it in subsequent steps.
• GitHub requires a checkout in the build process. I've bumped into mysterious issues with the git client, credentials, and actions in general when I tried to restore the sealed artifact without a checkout. The solution was to always checkout followed by a restore of the sealed artifact which would overwrite what's being checked out, thus bringing the newly bumped version we are meant to release.

Whichever solution you find that prevents accidental code being added to the release after a version bump I'll be happy with it. Ping @sthulb for a security review once this is settled.

We're here to help!

[dreamorosi]

great work @am29d !!

+1 on this

Prevent in-between commits to slip in

We have opted to go in this direction because we want to delegate the version increase to Lerna rather than having to manually compute it and input it (which is also error prone, and irreversible once published). Already in its current form, Lerna scans the messages of all the commits made since the previous release and based on conventional commits it decides the next version.

At the very beginning of the project (mid 2021) this was done manually but given the modular nature of the project we found that this put a significant cognitive load on the maintainers. To obviate this we adopted the lerna version command which creates the changelog for each package in its respective directory, updates all the package.json files, and commits the changes.

Given that we want to remove the contents: write permission and we no longer want our CI to mutate the repository without the maintainers supervision, we need to surface the commit into a PR. This also gives us the chance to review the new version and its contents before the actual release process starts.

With this in mind, we decided to split the workflow in two:

• one that versions the project (chore(ci): add versioning workflow for pre-release #2006)
• and another that does the release on npm as well as Layers (this PR)

Our original plan was to have a maintainer take the commit hash of the versioning commit and use it as an input of the release workflow. After your comment however I wonder if this might not be enough to establish strong provenance.

I don't want to complicate the workflows further, but at least for now I'm inclined to keep the versioning & release steps separate unless there's no other way that satisfies governance & security. To this end, I see two options:

1. add an initial step to the release workflow that checks the input commit hash & determines if it comes from the correct PR (aka the latest versioning one).
2. use the "Versioning PR merged" event as a trigger of the release workflow

The second option is probably the simpler (in terms of implementation) and guarantees a stronger link between versioning & release. The only problem I see with it is that if for any reason the release workflow fails, we'd have to revert the versioning commit & run it again, but I think it's an acceptable tradeoffs in the name of security (as long as we have a runbook ).

What do you all think?

[heitorlessa]

looking 👀

[heitorlessa]

one question about the usage of a custom token on action/checkout.

Ask: could you please document the overall process of make-release.yml?

Example: https://github.com/aws-powertools/powertools-lambda-python/blob/9b00d0a690077cc6df227556ad45055b8febc4b3/.github/workflows/release.yml#L3

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[heitorlessa]

great work @am29d !!!

[dreamorosi]

Amazing work, looking forward to test this!

Thanks for raising the bar on this!