Add --upload flag to atmos describe affected command

[aknysh]

what

• Add --upload flag to atmos describe affected command
• Update docs
  • https://pr-631.atmos-docs.ue2.dev.plat.cloudposse.org/cli/commands/describe/affected/

why

If the --upload=true command-line flag is passed, Atmos will upload the affected components and stacks to a specified HTTP endpoint.

The endpoint can process the affected components and their dependencies in a CI/CD pipeline (e.g. execute terraform apply on all the affected components in the stacks and all the dependencies).

Atmos will perform an HTTP POST request to the URL ${ATMOS_PRO_BASE_URL}/${ATMOS_PRO_ENDPOINT}, where the base URL is defined by the ATMOS_PRO_BASE_URL environment variable, and the URL path is defined by the ATMOS_PRO_ENDPOINT environment variable.

An Authorization header Authorization: Bearer $ATMOS_PRO_TOKEN will be added to the HTTP request (if the ATMOS_PRO_TOKEN environment variable is set) to provide credentials to authenticate with the server.

NOTE: If the --upload=true command-line flag is passed, the --include-dependencies and --include-settings flags are automatically set to true, so the affected components will be uploaded with their dependencies and settings (if they are configured in Atmos stack manifests).

The payload of the HTTP POST request will be a JSON object with the following schema:

  {
     "base_sha": "6746ba4df9e87690c33297fe740011e5ccefc1f9",
     "head_sha": "5360d911d9bac669095eee1ca1888c3ef5291084",
     "repo_url": "https://github.com/cloudposse/atmos",
     "repo_host": "github.com",
     "repo_name": "atmos",
     "repo_owner": "cloudposse",
     "stacks": [
        {
          "component": "vpc",
          "component_type": "terraform",
          "component_path": "examples/quick-start/components/terraform/vpc",
          "stack": "plat-ue2-dev",
          "stack_slug": "plat-ue2-dev-vpc",
          "affected": "stack.vars",
          "included_in_dependents": false,
          "dependents": [],
          "settings": {}
        }
    ]
 }

where:

• base_sha - the Git commit SHA of the base branch against which the changes in the current commit are compared

• head_sha - the SHA of the current Git commit

• repo_url - the URL of the current repository

• repo_host - the host of the current repository

• repo_name - the name of the current repository

• repo_owner - the owner of the current repository

• stacks - a list of affected components and stacks with their dependencies

[mcalhoun]

It's looking really good! I left a few comments and asked for some changes.

[mcalhoun]

I made a couple more small comments/requests for change and then this looks good to merge to me. Thanks!

[mcalhoun]

Approving the PR, but still don't agree that we shouldn't warn/error when the API token isn't set (see my comment).

[github-actions]

These changes were released in v1.82.0.