[WIP] App install flow

.github/workflows/test-account-config.json

@@ -0,0 +1,9 @@
+{
+  "accountName": "project-actions-test-account",
+  "description": "Test account for project actions",
+  "marketingLevel": "ENTERPRISE",
+  "opsLevel": "ENTERPRISE",
+  "serviceLevel": "ENTERPRISE",
+  "salesLevel": "ENTERPRISE",
+  "contentLevel": "ENTERPRISE"
+}

.github/workflows/test-composed-flow.yml

@@ -8,14 +8,42 @@ env:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    outputs:
+      test_account_id: ${{ steps.test-account-create-step.outputs.account_id }}
     steps:
       - name: Checkout
         uses: actions/[email protected]
       - name: HubSpot Project Validation Action
         uses: ./project-validate
         with:
           project_dir: ./.github/workflows/example-project
+      - name: HubSpot Test Account Creation Action
+        id: test-account-create-step
+        uses: ./create-test-account
+        with:
+          account_config_path: ./.github/workflows/test-account-config.json
       - name: HubSpot Project Upload Action
         uses: ./project-upload
         with:
           project_dir: ./.github/workflows/example-project
+          personal_access_key: ${{ steps.test-account-create-step.outputs.personal_access_key }}
+          account_id: ${{ steps.test-account-create-step.outputs.account_id }}
+      - name: HubSpot Install OAuth App Action
+        uses: ./install-oauth-app
+        with:
+          test_account_id: ${{ steps.test-account-create-step.outputs.account_id }}
+          project_dir: ./.github/workflows/example-project
+          personal_access_key: ${{ steps.test-account-create-step.outputs.personal_access_key }}
+          account_id: ${{ steps.test-account-create-step.outputs.account_id }}
+
+  cleanup:
+    needs: deploy
+    if: always() && needs.deploy.outputs.test_account_id != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: HubSpot Delete Test Account Action
+        uses: ./delete-test-account
+        with:
+          test_account_id: ${{ needs.deploy.outputs.test_account_id }}

README.md

@@ -1,11 +1,5 @@
 # Official HubSpot Project Actions
 
