@appland/appmap 3.146.0 → 3.147.0

package/built/docs/setup-appmap-in-ci/in-circleci.md

@@ -0,0 +1,423 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Get started with AppMap and CircleCI for behavioral analysis in your test cases. Follow steps to sync files, set up GitHub Action, and analyze runtime code changes."
+name: Getting Started with CircleCI
+setup-appmap-ci: true
+step: 3
+render_with_liquid: false
+---
+
+# Getting Started with CircleCI <!-- omit in toc -->
+
+<p class="alert alert-info">
+If at any point you would like some help, <a href="/slack">join us in Slack</a>!
+You'll find the AppMap team there, along with other AppMap users.
+</p>
+
+- [How it works](#how-it-works)
+- [Step-by-step walkthrough](#step-by-step-walkthrough)
+  - [Prerequisites](#prerequisites)
+  - [Step 1: Setup AppMap file sync in existing CircleCI Project](#step-1-setup-appmap-file-sync-in-existing-circleci-project)
+  - [Step 2: Setup AppMap GitHub Action for baseline](#step-2-setup-appmap-github-action-for-baseline)
+  - [Step 3: Add AppMap to compare HEAD revision](#step-3-add-appmap-to-compare-head-revision)
+  - [Step 4: Merge Pull Request to enable AppMap](#step-4-merge-pull-request-to-enable-appmap)
+- [Example Project Files](#example-project-files)
+- [Advanced Configuration Options](#advanced-configuration-options)
+  - [Prerequisites](#prerequisites-1)
+  - [Step 1: Add or Update AppMap action to use `repository_dispatch` trigger](#step-1-add-or-update-appmap-action-to-use-repository_dispatch-trigger)
+  - [Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion.](#step-2-update-your-circleci-build-to-trigger-the-github-api-on-a-successfully-build-completion)
+- [Next Steps](#next-steps)
+
+## Overview <!-- omit in toc -->
+AppMap works with your test cases in CircleCI and a GitHub Action to collect, store, analyze, and report on the behavioral changes within each Pull Request. Tests can execute within your existing CircleCI build job, and AppMaps can be retrieved by a GitHub Action to analyze the code behavior changes. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-github-action.webp"/> 
+
+## How it works
+
+AppMap records the behavior of your test cases when they run in CircleCI and produces AppMap data that can be copied to a centralized storage repository. An additional step is added in your CircleCI build job to create a tarball of that data and push the resulting file to a centralized object storage or file storage of your control. From there, the AppMap GitHub Action will download those maps and analyze them. AppMap will add comments to your Pull Request with deep insights into the runtime code changes. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circleci-github-arch-diagram.webp"/> 
+
+In this example, the following events will happen:
+
+<b>1) CircleCI builds your application and runs automated test cases run with AppMaps created in `tmp/appmap` on the CircleCI runner.</b>
+- A tarball (`tar`) file of the `tmp/appmap` directory is created in the CircleCI runner.
+- This tarball is copied to your chosen centralized location (such as AWS S3 or Azure Blob Storage) for secure storage and retrieval by the AppMap GitHub Action.  
+  
+<b>2) While the CircleCI build is running, the AppMap GitHub Action will also trigger, looking for a baseline archive for comparison.</b>
+  - The AppMap GitHub Action waits until all the AppMaps exist on the central storage location before continuing.
+  - This will download the raw AppMaps created by CircleCI in your previous step to generate a baseline archive for comparison.
+
+<b>3) The GitHub Action will analyze the latest maps against the baseline for the pull request.  
+  - The AppMap GitHub Action will provide a full runtime code analysis diff report as a comment in your pull request.</b>
+
+## Step-by-step walkthrough
+
+### Prerequisites
+
+1) AppMap only supports project that have automated test cases. To add AppMap to your project, use either the [AppMap installer CLI](/docs/reference/appmap-client-cli.html#install) or manually add with the [AppMap libraries](/docs/reference).
+   
+2) A centralized storage location (such as Amazon S3 or Azure Blob Storage) for storing raw AppMaps generated from the test cases. This storage needs write access from CircleCI and read access from GitHub Actions. In this example below we will use Amazon S3.
+
+### Step 1: Setup AppMap file sync in existing CircleCI Project
+
+First, create a branch called `appmap-ci` in your project.  Next, in your CircleCI configuration (generally found at `.circle/config.yml`), add a run action that will create a (`tar`) of your AppMaps after your test cases are completed. 
+
+```yaml
+- run:
+    name: Create archive of AppMaps
+    command: tar --remove-files -cvzf <<pipeline.git.revision>>.tar tmp/appmap/
+```
+{: .example-code}
+
+Using the CircleCI pipeline value of `<<pipeline.git.revision>>` will give this archive tarball a unique file name based on the SHA the AppMaps are based on. 
+
+After the archive step, add the necessary steps to authenticate and copy this archive file to your centralized storage location. In our example below, we will authenticate with Amazon AWS to generate temporary credentials and then we will copy this file to the configured bucket.  In this example, copying the tarball to the `s3://circleci-appmaps/` bucket. 
+
+```yaml
+- aws-cli/setup:
+    profile_name: Circle-CI-Write-to-S3
+    role_arn: arn:aws:iam::12345678900:role/Circle-CI-Write-to-S3
+
+- aws-s3/copy:
+    from: <<pipeline.git.revision>>.tar
+    profile_name: Circle-CI-Write-to-S3
+    to: s3://circleci-appmap/
+    arguments: --region us-west-2
+```
+{: .example-code}
+
+[**Example Code Commit**](https://github.com/land-of-apps/circle-ci-example/commit/1b1f2e886c8ca0a166296147b083d3eb500a8c5f)
+
+After you push this commit to your branch, CircleCI will trigger a workflow and you can confirm that the steps all completed successfully.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circle-ci-example-storage.webp"/> 
+
+Once you have confirmed your AppMaps have successfully copied to your centralized file repository, merge this branch and continue to the next step.
+  
+### Step 2: Setup AppMap GitHub Action for baseline
+
+To setup the GitHub Action, create a new branch called `appmap-action` in your repository.
+
+Create a new file with the name `.github/workflows/appmap-analysis.yml`
+
+In this file you can use [this default action example](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L1-L77). **NOTE** Right now you will only use the first job that is listed in lines 1-77, after we create the baseline archive we'll add the AppMap job below this section.
+
+- Download the AppMap tooling into the runner.
+- Check for an existing baseline AppMap archive stored in your GitHub artifact store.
+- (If no baseline AppMap archive exists) Locate and download the tarball of AppMaps for the base revision from your chosen centralized data store.
+- (If no baseline AppMap archive exists) Create an AppMap archive of the baseline AppMaps and store to your GitHub artifact store.
+ 
+Commit your GitHub Action workflow file to your branch and open a new Pull Request which will trigger the action.
+
+After the action completes running successfully, check the action summary and confirm a build artifact has been created like the following screenshot.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/github-artifact-example.webp"/> 
+
+### Step 3: Add AppMap to compare HEAD revision
+ 
+After the previous step succeeds and the baseline AppMap data is created, [update the GitHub Action](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L79-L125) to include a similar job to fetch the AppMaps for the HEAD revision and additionally analyze the code changes for code quality problems and provide a detailed report into the pull request comments.  
+
+[Review this example commit](https://github.com/land-of-apps/circle-ci-example/pull/2/commits/4ea72bb9c930960dafd38698749a0b1dbc2e9db8) for an example of the additional steps to add to your GitHub Action.
+
+When the build completes successfully, you will see a comment from the GitHub Action.  After merging this Pull Request you will see a similar analysis on each new Pull Request.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/initial-report.webp"/> 
+
+Your completed installation should now look like the following [Pull Request Example.](https://github.com/land-of-apps/circle-ci-example/pull/2)
+
+### Step 4: Merge Pull Request to enable AppMap
+
+After you merge this Pull Request, AppMap will execute on each subsequent Pull Request.
+
+With AppMap deployed in your project, AppMap will execute on each Pull Request and provide a detailed runtime code analysis on each new commit.  AppMap performs a thorough analysis of the runtime differences, giving you:
+
+- Root cause analysis of failed tests.
+- Web service API changes, both breaking and non-breaking.
+- New and resolved security findings.
+- New and resolved performance findings.
+- New and resolved findings in other categories: maintainability, reliability, and user-defined rules.
+- "Behavioral diffs" as sequence diagrams showing changed runtime behavior within the PR.
+
+[Example Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14)
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-pull-request.webp"/>
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-checks-with-circleci.webp"/> 
+
+## Example Project Files
+
+- [Example Ruby on Rails Project](https://github.com/land-of-apps/rails-7-app/)
+- [Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14)
+- [CircleCI Example copying AppMaps to Amazon S3](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.circleci/config.yml#L34-L46)
+- [GitHub Action Workflow File](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml)
+
+## Advanced Configuration Options
+
+In our basic CircleCI example above, both the CircleCI test runner and the AppMap action will start running at the same time. The GitHub Action will check your central storage location every 10 seconds until your baseline maps and HEAD revision maps exist. For many projects where your test cases can complete in a short amount of time, this additional wait time in the AppMap GitHub Action is worth the cost for the simpler configuration to get started. 
+
+But if your test cases on CircleCi take longer to run, it can be inefficient and expensive to have a GitHub Action running and waiting for files to become available. You can use the GitHub API to trigger a webhook event called `repository_dispatch` when you want to trigger a workflow for activity that happens outside of GitHub. In our case after CircleCI has successfully finished running test and pushed the AppMap archive to the central file storage location. 
+
+Refer to the [GitHub Action documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#repository_dispatch) for more details about how the `repository_dispatch` action trigger works.
+
+The overall architecture largely stays the same as the basic example from above. You can see in the diagram below we've added a new step #2 where a CircleCI job will make a call to the GitHub API to trigger a webhook and start our updated GitHub Action. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/advanced-circleci-github-arch-diagram.webp"/> 
+
+### Prerequisites
+
+- [Create a GitHub Personal Access Token](https://docs.github.com/en/enterprise-server@3.8/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `repo` scope. This needs to be stored in your CircleCI account as an environment variable.
+- The `repository_dispatch` trigger will only run if your workflow file is on your main branch. As such, you'll need the ability to commit to your project main branch. 
+- Centralized storage setup and configured for access.  As the example above, you'll need write access from CircleCI and read access from GitHub Actions. In our example we'll be using Amazon S3.
+- This walkthrough assumes you have already completed the basic setup steps in the previous example. At the very least you need to ensure you've [completed Step 2](/docs/setup-appmap-in-ci/in-circleci.html#step-2-setup-appmap-github-action-for-baseline) and have a baseline AppMap archive ready for analysis. 
+
+### Step 1: Add or Update AppMap action to use `repository_dispatch` trigger
+
+For this updated GitHub Action to work you'll need to commit a software utility to your project that will locate which Pull Request your commit is associated with.  Normally when a Pull Request is opened, the AppMap Action will trigger and the action payload will include details about which Pull Request the AppMap report will be associated with.  But since our action will be triggered via a webhook, it will lack information about what Pull Request is associated with the commit. 
+
+#### Add `searchPullRequest.js` to your project <!-- omit in toc -->
+
+You can use this JavaScript function to locate the Pull Request for your commits, and pass the relevant pull request number to the AppMap GitHub Action. [Copy the latest version from the sample project](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js) and add to your project. 
+
+Add the following as a new file named `package.json` or add these project dependencies to your existing `package.json`
+
+```json
+{
+  "dependencies": {
+    "@octokit/rest": "^20.0.2",
+    "yargs": "^17.7.2"
+  }
+}
+```
+{: .example-code}
+
+#### Add/Update the AppMap Action to your project <!-- omit in toc -->
+
+The most recent version of the AppMap GitHub Action that can be triggered via a [webhook is located in our sample project.](https://github.com/land-of-apps/rails-7-app/blob/cca7f276cf7c32b4b7a5af218ccf19399084777a/.github/workflows/analyze-maps-from-circleci.yml) You'll need to commit this file (configured for your environment) and the files above into the main branch of your repository.  As with the above example you'll need to save this file into the `.github/workflows/` folder. 
+
+**Commit these files to your main branch and then continue to Step 2.**
+
+This action has many steps to process the files and analyze your pull requests, below are details of what each step is doing.
+
+* Reconfigure this environment variable to point to your specific central file location.
+  
+```yaml
+env:
+  appmap_storage_bucket: circleci-appmaps
+```
+{: .example-code}
+
+* Use this action to set the status of your Pull Request as "pending" for the commit being built.
+
+```yaml
+- name: Set commit status as pending
+  uses: myrotvorets/set-commit-status-action@f8a3f50eca0d32f3e12dc3a98792bb588bf29626
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    status: pending
+    context: AppMap Analysis
+    sha: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/appmap-analysis-status.webp"/> 
+
+
+* Install the AppMap command line tools, but do not install the libraries. 
+  
+```yaml
+ - name: Install AppMap tools
+   uses: getappmap/install-action@v1
+   with:
+     install-appmap-library: false
+```
+{: .example-code}
+
+* Check and see if the baseline AppMap archive exists in the GitHub artifact store. This will fail if an archive is not found so we enable `continue-on-error: true`
+  
+```yaml
+- name: Check for existing baseline archive
+  id: check_for_baseline
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+  continue-on-error: true  
+  run: |
+    appmap restore --check --revision ${base_sha} --github-repo ${GITHUB_REPOSITORY} --exact 
+```
+{: .example-code}
+
+* If the previous step "fails" (i.e. no baseline archive exists) run these steps to download raw AppMaps and archive them for analysis.
+
+```yaml
+- name: Download and extract appmaps
+  if: steps.check_for_baseline.outcome == 'failure'
+  run: | 
+    aws s3 cp s3://${appmap_storage_bucket}/${base_sha}.tar ${base_sha}.tar 
+    tar xvf ${base_sha}.tar
+    
+- name: Archive AppMaps
+  if: steps.check_for_baseline.outcome == 'failure'
+  uses: getappmap/archive-action@v1
+  with: 
+    revision: ${base_sha}
+```
+{: .example-code}
+
+The 2nd section in the GitHub AppMap Action will trigger when the above steps are successful. Below is an explanation of what each of those steps is used for. 
+
+* As in the previous example, reconfigure the storage bucket location based on where your AppMaps are located.
+
+```yaml
+env:
+  appmap_storage_bucket: circleci-appmaps
+```
+{: .example-code}
+
+* Install Node.js and the packages required to run the `searchPullRequest.js` application.
+  
+```yaml
+- name: Use Node.js
+  uses: actions/setup-node@v2
+  with:
+    node-version: '18'
+
+- name: Install dependencies
+  run: npm ci
+```
+{: .example-code}
+
+* Download and extract the HEAD revision AppMaps sent from CircleCI
+
+```yaml
+- name: Download and extract appmaps
+  run: | 
+    aws s3 cp s3://${appmap_storage_bucket}/${head_sha}.tar ${head_sha}.tar 
+    tar xvf ${head_sha}.tar
+```
+{: .example-code}
+
+* Run `searchPullRequest.js` and locate the most recent Pull Request with the HEAD sha associated. This value will be stored in $LATESTPR.
+
+```yaml
+- name: Get only the most recent issue with this head commit
+  run: echo LATESTPR=$(node searchPullRequest.js --ownerRepo=${GITHUB_REPOSITORY} --commit=${head_sha}) >> "$GITHUB_ENV"
+
+```
+{: .example-code}
+
+* Analyze the AppMaps and compare the changes between the base and head revisions, passing the `issue-number` to the analyze-action.  
+
+```yaml
+- name: Analyze AppMaps
+  uses: getappmap/analyze-action@v1
+  with:
+    issue-number: ${{env.LATESTPR}}
+    directory: .
+    base-revision: ${{ github.event.client_payload.base_sha }}
+    head-revision: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+* Update the commit status for this repository_dispatch build.
+
+```yaml
+- name: Update Commit Status
+ uses: myrotvorets/set-commit-status-action@v2.0.0
+ if: always()
+ with:
+   token: ${{ secrets.GITHUB_TOKEN }}
+   status: ${{ job.status }}
+   context: AppMap Analysis
+   sha: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+The commit status update will look like the following in a sucessful pull request.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/appmap-analysis-status-complete.webp"/> 
+
+Make sure to commit the [searchPullRequest.js](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js), the [package.json](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/package.json), and the Webhook AppMap GitHub Action before continuing to step 2.
+
+[Here is an example commit with the changes files in an example test project.](https://github.com/land-of-apps/circle-ci-example/commit/44bcfafbaf978484fc0d29e826d28161ded89ef6)
+
+### Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion.  
+
+For an example of a full CircleCI workflow, [refer to the latest version from our sample project.](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.circleci/config.yml)
+
+In our example, we'll modify the CircleCI build runner from our basic example, and add a new build job called `run_appmap_analysis` which will only trigger on non-mainline code commits after the normal build succeeds.  
+
+We don't need to trigger the Webhook based AppMap Action on a mainline branch build because analysis only happens inside of an existing Pull Request. 
+
+First we can create a new job in our existing `.circleci/config.yml` file. 
+
+You'll need to update the following items according to your project:
+
+- Ensure your GitHub Personal Access Token is saved as a CircleCI secure environment variable at `$GITHUB_PAT`
+- Update the URL for triggering the `repository_dispatch` project.  The format is: `https://api.github.com/repos/{ORGNAME}/{REPONAME}/dispatches`
+- [Confirm the name of your `repository_dispatch`](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.github/workflows/analyze-maps-from-circleci.yml#L3-L7) action and update the `"event_type": "run_appmap_analysis",` accordingly. 
+
+```yaml
+run_appmap_analysis:
+  docker:
+    - image: cimg/ruby:3.1.2
+
+  steps:
+    - checkout
+
+    - run:
+        name: Get base Git SHA
+        command: echo 'export BASE_SHA=$(git merge-base origin/main $CIRCLE_BRANCH)' >> $BASH_ENV
+
+    - run:
+        name: Run AppMap Analysis
+        command: |
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github.v3+json" \
+            -H "Authorization: token $GITHUB_PAT" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/land-of-apps/rails-7-app/dispatches \
+            -d @- \<<EOF 
+          {
+            "event_type": "run_appmap_analysis",
+            "client_payload": {
+              "base_sha": "$BASE_SHA",
+              "head_sha": "<< pipeline.git.revision >>"
+            }
+          }
+          EOF
+```
+{: .example-code}
+
+In your CircleCI workflow declaration section. Update the jobs so that the GitHub webhook job will only run after the build job and excluding your mainline branch. 
+
+```yaml
+workflows:
+  build:
+    jobs:
+      - build
+      - run_appmap_analysis:
+          requires:
+            - build
+          filters:
+            branches:
+              ignore:
+                - main
+```
+{: .example-code}
+
+Now, create a new Pull Request with these changes and on your next CircleCI build, you'll see that the `run_appmap_analysis` job will execute after your normal build step.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circleci-build-example.webp"/> 
+
+For more details refer to this [example Pull Request](https://github.com/land-of-apps/circle-ci-example/pull/3) and [commit changes](https://github.com/land-of-apps/circle-ci-example/pull/3/commits/8c328130e0572a0eee9b9a0e0b1b2d73e3909ebc) for this sample project. 
+
+When you view your project's GitHub Actions page, you'll see the `workflow_dispatch` action trigger after CircleCI completes its build after it has uploaded the AppMaps to your centralized data store.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/github-action-webhook-example.webp"/> 
+
+## Next Steps
+
+AppMap comes with a comprehensive set of rules that are categorized by their impact on applications: Performance, Reliability, Maintainability, Stability, and Security.  [Refer to the AppMap documentation](/docs/setup-appmap-in-ci/in-github-actions.html#configure-additional-appmap-analysis-rules) to learn how to configure these rules for your project. 

package/built/docs/setup-appmap-in-ci/in-github-actions.md

@@ -0,0 +1,177 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Learn how to leverage AppMap within GitHub Actions to analyze behavioral changes in Pull Requests. Install AppMap and configure rules for enhanced performance and security."
+name: Getting Started with GitHub Actions
+setup-appmap-ci: true
+step: 2
+render_with_liquid: false
+redirect_from: [/docs/early-access/in-github-actions,/docs/analysis/in-github-actions]
+---
+
+# Getting Started with GitHub Actions <!-- omit in toc -->
+
+<p class="alert alert-info">
+If at any point you would like some help, <a href="/slack">join us in Slack</a>!
+You'll find the AppMap team there, along with other AppMap users.
+</p>
+
+<p class="alert alert-success">
+Make sure to <a href="https://github.com/marketplace/get-appmap">install the AppMap App from the GitHub Marketplace</a> before you start the installation process.
+</p>
+
+<a class="btn btn-primary btn-lg" href="https://getappmap.com/setup/">Install AppMap for GitHub Actions</a>
+
+## Overview <!-- omit in toc -->
+AppMap can work within GitHub Actions to collect, store, analyze, and report on the behavioral changes within each Pull Request. AppMap will analyze the changes in your application on each pushed commit or pull request. AppMap performs a thorough analysis of the runtime differences, giving you:
+
+- Root cause analysis of failed tests.
+- Web service API changes, both breaking and non-breaking.
+- New and resolved security findings.
+- New and resolved performance findings.
+- New and resolved findings in other categories: maintainability, reliability, and user-defined rules.
+- "Behavioral diffs" as sequence diagrams showing changed runtime behavior within the PR.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-github-action.webp"/> 
+
+## Step-by-step walkthrough
+
+  - [Step 1: Install the AppMap GitHub App from the GitHub Marketplace.](#step-1-install-the-appmap-github-app-from-the-github-marketplace)
+  - [Step 2: Choose an Installation Method](#step-2-choose-an-installation-method)
+  - [Step 3: Grant Access to your repositories.](#step-3-grant-access-to-your-repositories)
+  - [Step 4: Complete the Installation Process](#step-4-complete-the-installation-process)
+  - [Step 5: Merge this PR to deploy AppMap](#step-5-merge-this-pr-to-deploy-appmap)
+- [Optional Post-Install Configuration](#optional-post-install-configuration)
+  - [Configure Additional AppMap analysis rules](#configure-additional-appmap-analysis-rules)
+
+Configuration of the AppMap GitHub Action happens inside a branch and can be easily tested in a Pull Request before merging any code changes to the mainline branch.  This allows users to easily test AppMap in the environment before deploying across the repository.  
+
+Follow the steps below for your project. If you need additional assistance contact AppMap at [support@appmap.io](mailto:support@appmap.io) or join us in our [Community Slack](https://appmap.io/slack)
+
+### Step 1: Install the AppMap GitHub App from the GitHub Marketplace.
+
+<a class="btn btn-primary btn-lg" href="https://github.com/marketplace/get-appmap">Click to install the AppMap GitHub Action</a>
+
+Installing the AppMap GitHub App into your repository will allow the AppMap installer to properly detect your repositories for installation. Your data is your data, AppMap does not store your code or any AppMaps that are generated. For more details about AppMap security controls, review the [Security FAQ](https://appmap.io/security).
+
+### Step 2: Choose an Installation Method
+
+AppMap runs as a GitHub Action in your project. Add AppMap to a project with an existing GitHub workflow that runs tests successfully. Choose if you would like to install AppMap manually into your project or use the automated AI assisted installation.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/manual-or-ai-installer.webp"/> 
+
+### Step 3: Grant Access to your repositories.
+Granting AppMap access to your repositories allows AppMap to complete an automated installation for your project. For the automated installation to be successful you'll need an existing GitHub workflow which builds and tests your application successfully.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/authorize-appmap.webp"/> 
+
+*Note*: If you do not currently have a GitHub Action that can run your test cases, refer to the [GitHub documentation](https://docs.github.com/en/actions/quickstart) to build an Action that will execute your test cases.  
+
+### Step 4: Complete the Installation Process
+
+Follow the steps in the AppMap installation process to complete the AppMap Installation. AppMap will add a Configuration Report as a comment in the initial pull request. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/config-report.webp"/> 
+
+The initial AppMap report will give you details about:
+
+- **AppMap data sources** shows how many AppMaps were recorded, and which test frameworks were used.
+- **Code profile** indicates which packages and modules were recorded.
+- **Web service API profile** summarizes the HTTP requests observed while your tests ran. AppMap uses this information to automatically generate OpenAPI definitions.
+- **SQL profile** summarizes the SQL queries executed in your tests.
+
+After completing the initial configuration report, AppMap will analyze your entire source code repository. In this report AppMap will display recently introduced code flaws and problems. A sample of all the problems that were found in the AppMaps are listed in order of when they were most likely introduced, with most recent first.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/appmap-project-summary.webp"/> 
+
+### Step 5: Merge this PR to deploy AppMap
+Congratulations! You’ve successfully set up the AppMap GitHub Action and can now merge this into your project to make it available for every other developer to use on each of their subsequent pull requests. 
+
+ To see AppMap in action, create a draft pull request with some changes that you don't plan to merge. Some suggested changes include:
+
+- Add a new test
+- Add, change, or remove an API route
+- Change how your application interacts with its database
+
+AppMap will execute runtime code analysis on every pull request in this repository. 
+
+<div class="video-container">
+  <video playsinline loop autoplay muted>
+    <source src="/assets/img/docs/gh-action/action-report-summary.mp4" type="video/mp4">
+  </video>
+</div>
+
+## Optional Post-Install Configuration
+
+### Configure Additional AppMap analysis rules 
+
+AppMap comes with a comprehensive set of rules that are categorized by their impact on applications: Performance, Reliability, Maintainability, Stability, and Security.
+
+You can refer to the [AppMap Documentation](/docs/reference/analysis-rules) for more information about all the rules that are available within AppMap.  
+
+To enable additional rules simply add them to an `appmap-scanner.yml` file in the root of your project directory and commit it to your project. 
+
+This is a sample `appmap-scanner.yml` file which you can use to enable or disable certain AppMap analysis rules. Rules can be disabled by commenting them out with the `#` character.
+
+```yaml
+checks:
+  - rule: authz-before-authn
+  # - rule: circular-dependency
+  - rule: deprecated-crypto-algorithm
+  - rule: deserialization-of-untrusted-data
+  - rule: exec-of-untrusted-command
+  - rule: http-500
+  # - rule: illegal-package-dependency
+  #   properties:
+  #     callerPackages:
+  #       - equal: actionpack
+  #     calleePackage:
+  #       equal: app/controllers
+  # - rule: incompatible-http-client-request
+  # - rule: insecure-compare
+  # - rule: job-not-cancelled
+  - rule: logout-without-session-reset
+  # - rule: missing-authentication
+  - rule: missing-content-type
+  - rule: n-plus-one-query
+  # - rule: query-from-invalid-package
+  # - rule: query-from-view
+  # - rule: rpc-without-circuit-breaker
+  # - rule: save-without-validation
+  - rule: secret-in-log
+  # - rule: slow-function-call
+  #   properties:
+  #     timeAllowed: 0.2
+  #     functions:
+  #       - match: Controller#create$
+  # - rule: slow-http-server-request
+  #   properties:
+  #     timeAllowed: 0.5
+  # - rule: slow-query
+  #   properties:
+  #     timeAllowed: 0.05
+  - rule: too-many-joins
+  - rule: too-many-updates
+  # - rule: unbatched-materialized-query
+  - rule: unauthenticated-encryption
+  - rule: update-in-get-request
+```
+{: .example-code}
+
+Add these changes to Git and commit and put them into the PR branch.
+
+```bash
+$ git add .
+$ git commit -m "ci: Add customized scanner configuration"
+```
+{: .example-code}
+
+Push the changes upstream to your branch which updates the Pull Request.
+```bash
+$ git push
+```
+{: .example-code}
+
+The AppMap analysis report will be updated on the completion of the build and a new report will be displayed. 
+
+For more details about AppMap GitHub Actions refer to the [reference documentation](/docs/reference/github-action)

package/built/docs/setup-appmap-in-ci/index.md

@@ -0,0 +1,22 @@
+---
+layout: docs
+title: Set up AppMap in CI
+description: "Learn to set up AppMap in CI using GitHub Actions or CircleCI. Explore how it works, example projects, and troubleshooting tips."
+redirect_from: [/docs/analysis/integrating-with-ci/]
+---
+
+# Set up AppMap in CI
+
+<p class="alert alert-info">
+If at any point you would like some help, <a href="/slack">join us in Slack</a>!
+You'll find the AppMap team there, along with other AppMap users.
+</p>
+
+<a class="btn btn-primary btn-lg" href="https://github.com/marketplace/get-appmap">Get Started with our GitHub integration</a>
+
+- [How it works](/docs/setup-appmap-in-ci/how-it-works)
+- [Getting Started with GitHub Actions](/docs/setup-appmap-in-ci/in-github-actions)
+- [Getting Started with CircleCI](/docs/setup-appmap-in-ci/in-circleci)
+- [Example Projects](/docs/setup-appmap-in-ci/example-projects) 
+- [Matrix Builds](/docs/setup-appmap-in-ci/matrix-builds)
+- [Troubleshooting](/docs/setup-appmap-in-ci/troubleshooting)