wip: adds README and earthly version support

Author: jmgilman

blueprint.cue

@@ -9,22 +9,22 @@ ci: {
 			registry: "332405224602.dkr.ecr.eu-central-1.amazonaws.com"
 			role:     "arn:aws:iam::332405224602:role/ci"
 		}
-		docker: {
-			credentials: {
-				provider: "aws"
-				path:     "global/ci/docker"
-			}
+
+		docker: credentials: {
+			provider: "aws"
+			path:     "global/ci/docker"
 		}
+
 		earthly: {
 			credentials: {
 				provider: "aws"
 				path:     "global/ci/earthly"
 			}
 			org:       "Catalyst"
 			satellite: "ci"
+			version:   "0.8.15"
 		}
-		github: {
-			registry: "ghcr.io"
-		}
+
+		github: registry: "ghcr.io"
 	}
 }

blueprint/schema/_embed/schema.cue

@@ -81,6 +81,10 @@ package schema
 	// Satellite contains the satellite to use for caching.
 	// +optional
 	satellite?: null | string @go(Satellite,*string)
+
+	// The version of Earthly to use in CI.
+	// +optional
+	version?: null | string @go(Version,*string)
 }
 
 // ProviderGithub contains the configuration for the Github provider.

blueprint/schema/schema.go

@@ -53,6 +53,8 @@ type Providers struct {
 	// +optional
 	Earthly ProviderEarthly `json:"earthly"`
 
+	// Github contains the configuration for the Github provider.
+	// +optional
 	Github ProviderGithub `json:"github"`
 }
 
@@ -88,6 +90,10 @@ type ProviderEarthly struct {
 	// Satellite contains the satellite to use for caching.
 	// +optional
 	Satellite *string `json:"satellite"`
+
+	// The version of Earthly to use in CI.
+	// +optional
+	Version *string `json:"version"`
 }
 
 // ProviderGithub contains the configuration for the Github provider.

blueprint/schema/schema_go_gen.cue

@@ -81,6 +81,10 @@ package schema
 	// Satellite contains the satellite to use for caching.
 	// +optional
 	satellite?: null | string @go(Satellite,*string)
+
+	// The version of Earthly to use in CI.
+	// +optional
+	version?: null | string @go(Version,*string)
 }
 
 // ProviderGithub contains the configuration for the Github provider.

forge/actions/setup/README.md

@@ -0,0 +1,111 @@
+# Setup Action
+
+The setup action can be used to install the Forge CLI and configure various providers by reading from the root blueprint file.
+The blueprint schema provides options for configuring a number of third-party providers like AWS, Earthly, etc.
+The setup action will automatically interrogate these options and use them to determine which providers to set up.
+The action only configures providers that have been specified in the blueprint file.
+
+## Usage
+
+Add a `blueprint.cue` to the root of your repository and add configuration for individual providers.
+Here is an example:
+
+```cue
+version: "1.0"
+ci: {
+	providers: {
+		aws: {
+			region:   "eu-central-1"
+			registry: "123456.dkr.ecr.eu-central-1.amazonaws.com"
+			role:     "arn:aws:iam::123456:role/ci"
+		}
+		earthly: {
+			credentials: {
+				provider: "aws"
+				path:     "path/to/secret"
+			}
+			org:       "myorg"
+			satellite: "sat"
+		}
+	}
+}
+```
+
+The above blueprint configures both the AWS and Earthly Cloud providers.
+Once in place, simply invoke the setup action in a step:
+
+```yaml
+name: Run Setup
+on:
+  push:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup
+        uses: input-output-hk/catalyst-forge/forge/actions/setup@master
+```
+
+The action will then perform the following:
+
+1. Install the latest version of the Forge CLI
+2. Authenticate to AWS via OIDC
+3. Authenticate to Earthly Cloud using the credentials in the AWS Secrets Manager secret stored at `path/to/secret`
+4. Set the default Earthly Cloud organization to `myorg`
+
+### Configuring Providers
+
+All providers expect credentials to be passed via a secret.
+The format for the secret is the same as used elsewhere in Catalyst Forge.
+Notably, the setup action assumes credentials are stored in a common way inside secrets.
+The secret must be a JSON string with specific keys mapping to specific credentials.
+
+The below list documents the expected format for each provider:
+
+1. Docker
+   - `username`: The username to login with
+   - `password`: The password to login with
+1. Earthly
+  - `token`: The Earthly Cloud token to login with
+
+If the secret uses a different format, the `maps` field of the secret can be used to map them correctly:
+
+```cue
+version: "1.0"
+ci: {
+	providers: {
+		docker: {
+			credentials: {
+				provider: "aws"
+				path:     "path/to/secret"
+                maps: {
+                    username: "my_username"
+                    password: "my_password"
+                }
+			}
+		}
+	}
+}
+```
+
+In the above example, the fields `my_username` and `my_password` are remapped to the expected `username` and `password` fields.
+
+### Local Testing
+
+By default, the setup action installs release versions of the Forge CLI.
+The `forge_version` input can be set to `local` in order to build a local version of the CLI.
+This is useful for testing changes without needing to perform a release.
+
+Note that this _only_ works when run within the Catalyst Forge repository.
+
+## Inputs
+
+| Name          | Description                              | Required | Default                 |
+| ------------- | ---------------------------------------- | -------- | ----------------------- |
+| forge_version | The version of the forge CLI to install  | No       | `"latest"`              |
+| github_token  | The GitHub token used for authentication | No       | `"${{ github.token }}"` |