-:warning: This is pre-release software. It is unstable and subject to breaking changes.
-
-For now, we recommend using the more stable [current project upload action](https://github.com/HubSpot/hubspot-project-upload-action)
-
----
-
 Use these composable actions to upload, deploy, and test your HubSpot Developer Projects. These actions are modular so you can arrange them into a workflow that best suits your needs.
 
 Don't know where to start? Follow the usage guide below to set up a basic flow to upload your project into your HubSpot account.
@@ -57,9 +51,59 @@ jobs:
 
 This should enable automatic uploads to your target HubSpot account with every commit into `main` 🚀
 
+## `Test Hubspot Project` Action
+
+This action is a wrapper around several core actions to simplify your workflow setup. It facilitates our recommended automated validation & testing workflow.
+
+1. Validate your project to ensure it's properly configured
+2. Create a new Developer Test Account to test in isolation
+3. Upload your project into the test account and install your app
+
+This sets you up with an isolated environment to safely run your tests!
+
+See the [test-hubspot-project docs](./test-hubspot-project/README.md) for details on how to use this action in your workflow.
+
+**Example usage:**
+
+```yaml
+- uses: HubSpot/hubspot-project-actions/test-hubspot-project@v1
+  with:
+    account_config_path: "./test-account-config.json"
+    project_dir: "./my-project" # optional
+```
+
 ## Available Actions
 
-All actions support the `DEFAULT_ACCOUNT_ID` and `DEFAULT_PERSONAL_ACCESS_KEY` env variables, so you don't need to pass them into each action individually.
+While we recommend using our `test-hubspot-project` action, you are free to compose these actions however you'd like! All actions support the `DEFAULT_ACCOUNT_ID` and `DEFAULT_PERSONAL_ACCESS_KEY` env variables, so you don't need to pass them into each action individually.
+
+### `Create Test Account`
+
+Creates a new HubSpot test account based on a configuration file. This action allows you to programmatically create test accounts with predefined settings.
+
+See the [create-test-account docs](./create-test-account/README.md) for detailed specs.
+
+**Example usage:**
+
+```yaml
+- uses: HubSpot/hubspot-project-actions/create-test-account@v1
+  with:
+    account_config_path: "./test-account-config.json"
+```
+
+### `Delete Test Account`
+
+Deletes a HubSpot test account. This action is typically used to clean up test accounts after running tests.
+
+See the [delete-test-account docs](./delete-test-account/README.md) for detailed specs.
+
+**Example usage:**
+
+```yaml
+- uses: HubSpot/hubspot-project-actions/delete-test-account@v1
+  with:
+    personal_access_key: ${{ steps.create-test-account.outputs.personal_access_key }}
+    account_id: ${{ steps.create-test-account.outputs.account_id }}
+```
 
 ### `Project Upload`
 
@@ -104,6 +148,20 @@ See the [project-validate docs](./project-validate/README.md) for detailed specs
     project_dir: "./my-project" # optional
 ```
 
+### `Install OAuth App`
+
+Installs your project's OAuth app into a target Developer Test Account.
+
+See the [install-oauth-app docs](./install-oauth-app/README.md) for detailed specs.
+
+**Example usage:**
+
+```yaml
+- uses: HubSpot/hubspot-project-actions/install-oauth-app@v1
+  with:
+    target_account_id: 12345678
+```
+
 ### `Install HubSpot CLI`
 
 Installs the HubSpot CLI. Only installs if the cli has not already been installed by an earlier step.

create-test-account/README.md

@@ -0,0 +1,47 @@
+# `Create Test Account` Action
+
+Creates a new HubSpot test account based on a configuration file. This action allows you to programmatically create test accounts with predefined settings.
+
+**Inputs:**
+
+- `account_config_path` (required): Path to the test account configuration file
+- `personal_access_key` (optional): Personal Access Key generated in HubSpot that grants access to the CLI. If not provided, will use DEFAULT_PERSONAL_ACCESS_KEY from environment.
+- `account_id` (optional): HubSpot account ID associated with the personal access key. If not provided, will use DEFAULT_ACCOUNT_ID from environment.
+- `cli_version` (optional): Version of the HubSpot CLI to install. If not provided, will look for `DEFAULT_CLI_VERSION` in environment. If neither are found, defaults to `latest`.
+
+**Outputs:**
+
+- `personal_access_key`: The personal access key of the created test account
+- `account_id`: The account ID of the created test account
+
+**Example usage:**
+
+On every code push, create a new test account and then upload your project into it. This leverages the `personal_access_key` and `account_id` output from the test account create action to upload the project into the newly created test account instead of the default account.
+
+_tip:_ Use `hs test-account create-config` to generate a test account config file.
+
+```yaml
+on: [push]
+
+env:
+  DEFAULT_PERSONAL_ACCESS_KEY: ${{ secrets.HUBSPOT_PERSONAL_ACCESS_KEY }}
+  DEFAULT_ACCOUNT_ID: ${{ secrets.HUBSPOT_ACCOUNT_ID }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: HubSpot Create Test Account
+        id: test-account-create-step
+        uses: HubSpot/hubspot-project-actions/create-test-account@v1
+        with:
+          account_config_path: ./test-account-config.json
+      - name: HubSpot Project Upload
+        uses: HubSpot/hubspot-project-actions/project-upload@v1
+        with:
+          project_dir: ./my-project # optional
+          personal_access_key: ${{ steps.test-account-create-step.outputs.personal_access_key }}
+          account_id: ${{ steps.test-account-create-step.outputs.account_id }}
+```

create-test-account/action.yml

@@ -0,0 +1,62 @@
+name: "Create Test Account"
+description: "Create a new test account from a configuration file"
+inputs:
+  account_config_path:
+    description: "The path to the test account configuration file"
+    required: true
+    type: string
+  personal_access_key:
+    description: "[SECRET] Personal Access Key generated in HubSpot that grants access to the CLI. If not provided, will use DEFAULT_PERSONAL_ACCESS_KEY from environment."
+    required: false
+    type: string
+  account_id:
+    description: "HubSpot account ID associated with the personal access key. If not provided, will use DEFAULT_ACCOUNT_ID from environment."
+    required: false
+    type: number
+  cli_version:
+    description: "Version of the HubSpot CLI to install. If not provided, will use DEFAULT_CLI_VERSION from environment. If neither are found, defaults to `latest`."
+    required: false
+    type: string
+outputs:
+  personal_access_key:
+    description: "The personal access key of the created test account"
+    value: ${{ steps.create-test-account.outputs.personal_access_key }}
+  account_id:
+    description: "The account ID of the created test account"
+    value: ${{ steps.create-test-account.outputs.account_id }}
+runs:
+  using: "composite"
+  steps:
+    - name: Install HubSpot CLI
+      uses: ./install-hubspot-cli
+      with:
+        cli_version: ${{ inputs.cli_version }}
+    - name: Create new HubSpot test account
+      id: create-test-account
+      shell: bash
+      env:
+        HUBSPOT_PERSONAL_ACCESS_KEY: ${{ inputs.personal_access_key || env.DEFAULT_PERSONAL_ACCESS_KEY }}
+        HUBSPOT_ACCOUNT_ID: ${{ inputs.account_id || env.DEFAULT_ACCOUNT_ID }}
+      run: |
+        # Source shared utilities
+        . "$GITHUB_ACTION_PATH/../scripts/action-utils.sh"
+
+        # Validate account and personal access key
+        validate_account_and_personal_access_key
+
+        # Validate account config path
+        if [ ! -f "${{ inputs.account_config_path }}" ]; then
+          echo "Error: Test account config file not found at path: ${{ inputs.account_config_path }}"
+          exit 1
+        fi
+
+        # Run test-account create command
+        run_hs_command \
+          "hs test-account create --use-env --json --config-path '${{ inputs.account_config_path }}'" \
+          "true"
+
+        # Parse and set outputs
+        set_output_from_json "personal_access_key" ".personalAccessKey"
+        set_output_from_json "account_id" ".accountId"
+
+        echo "✅ Test account created successfully"

delete-test-account/README.md

@@ -0,0 +1,51 @@
+# `Delete Test Account` Action
+
+Deletes a HubSpot test account. This action is typically used to clean up test accounts after running tests.
+
+**Inputs:**
+
+- `test_account_id` (required): Account ID of the test account to be deleted.
+- `personal_access_key` (optional): Personal Access Key of the test account to be deleted. If not provided, will use DEFAULT_PERSONAL_ACCESS_KEY from environment.
+- `account_id` (optional): HubSpot account ID associated with the personal access key. If not provided, will use DEFAULT_ACCOUNT_ID from environment.
+- `cli_version` (optional): Version of the HubSpot CLI to install. If not provided, will look for `DEFAULT_CLI_VERSION` in environment. If neither are found, defaults to `latest`.
+
+**Outputs:**
+No outputs.
+
+**Example usage:**
+
+On every code push, create a new test account. Then delete it in the cleanup job. This will only attempt to cleanup the account if it was successfully created. It leverages the `account_id` output from the test account create action, and makes it available in the cleanup job by declaring it as output of the deploy job.
+
+```yaml
+on: [push]
+
+env:
+  DEFAULT_PERSONAL_ACCESS_KEY: ${{ secrets.HUBSPOT_PERSONAL_ACCESS_KEY }}
+  DEFAULT_ACCOUNT_ID: ${{ secrets.HUBSPOT_ACCOUNT_ID }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    outputs:
+      test_account_id: ${{ steps.test-account-create-step.outputs.account_id }}
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: HubSpot Create Test Account
+        id: test-account-create-step
+        uses: HubSpot/hubspot-project-actions/create-test-account@v1
+        with:
+          account_config_path: ./test-account-config.json
+
+  cleanup:
+    needs: deploy
+    if: always() && needs.deploy.outputs.test_account_id != ''
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+      - name: HubSpot Delete Test Account
+        uses: HubSpot/hubspot-project-actions/delete-test-account@v1
+        with:
+          test_account_id: ${{ needs.deploy.outputs.test_account_id }}
+```

delete-test-account/action.yml

@@ -0,0 +1,50 @@
+name: "Delete Test Account"
+description: "Delete a test account"
+inputs:
+  test_account_id:
+    description: "The account ID of the test account to delete"
+    required: true
+    type: string
+  personal_access_key:
+    description: "[SECRET] Personal Access Key generated in HubSpot that grants access to the CLI. If not provided, will use DEFAULT_PERSONAL_ACCESS_KEY from environment."
+    required: false
+    type: string
+  account_id:
+    description: "HubSpot account ID associated with the personal-access-key. If not provided, will use DEFAULT_ACCOUNT_ID from environment."
+    required: false
+    type: number
+  cli_version:
+    description: "Version of the HubSpot CLI to install. If not provided, will use DEFAULT_CLI_VERSION from environment. If neither are found, defaults to `latest`."
+    required: false
+    type: string
+runs:
+  using: "composite"
+  steps:
+    - name: Install HubSpot CLI
+      uses: ./install-hubspot-cli
+      with:
+        cli_version: ${{ inputs.cli_version }}
+    - name: Delete HubSpot test account
+      shell: bash
+      env:
+        HUBSPOT_PERSONAL_ACCESS_KEY: ${{ inputs.personal_access_key || env.DEFAULT_PERSONAL_ACCESS_KEY }}
+        HUBSPOT_ACCOUNT_ID: ${{ inputs.account_id || env.DEFAULT_ACCOUNT_ID }}
+      run: |
+        # Source shared utilities
+        . "$GITHUB_ACTION_PATH/../scripts/action-utils.sh"
+
+        # Validate account and personal access key
+        validate_account_and_personal_access_key
+
+        # Validate test account ID
+        if [ -z "${{ inputs.test_account_id }}" ]; then
+          echo "Error: test_account_id is required but was not set"
+          exit 1
+        fi
+
+        # Delete the test account
+        run_hs_command \
+          "hs test-account delete --use-env '${{ inputs.test_account_id }}'" \
+          "false"
+
+        echo "✅ Test account deleted successfully"