docs: Updated shared services documentation to match new deployment process. (#43)

Author: jamesiarmes

docs/assets/app-deployment-workflow.yaml

@@ -29,7 +29,7 @@ jobs:
     environment: ${{ inputs.environment }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v4
         with:
@@ -64,11 +64,19 @@ jobs:
             --name  /$APPLICATION/$ENVIRONMENT/web/version \
             --value "$IMAGE_TAG" \
             --overwrite
+      - name: Get a deployment token
+        uses: actions/create-github-app-token@v2
+        id: token
+        with:
+          app-id: ${{ secrets.DEPLOYMENT_APP_ID }}
+          private-key: ${{ secrets.DEPLOYMENT_APP_KEY }}
+          owner: codeforamerica
+          repositories: shared-services-infra
       - name: Trigger deployment from shared services
-        uses: codex-/return-dispatch@v2
+        uses: codex-/return-dispatch@v3
         id: dispatch
         with:
-          token: ${{ secrets.DEPLOYMENT_PAT }}
+          token: ${{ steps.token.outputs.token }}
           ref: ${{ inputs.shared_services_ref || 'main' }}
           repo: shared-services-infra
           owner: codeforamerica
@@ -86,7 +94,7 @@ jobs:
           workflow: ${{ steps.dispatch.outputs.run_id }}
       - name: Fail unless the workflow succeeded
         if: ${{ steps.waiter.outputs.conclusion != 'success' }}
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             core.setFailed('Deployment workflow completed with stats: ${{ steps.waiter.outputs.conclusion }}')

docs/services/hosting/deployment-workflow.md

@@ -30,29 +30,54 @@ Follow the steps below to add the workflow to your repository:
 1. Add your additional build steps, as needed, before the
    `Build and push Docker image` step
 
-## Environment
+## Secrets and variables
 
 > [!TIP]
-> The DevOps team will create the initial environment for you and set the
-> appropriate secrets and variables. You can then modify the environment as
-> needed.
+> The DevOps team will set the appropriate secrets and variables documented
+> below. You can add additional secrets and variables that shoudl be synced to
+> GitHub.
 
-For this workflow to function correctly, you will need to set up one or more
-environments for it be run against. The environment should include the following
-secrets and variables:
+We use [Doppler] to manage secrets across projects and environments. If you
+don't already have a Doppler project and environment, one will be created for
+you. Secrets from the `ci` environment will be synced to GitHub Environments
+for use in GitHub Actions.
 
-### Secrets
+In addition to the secrets added directly to the `ci` environment, an
+[inherited config][config-inheritance] will be added, which will add the values
+needed to deploy the application.
 
-| Name                    | Description                                                           |
-|-------------------------|-----------------------------------------------------------------------|
-| `AWS_ACCESS_KEY_ID`     | AWS access key ID with access to the shared services environment.     |
-| `AWS_SECRET_ACCESS_KEY` | AWS secret access key with access to the shared services environment. |
+### Direct secrets
 
-### Variables
+The following secrets are used push container images, and update the version
+SSM parameter. They are unique to your project and environment and provide
+minmal access.
 
-| Name         | Description                                                      |
-|--------------|------------------------------------------------------------------|
-| `AWS_REGION` | The AWS region where the shared services environment is located. |
+| Name                      | Description                                                           |
+|---------------------------|-----------------------------------------------------------------------|
+| `AWS_ACCESS_KEY_ID`       | AWS access key ID with access to the shared services environment.     |
+| `AWS_SECRET_ACCESS_KEY`   | AWS secret access key with access to the shared services environment. |
+
+
+### Inherited secrets
+
+These secrets are inherited from the shared services project and managed by the
+DevOps team. They allow your repository to trigger the application deployment
+workflow on the sahred services repository.
+
+| Name                  | Description                                          |
+|-----------------------|------------------------------------------------------|
+| `DEPLOYMENT_APP_ID`   | ID of the GitHub App used for authorization.         |
+| `DEPLOYMENT_APP_KEY`  | Private key to authenticate with the GitHub App.     |
+
+### Inherited variables
+
+Like the secrets above, these variables are inherited from teh shared services
+project. They represent insecure values necessary to identify the target of
+deployments.
+
+| Name          | Description                                                      |
+|---------------|------------------------------------------------------------------|
+| `AWS_REGION`  | The AWS region where the shared services environment is located. |
 
 ## How it works
 
@@ -106,6 +131,8 @@ sequenceDiagram
 --8<-- "docs/assets/app-deployment-workflow.yaml"
 ```
 
+[config-inheritance]: https://docs.doppler.com/docs/config-inheritance
+[doppler]: https://www.doppler.com/
 [review]: usage.md#review-and-setup
 
 [^1]: By default, the new version is based on the latest SHA. You may want to

docs/services/hosting/usage.md

@@ -22,8 +22,11 @@ that describes the application, its containers, volumes, and other settings.
 The DevOps team will review the pull request and, once approved, will create
 resources in your repository that will allow you to deploy your application.
 
-- A repository secret named `DEPLOYMENT_PAT` that will be used to start the
-  shared services deployment workflow
+> [!NOTE]
+> The GitHub environment and secrets mentioned below are managed by Doppler.
+
+- Environment secrets named `DEPLOYMENT_APP_ID` and `DEPLOYMENT_APP_KEY` will
+  be used to start the shared services deployment workflow
 - A `development` environment, if one does not already exist, that will be used
   to build and push updated docker images for the application
 - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment secrets that are