fix: Enforce explicitly setting SHA in API requests

[lukaspj]

what

I propose adding the Commit SHA as a required field on API requests.

why

When running API Requests, we are currently only requiring the following fields:

type APIRequest struct {
	Repository string `validate:"required"`
	Ref          string `validate:"required"`
	Type       string `validate:"required"`
	PR           int
	Projects  []string
	Paths      []struct {
		Directory string
		Workspace string
	}
}

However, this is not sufficient information as many operations rely on knowing the exact commit we are working on and not just the Ref, which is a moving target.

Furthermore, it's more reliable to explicitly state the SHA you want to perform actions on, otherwise you could get unexpected results as the pipeline you are currently working with locally might be pointing to a different version of the Ref than the one that Atlantis fetches.

tests

I would like guidance on how to appropriately testing this change as I'm fairly unfamiliar with the Atlantis codebase.

references

closes #5143

[jamengual]

@lukaspj could you update the api docs too? Thanks.

[lukaspj]

I certainly can, but I was unsure exactly how to handle the docs side of it, considering this is a breaking change as-is.

Would you prefer me to make it default to the previous behaviour when no SHA is provided or make it required like it is now?

[jamengual]

I certainly can, but I was unsure exactly how to handle the docs side of it, considering this is a breaking change as-is.

Would you prefer me to make it default to the previous behaviour when no SHA is provided or make it required like it is now?

That will be even better.

the docs you will need to change https://www.runatlantis.io/docs/api-endpoints.html which is here in the repo https://github.com/runatlantis/atlantis/blob/main/runatlantis.io/docs/api-endpoints.md