forge/actions/setup/action.yml

@@ -1,9 +1,6 @@
 name: Setup CI
 description: Sets up the CI with the configured providers
 inputs:
-  earthly_version:
-    description: The version of Earthly to install
-    default: latest
   forge_version:
     description: The version of the forge CLI to install (use 'local' for testing)
     default: latest
@@ -20,7 +17,7 @@ runs:
       uses: earthly/actions-setup@v1
       if: inputs.forge_version == 'local'
       with:
-        version: ${{ inputs.earthly_version }}
+        version: latest
     - name: Cache Forge CLI binary
       if: inputs.forge_version == 'local'
       id: cache-forge
@@ -118,11 +115,6 @@ runs:
         password: ${{ inputs.github_token }}
 
     # Earthly Provider
-    - name: Install Earthly
-      uses: earthly/actions-setup@v1
-      if: inputs.forge_version != 'local'  # Prefer to install Earthly after logging into Docker Hub
-      with:
-        version: ${{ inputs.earthly_version }}
     - name: Get Earthly provider configuration
       id: earthly
       shell: bash
@@ -132,6 +124,9 @@ runs:
         EARTHLY=$(echo "$BP" | jq -r .ci.providers.earthly)
         if [[ "$EARTHLY" != "null" ]]; then
           ORG=$(echo "$BP" | jq -r .ci.providers.earthly.org)
+          VERSION=$(echo "$BP" | jq -r .ci.providers.earthly.version)
+        else
+          VERSION="latest"
         fi
 
         EARTHLY_CREDS=$(echo "$BP" | jq -r .ci.providers.earthly.credentials)
@@ -146,9 +141,15 @@ runs:
         fi
 
         echo "org=$ORG" >> $GITHUB_OUTPUT
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
 
         echo "::add-mask::$TOKEN"
         echo "token=$TOKEN" >> $GITHUB_OUTPUT
+    - name: Install Earthly
+      uses: earthly/actions-setup@v1
+      if: inputs.forge_version != 'local'  # Prefer to install Earthly after logging into Docker Hub
+      with:
+        version: ${{ steps.earthly.outputs.version }}
     - name: Login to Earthly Cloud
       if: steps.earthly.outputs.token != ''
       shell: bash
@@ -158,8 +159,4 @@ runs:
       if: steps.earthly.outputs.org != ''
       shell: bash
       run: |
-        earthly org select "${{ steps.earthly.outputs.org }}"
-    - name: Testing
-      shell: bash
-      run: |
-        forge run ./forge/cli+test
+        earthly org select "${{ steps.earthly.outputs.org }}"