@appland/appmap 3.133.0 → 3.134.0

package/built/docs/reference/jetbrains.md

@@ -0,0 +1,119 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: AppMap for JetBrains
+step: 2
+---
+
+# AppMap for JetBrains
+
+- [AppMap tool window](#appmap-tool-window)
+- ["Start with AppMap" for Java](#start-with-appmap-for-java)
+  - [Create AppMaps from JUnit test runs](#create-appmaps-from-junit-test-runs)
+    - [Disable specific JUnit tests](#disable-specific-junit-tests)
+  - [Running a Java application with AppMap](#running-a-java-application-with-appmap)
+- [Remote recording](#remote-recording)
+- [AppMap Plugin actions](#appmap-plugin-actions)
+- [Generate OpenAPI Definitions](#generate-openapi-definitions)
+- [Troubleshooting](#troubleshooting)
+- [GitHub repository](#github-repository)
+
+## AppMap tool window
+
+The AppMap tool window shows all AppMaps in your open projects. You can open it from the top level menu (`View -> Tools Windows -> AppMaps`), with an AppMap action or by clicking on its tab in the UI.
+
+<img class="intellij-screenshot" src="/assets/img/intellij-appmap-tool-window.webp"/>
+
+AppMap tool window actions:
+
+- Alphabetical listing of all AppMaps in the project, sorted by name.
+- Double-click on any AppMap to open it.
+- Search for an AppMap by its name.
+- Start/stop [remote recordings](#remote-recording).
+- View the Quickstart guide.
+
+## "Start with AppMap" for Java
+
+**NOTE:** This section only applies to Java applications.
+
+Installing the AppMap JetBrains plugin adds custom buttons and menu options to the JetBrains editor interface. These can be used to run your Java application code with AppMap automatically configured, saving you from manually changing your Maven or Gradle settings. This is the recommended approach for all Java users using JetBrains editors like IntelliJ.
+
+For exmaple, if you right click on your main class file you'll see a new menu item under "More Run/Debug" to `Start with AppMap`. Selecting this option will start your application with the AppMap libraries enabled.  From here, you can interact with your application to generate [request recordings](/docs/reference/appmap-java.html#requests-recording) or use [remote recording](#remote-recording)
+
+<img class="intellij-screenshot" src="/assets/img/jetbrains-run-main-with-appmap.webp"/>
+
+You can also use this custom button to run a specific test or group of tests with the `Start with AppMap` option. Similar to above, right click on a single test or a group of tests and use the custom button under "More Run/Debug" to `Start with AppMap`.
+
+<img class="intellij-screenshot" src="/assets/img/jetbrains-run-test-with-appmap.webp"/>
+
+{% include vimeo.html id='916087828' %}
+
+### Create AppMaps from JUnit test runs
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Open your test file in the editor. Each method marked with JUnit's `@Test` annotation will produce an AppMap.
+3. Run the test(s) with AppMap by clicking the icon next to the test class and then selecting "Start with AppMap", or by clicking the AppMap run configuration button:
+<img class="intellij-screenshot" src="/assets/img/run-config-test.png"/>
+
+#### Disable specific JUnit tests
+
+To disable recording for a particular JUnit test (for example, a performance
+test), list the class or methods under `exclude` in the project's `appmap.yml` configuration file.
+
+### Running a Java application with AppMap
+
+When you run a Java application with the AppMap agent, [remote recording](/docs/recording-methods.html#remote-recording) will be enabled. (Note: For this to work, your application must include a web server).
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Open your application file in the editor.
+3. Run your application with AppMap by clicking the icon next to the main class you wish to run and then selecting "Start with AppMap", or by clicking the AppMap run configuration button:
+<img class="intellij-screenshot" src="/assets/img/run-config-start.png"/>
+1. With the application running, follow the [remote recording](#remote-recording) instructions below to (starting at step 3) create AppMaps.
+
+## Remote recording
+
+You can make a [remote recording](../recording-methods#remote-recording) from within the JetBrains IDE. 
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Start your application with remote recording enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details.
+3. To start a recording, click the remote recording button, or use the command **Start AppMap recording**. 
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-start.png"/>
+4. Enter the URL where your application is running.
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-url.png"/>
+5. Interact with your app through its UI or API. Then click the button to stop the recording, or use the command **Stop AppMap recording**. 
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-stop.png"/>
+6. You'll be prompted to save the AppMap to a file, and it will be opened.
+<img class="intellij-screenshot" src="/assets/img/docs/intellij-remote-save.png"/>
+
+For more details about remote recording, see:
+
+* [Recording methods > Remote recording](/docs/recording-methods)
+* [Remote recording API](../reference/remote-recording-api)
+
+## AppMap Plugin actions
+
+To open the list of AppMap plugin actions, press `CTRL+SHIFT+A` on Windows and Linux, or `COMMAND+SHIFT+A` on macOS, and type `AppMap`. You can also find these actions at `Tools > AppMap` of the main menu.
+
+The command names should be self-explanatory. 
+
+## Generate OpenAPI Definitions
+
+After [recording AppMaps](/docs/recording-methods.html) for your project, select "Generate OpenAPI" from the AppMap instructions quick start in the lower right hand column. 
+
+![Generate OpenAPI Link](/assets/img/openapi/jetbrains-1.webp)
+
+Selecting the "Generate OpenAPI Definitions" button will open a new file with your OpenAPI definition document to save locally, share with your team or use with 3rd party API management tools [like Postman](https://blog.postman.com/new-postman-integration-with-appmap-create-and-manage-always-accurate-collections/)
+
+![OpenAPI Generation Screen](/assets/img/openapi/jetbrains-2.webp)  
+
+## Troubleshooting
+
+#### Downloading plugin logs
+
+AppMap technical support may ask you for your IDE logs to diagnose issues with the plugin's behavior. If so, go to the `Help` menu in your editor and select `Collect Logs and Diagnostic Data`. This will create a `.zip` file on your local machine and open a file explorer window to it. You can then safely send that file to AppMap within your technical support ticket conversation.
+
+## GitHub repository
+
+[https://github.com/getappmap/appmap-intellij-plugin](https://github.com/getappmap/appmap-intellij-plugin)

package/built/docs/reference/license-key-install.md

@@ -0,0 +1,73 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+step: 17
+name: License Key Installation
+---
+
+# AppMap Code Editor license key installation
+
+After receiving your AppMap license key follow the steps below. 
+
+For the license key to successfully validate with AppMap systems ensure your machine is able to connect to <a href="https://getappmap.com">https://getappmap.com</a>. You can test by opening it in your web browser.
+
+- [VS Code license key install steps](#vs-code-license-key-install-steps)
+- [JetBrains license key install steps](#jetbrains-license-key-install-steps)
+
+## VS Code license key install steps
+
+1) Open the VS Code Command Palette
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+2) Search for `AppMap license`
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-1.webp"/> 
+
+3) Enter the license key provided by the AppMap team and press `Enter` to submit
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-2.webp"/> 
+
+4) Click `Allow` to allow the AppMap extension to use your license key.
+
+<img class="video-screenshot" src="/assets/img/license-key-vscode-3.webp"/> 
+
+5) AppMap will be activated for Visual Studio Code.
+
+<br/>
+
+## JetBrains license key install steps
+
+1) Select `Tools` from the main menu of your JetBrains Code Editor. Then select `AppMap` -> `Enter License Key`.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-1.webp"/> 
+
+2) Enter the license key provided by the AppMap team and press `Ok` to submit.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-2.webp"/> 
+
+3) You will now be logged into AppMap for the IDE.
+
+<img class="video-screenshot" src="/assets/img/license-key-jetbrains-3.webp"/> 
+
+### JetBrains Install Video Demo
+
+<div class="video-container" onclick="JetBrainsplayVideo()">
+  <img id="JetBrainsvideoPlaceholder" src="/assets/img/appmap-license-jetbrains-placeholder.webp" style="display:block; width: 100%;">
+  <video id="JetBrainsvideoPlayer" playsinline loop style="display:none;">
+    <source src="/assets/video/appmap-license-key-jetbrains.webm" type="video/webm">
+    <source src="/assets/video/appmap-license-key-jetbrains.mp4" type="video/mp4">
+  </video>
+</div>
+
+<script>
+  function JetBrainsplayVideo() {
+    var video = document.getElementById('JetBrainsvideoPlayer');
+    var placeholder = document.getElementById('JetBrainsvideoPlaceholder');
+    placeholder.style.display = 'none';
+    video.style.display = 'block';
+    video.play();
+  }
+</script>

package/built/docs/reference/remote-recording-api.md

@@ -0,0 +1,97 @@
+---
+layout: docs
+title: Docs - Reference
+toc: false
+reference: true
+name: Remote recording API
+step: 10
+redirect_from: [/docs/reference/remote-recording]
+---
+
+# Remote recording API
+
+- [Remote recording API](#remote-recording-api)
+  - [Start a remote recording](#start-a-remote-recording)
+  - [Retrieve the current recording status](#retrieve-the-current-recording-status)
+  - [Stop a remote recording](#stop-a-remote-recording)
+  - [Save recorded AppMaps to disk](#save-recorded-appmaps-to-disk)
+
+When an application is set up for AppMap recording, the AppMap agent injects itself into the web stack and handles the remote recording HTTP requests, accepting requests on the same port as the web interface of the application.
+
+For example, if you deployed your application to a local Tomcat server listening on port 8080, call the remote recording endpoints at `http://localhost:8080/_appmap/*` 
+
+##  Start a remote recording
+
+```
+POST /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This endpoint returns `200` if a new recording session was started successfully or `409` if an existing recording session was already in progress. It returns an empty body in the response.
+
+**curl example:**
+
+```
+curl -H 'Accept: application/json' -sXPOST http://localhost:8080/_appmap/record
+```
+
+## Retrieve the current recording status
+
+```
+GET /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This endpoint returns status `200` .
+
+AppMap recording status is returned in the response body, the "enabled" property is set to `true` when recording is in progress:
+
+```
+Content-type: application/json
+{
+  "enabled": boolean
+}
+```
+
+**curl example:**
+
+```
+curl -H 'Accept: application/json' -sXGET http://localhost:8080/_appmap/record
+```
+
+## Stop a remote recording
+
+```
+DELETE /_appmap/record
+```
+{: .example-code}
+
+No payload in the request is expected.
+
+This method returns `200` If an active recording session was stopped successfully, and the body contains AppMap JSON, or `404` If there was no active recording session to be stopped.
+
+If successful, the recorded AppMap is returned in the response body.
+
+```
+Content-type: application/json
+{
+  "version": "1.x",
+  "metadata": {},
+  "classMap": [],
+  "events": [],
+}
+```
+
+**curl example:**
+```
+curl -H 'Accept: application/json' -sXDELETE http://localhost:8080/_appmap/record -o MyFirstAppMap.appmap.json
+```
+
+## Save recorded AppMaps to disk
+
+Save the returned payload to disk as an `.appmap.json` file. We recommend that the AppMap file be named after the recorded test and that additional metadata is added to the recorded AppMap prior to saving, such as the AppMap’s name or labels indicating the test outcome and framework. See the [AppMap specification](https://github.com/getappmap/appmap#appmap-data-specification) for details about AppMap metadata.
+

package/built/docs/reference/uninstalling-appmap.md

@@ -0,0 +1,109 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: Uninstalling AppMap
+step: 18
+---
+
+# Uninstalling AppMap
+AppMap consists of several components, each of which may require a different uninstall approach depending on what changes were made to your applications during installation.
+
+- [Uninstalling AppMap](#uninstalling-appmap)
+  - [Uninstalling AppMap IDE Plugins](#uninstalling-appmap-ide-plugins)
+    - [Uninstalling the AppMap VS Code Extension](#uninstalling-the-appmap-vs-code-extension)
+    - [Uninstalling the AppMap JetBrains Plugin](#uninstalling-the-appmap-jetbrains-plugin)
+  - [Removing AppMap libraries from your application](#removing-appmap-libraries-from-your-application)
+    - [Ruby](#ruby)
+    - [Java](#java)
+    - [Python](#python)
+  - [Removing AppMap-generated files from your project](#removing-appmap-generated-files-from-your-project)
+
+## Uninstalling AppMap IDE Plugins
+
+### Uninstalling the AppMap VS Code Extension
+To uninstall AppMap from VS Code, first select the Extensions control to view your installed extensions. 
+<img class="video-screenshot" src="/assets/img/docs/extensions-vsc.png"/>
+
+Next, find and select `AppMap` in the list of installed extensions. Then click the `Uninstall` button to remove the AppMap extension from your editor.
+<img class="video-screenshot" src="/assets/img/docs/uninstall-vsc.png"/>
+
+Finally, if your project supports AppMap [Launch Configurations](https://appmap.io/docs/reference/vscode.html#run-with-appmap-for-java), you can now remove the AppMap specific details in the `.vscode/launch.json` and the `.vscode/settings.json` files. 
+
+<img class="video-screenshot" src="/assets/img/docs/launch-configuration-uninstall.webp"/>
+
+<p class="alert alert-info">
+Please note that even after uninstalling the IDE extension, your project may still be configured to load an AppMap library and continue to record maps when your application is run. You should follow the language-specific uninstall instructions below to remove the AppMap library from your project.
+</p>
+
+### Uninstalling the AppMap JetBrains Plugin
+To uninstall AppMap from JetBrains editors like IntelliJ and PyCharm, open your editor's `Settings` panel from the main menu. Select `Plugins` on the left panel, then find and select `AppMap` in the list of installed plugins. Then click the `Uninstall` button to remove the AppMap extension from your editor.
+<p>
+<img class="video-screenshot" src="/assets/img/docs/plugins-jetbrains.webp"/>
+</p>
+
+<p class="alert alert-info">
+Please note that even after uninstalling the IDE plugin, your project may still be configured to load an AppMap library and continue to record maps when your application is run. You should follow the language-specific uninstall instructions below to remove the AppMap library from your project.
+</p>
+
+## Removing AppMap libraries from your application
+Removing AppMap from your application typically involves removing the AppMap library from your project's dependencies. Language-specific instructions on how to do this are below.
+
+### Ruby
+Use the `bundle` command to remove the AppMap library from your project:
+
+{: .example-code}
+
+```console
+$ bundle remove appmap
+```
+Alternatively, manually remove the line containing `appmap` from the top of your Gemfile. 
+
+### Java
+For IntelliJ users, the act of uninstalling the AppMap plugin from the IDE is enough to fully remove AppMap configuration from your project. 
+
+VS Code users should remove the AppMap launch commands from the files `launch.json` and `settings.json`, both located in the `.vscode` folder.
+
+If you had also installed the [AppMap Maven plugin](https://appmap.io/docs/reference/appmap-maven-plugin.html), you should remove the appropriate AppMap `<plugin>` definition from your `pom.xml`. Similarly, if you had installed the [AppMap Gradle plugin](https://appmap.io/docs/reference/appmap-gradle-plugin.html#installation), you should remove the AppMap `plugins` section from your `build.gradle` or `build.gradle.kts` file.
+
+### Python
+Remove AppMap using your Python dependency manager:
+
+{: .example-code}
+
+```console
+Using pip:
+$ pip uninstall appmap
+
+Using poetry:
+$ poetry remove appmap
+
+Using pipenv:
+$ pipenv uninstall appmap
+```
+
+Also, if your project contains a `requirements.txt` file, you should remove `appmap` from that file too.
+
+### Node.js
+Your Node project dependencies were not modified to use AppMap. Simply changing your application's launch command
+to no longer prepend `npx appmap-node` is enough to stop using AppMap.
+
+## Removing AppMap-generated files from your project
+If you had generated AppMaps, you will have a number of files in your project folder that can safely be removed after completing the uninstall steps above. This is an optional step.
+
+Start by removing the AppMap configuration file:
+
+{: .example-code}
+
+```console
+$ rm appmap.yml
+```
+
+Finally, remove any generated AppMap files from your project:
+
+{: .example-code}
+
+```console
+$ rm -r tmp/appmap
+```

package/built/docs/reference/vscode.md

@@ -0,0 +1,125 @@
+---
+layout: docs
+title: Docs - Reference
+toc: true
+reference: true
+name: AppMap for Visual Studio Code
+step: 1
+---
+
+# AppMap for Visual Studio Code
+
+- [AppMap panel](#appmap-panel)
+  - [Instructions](#instructions)
+  - [AppMaps tree view](#appmaps-tree-view)
+  - [Runtime Analysis](#runtime-analysis)
+  - [Code Objects](#code-objects)
+- ["Run with AppMap" for Java](#run-with-appmap-for-java)
+- [Extension actions](#extension-actions)
+- [Remote recording](#remote-recording)
+- [Generate OpenAPI Definitions](#generate-openapi-definitions)
+- [GitHub repository](#github-repository)
+
+## AppMap panel
+
+### Instructions
+
+Step-by-step instructions for configuring a project to use AppMap and using the main features.
+
+Once you've configured AppMap for a project, commit the file changes to Git so that your colleagues don't have to do the setup themselves.
+
+### AppMaps tree view
+
+The AppMap view shows all AppMaps in your open projects. You can open it from the top level menu (View -> Open view... -> AppMap), with an AppMap action or by clicking on its icon in the side bar.
+
+AppMaps are organized by how they were created (request recording, remote recording, test case recording).
+
+Within the AppMap tree view you can
+
+* Click on any AppMap name to open the diagram
+* Right-click for a context menu
+
+You can also use the tree view buttons to Filter the AppMap tree by name, or search for a specific AppMap. There are also extension commands to do this.
+
+### Runtime Analysis
+
+AppMap can find automatically find software design flaws that impact security, performance, stability, and maintainability. When a problem is found, it's listed here. Click on the problem to get detailed information about it.
+
+### Code Objects
+
+All the HTTP server requests, SQL queries, packages, classes, and functions that are present in an AppMap are listed here in a tree view. You can navigate through these code objects to see what's present in your project. Click on any code object to open the AppMaps that contain it.
+
+## "Run with AppMap" for Java
+
+**NOTE:** This section only applies to Java applications.
+
+Installing the AppMap VC Code plugin adds a default [Launch Configuration](https://code.visualstudio.com/docs/editor/debugging) which supports the integrated VS Code debugger. These can be used to run your Java application code with AppMap automatically configured, saving you from manually changing your Maven or Gradle settings. This is the recommended approach for all Java users using the VS Code editor.
+
+To run your tests with AppMap enabled, navigate to the `Testing` section of VS Code in the left hand menu icons. If your project has tests you will see them listed in the following screen. From here, click on the `Run Tests` icon, highlighted in the screenshot below. This will kick off your test cases with the AppMap libraries installed and enabled. 
+
+<img class="video-screenshot" src="/assets/img/vscode-run-with-tests.webp"/> 
+
+To run your applicaiton with AppMap enabled, navigate to the `Run and Debug` section of VS Code in the left hand menu icons. You will see a new launch configuration in the in the drop down which says `Run with AppMap` alongside any other launch configurations for your project.  With the `Run with AppMap` launch configuration select click on the "Play" icon, highlighted in the screenshot below. This will start your applicaiton with the AppMap libraries installed and enabled.  You can now interact with your application to generate [request recordings](/docs/reference/appmap-java.html#requests-recording) or use [remote recording](#remote-recording).
+
+<img class="video-screenshot" src="/assets/img/vscode-run-with-appmap.webp"/> 
+
+### Video Demo
+
+{% include vimeo.html id='916087851' %}
+
+After installing the VS Code AppMap extension for your Java project, you will notice a new launch configuration in the `.vscode` directory in your project. 
+
+<img class="video-screenshot" src="/assets/img/docs/vscode-launch-configuration.webp"/> 
+
+Next, click on the "Run and Debug" menu option in the left hand column of VS Code
+
+<img class="video-screenshot" src="/assets/img/docs/vscode-run-and-debug.png"/> 
+
+Clicking on the "Play" button next to the "Run with AppMap" launch configuration will start your Java application with the necessary AppMap configuration flags enabled by default. 
+
+When your application is running you can proceed to record AppMaps using either [Requests Recording](/docs/reference/appmap-java#requests-recording) or [Remote Recording](https://appmap.io/docs/reference/vscode.html#remote-recording)
+
+
+## Extension actions
+
+To open the list of AppMap extension actions, press `CTRL+SHIFT+P` or `COMMAND+SHIFT+P` on macOS and type `AppMap`. 
+
+Most of the command names should be self-explanatory. Here are a few commands which are a bit more complicated:
+
+- **AppMap: Filter/Find AppMap by name** Opens the AppMap side bar view and the filter/find text field
+- **AppMap: Login**, **AppMap: Logout** Some extension functionality requires you to login to the AppMap Server. You'll be prompted to do this when you setup AppMap for the first time. You can also login and logout using the built-in `Accounts` feature of VSCode.
+- **AppMap: Touch Out-of-Date Test Files** If you have AppMaps that are generated from test cases, this command will determine which tests need to be re-run in order to bring the AppMaps up-to-date. It will then "touch" (update the modified date) of each out-of-date test case. You can use a file watching trigger program like `Guard` (Ruby), `grunt` or `gulp` (JS) to re-run the test cases as they are touched.
+- **AppMap: Copy Out-of-Date Tests to Clipboard** Similar to the "Touch Out-of-Date Test Files" command, but places the file names on the clipboard
+- **AppMap: Open Code Object in AppMap** Using this command you can find and open AppMaps for any code object (package, class, function, route, etc) in your project.
+
+## Remote recording
+
+You can make a [remote recording](../recording-methods#remote-recording) from within the VSCode IDE. First, start your application with remote recording enabled. Exactly how to do this depends the language you're using - consult the [agent reference](/docs/reference) for details.
+
+To start a recording, click the remote recording button, or use the command **AppMap: Start a Remote Recording**.
+
+![Start remote recording](/assets/img/docs/vscode-remote-start.png)
+
+Interact with your app through its UI or API. Then use the stop remote recording button again, or use the command **AppMap: Stop the Remote Recording**. 
+
+![Stop remote recording](/assets/img/docs/vscode-remote-stop.png)
+
+You'll be prompted to save the AppMap to a file, and it will be opened.
+
+![Prompt remote recording](/assets/img/docs/vscode-remote-save.png)
+
+For more details about remote recording, see:
+
+* [Recording methods > Remote recording](../recording-methods#remote-recording)
+* [Remote recording API](../reference/remote-recording-api)
+
+## Generate OpenAPI Definitions
+
+After [recording AppMaps](/docs/recording-methods.html) for your project, open the command pallette using `CTRL+SHIFT+P` or `COMMAND+SHIFT+P` on macOS, type `AppMap: Generate OpenAPI`, then hit `Enter`. This will open a new file with your OpenAPI definition document. Save this file locally, share with your team, or ingest as a [new collection into API tools like Postman.](https://blog.postman.com/new-postman-integration-with-appmap-create-and-manage-always-accurate-collections/)
+
+![alt_text](/assets/img/openapi/openapi-1.webp "OpenAPI export to file")
+
+
+## GitHub repository
+
+[https://github.com/getappmap/vscode-appland](https://github.com/getappmap/vscode-appland)

package/built/docs/setup-appmap-in-ci/example-projects.md

@@ -0,0 +1,20 @@
+---
+layout: docs
+title: Set up AppMap in CI
+name: Example Projects
+setup-appmap-ci: true
+step: 4
+redirect_from: [/docs/setup-appmap-in-ci/in-github-actions.html#workflow-examples]
+---
+
+## Workflow examples
+
+Reference implementations of the AppMap GitHub Action are available for the following languages and frameworks:
+
+* [**Ruby on Rails**](https://github.com/land-of-apps/sample_rails_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Ruby on Rails w/ Matrix Build**](https://github.com/land-of-apps/sample_rails_matrix_build/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Java Spring**](https://github.com/land-of-apps/sample_spring_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Java Spring w/ multiple sub-projects**](https://github.com/land-of-apps/waltz/blob/appmap-analysis/.github/workflows/appmap-analysis.yml)
+* [**Python Django**](https://github.com/land-of-apps/django-oscar/blob/appmap/.github/workflows/appmap-analysis.yml)
+* [**Python w/ Matrix Build**](https://github.com/land-of-apps/sample_django_app/blob/appmap/.github/workflows/appmap-analysis.yml)
+* **Node.js** Coming soon!

package/built/docs/setup-appmap-in-ci/how-it-works.md

@@ -0,0 +1,42 @@
+---
+layout: docs
+setup-appmap-ci: true
+title: Set up AppMap in CI
+step: 1
+name: How it works
+redirect_from: [/docs/analysis/in-ci]
+---
+# Set Up AppMap in CI
+
+AppMap Analysis can work with your Continuous Integration (CI) system 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 - breaking and non-breaking - via comparison of generated OpenAPI definitions.  
+* 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.  
+
+<p class="alert alert-info">
+Install the <a href="https://github.com/marketplace/get-appmap" target="_blank">AppMap GitHub App</a> on the GitHub Marketplace to get started now!
+</p>
+
+The AppMap Analysis GitHub actions can run cooperatively or independently of your existing CI job. 
+For example, AppMap Analysis can run as a GitHub Action even if you do not use GitHub Actions as your CI system.
+
+AppMap Analysis runs entirely within your existing GitHub account and does not send code or data to an external or 3rd-party server. For more information, refer to the [AppMap Security FAQ](https://appmap.io/security).
+
+Once you create a pull request, AppMap data is recorded as your test cases run. As AppMaps are generated, an AppMap archive file is created that includes all the AppMap data, plus some metadata about the job. As code is pushed to a branch, AppMap Analysis create an archive file for that code revision. This archive file is automatically saved as a CI artifact.  Once an archive has been created, it can be compared to the “base” revision (i.e. your mainline or production branch).  
+1
+## The value of AppMap in CI
+
+We designed AppMap’s findings as a comment in the PR itself to enable the Development, QA, Architecture, and Security teams to review code faster, evaluate code independently, and catch deep-rooted code issues easier. This helps you determine the stability of new code in the context of where the code actually lives and allows for faster and more reliable code delivery. 
+
+By simply browsing the PR comments, a DevOps team can reliably deploy code with the assurance that it meets all needed code quality requirements, reducing the amount of unnecessary communication between teams just to get the code live long before it is ever pushed to production.
+
+## Requirements
+If you have already generated AppMaps outside of CI (for example, by running your test cases locally), you can quickly deploy AppMap in CI using the same commands used to execute your test cases. If you already have an existing CI job that builds an environment to execute your test cases, AppMap Analysis can be added to that job.
+
+## Next steps
+- [Add to GitHub Actions](/docs/analysis/in-github-actions)