Add GHA workflow to validate pants BUILD files

[cognifloyd]

Background

This is another part of introducing pants, as discussed in the TSC Meetings on 12 July 2022, 02 Aug 2022 and 06 Sept 2022. Pants has fine-grained per-file caching of results for lint, fmt (like black), test, etc. It also has lockfiles that work well for monorepos that have multiple python packages. With these lockfiles CI should not break when any of our dependencies or our transitive dependencies release new versions, because CI will continue to use the locked version until we explicitly relock with updates.

To keep PRs as manageable/reviewable as possible, introducing pants will take a series of PRs. I do not know yet how many PRs; I will break this up into logical steps with these goals:

• introduce pants to the st2 repo, and
• teach some (but not all) TSC members about pants step-by-step.

Other pants PRs include:

• Initialize pantsbuild #5713
• Configure pantsbuild source roots #5724
• Enable pantsbuild language backends #5725
• Adjust .gitignore to work better with pantsbuild #5726
• Add GHA workflow to validate pants BUILD files #5732

Due to scope change, this PR replaces #5727

Overview of this PR

It's helpful to review this PR one commit at a time.

This PR prepares us to run pants in GitHub Actions (GHA). There are 2 parts to this:

1. Add a CI-specific pants config file: pants.ci.toml (used in addition to pants.toml)
2. Prepare to add BUILD files to the repo: Add GHA workflow that makes sure BUILD files are up-to-date.

CI-specific pants config

The pants docs recommend adding a CI-specific pants config file called pants.ci.toml:
https://www.pantsbuild.org/docs/using-pants-in-ci#configuring-pants-for-ci-pantscitoml-optional

Please note this quote from the docs:

set the environment variable PANTS_CONFIG_FILES=pants.ci.toml to use this new config file, in addition to pants.toml.

So, pants.ci.toml does NOT replace pants.toml, it extends it. So, pants will still use the pants.toml, but we can tune settings specifically for GHA, and possibly CircleCI (if we need to use pants there).

We don't have to remember to add the PANTS_CONFIG_FILES env var, however, because that is covered by the reusable pants-init action, which injects the env var for us.

Pants GHA workflow

BUILD files are an important part of helping pants understand our codebase. As the docs say:

BUILD files provide metadata about your code (the timeout of a test, any dependencies which cannot be inferred, etc). BUILD files are typically located in the same directory as the code they describe. Unlike many other systems, Pants BUILD files are usually very succinct, as most metadata is either inferred from static analysis, assumed from sensible defaults, or generated for you.

In one of the next PRs, we will be adding BUILD files with metadata for pants across the repo. That PR will run ./pants tailor :: as described in initial config docs.

pants has some great tooling to ensure those BUILD files are up-to-date, so we will need a GHA workflow that validates those files. I want to enable a workflow as soon as we add the BUILD files, but--to simplify reviewing--I don't want to add the workflow in the same PR that we add the BUILD files. So, I'm adding the workflow in this PR without enabling it.

This is the key part of the workflow:

st2/.github/workflows/pants.yaml

Lines 53 to 55 in acfffce

	- name: Check BUILD files
	run: |
	./pants tailor --check update-build-files --check ::

Here, we run two pants goals in check mode:

• tailor: "Auto-generate BUILD file targets for new source files."
• update-build-files: "Format and fix safe deprecations in BUILD files."

tailor example: If we add a shell script in a directory that didn't have any shell scripts before, then tailor would add a shell_sources target in a BUILD file in that directory. Same for python, and many other things. I expect to discuss more about the contents of BUILD files in the PRs where we add, and then modify them.

update-build-files example: BUILD files use python syntax, so this runs black over them to reformat them. update-build-files also vastly simplifies upgrading between pants versions, because it can adjust the BUILD files to use the latest-and-greatest targets/fields/etc. As the docs say, it can: "Automatically fix deprecations, such as target type renames, that are safe because they do not change semantics."

[cognifloyd]

We will uncomment this and remove workflow_dispatch when we add the BUILD files.

[cognifloyd]

https://github.com/pantsbuild/actions/tree/main/init-pants

The action handles installing pants, adding the PANTS_CONFIG_FILES env var (to use our new pants.ci.toml file), and it manages the GHA caches for us. Using this action means that we don't have to repeat those steps in every workflow that uses pants.

One of these GHA cahces will include the pip cache, so we will also be able to simplify our cache usage in other workflows once we are using pants everywhere.

[cognifloyd]

If we experience any issues with the 10GB GHA cache limit (a per-repo limit), we may need to add a workflow that periodically clears out older unused caches - Github expires unused caches after 7 days, but we might want a shorter timespan, as this cache is a per-commit cache. We can also bump the gha-cache-key input var if the cache gets too big to ignore it and start fresh.

[cognifloyd]

In my experience, this log is often nearly empty, but it can be very useful when debugging CI issues. Adding this step is recommended here: https://www.pantsbuild.org/docs/using-pants-in-ci#tip-store-pants-logs-as-artifacts

We will want to add this step in each workflow that runs pants.

[cognifloyd]

Recommended under "Tip: check cache performance with [stats].log" at the end of the Directories to Cache section of the docs.

[cognifloyd]

This was copied from the sample in the docs: https://www.pantsbuild.org/docs/using-pants-in-ci#configuring-pants-for-ci-pantscitoml-optional

[rush-skills]

LGTM