Getting Started with GitHub Actions

If at any point you would like some help, join us in Slack! You'll find the AppMap team there, along with other AppMap users.

Get Started with our GitHub integration

Overview

AppMap Analysis 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.

• Step-by-step walkthrough
  • Step 0: Install the AppMap GitHub App from the GitHub Marketplace.
  • Step 1: Create an initial baseline AppMap Inventory Report
  • Step 2: Add the Build Triggers and Analysis Step
  • (Optional) Step 3: Remove Installation Actions and Configuration
  • Step 4: Merge this PR to deploy AppMap
• Optional Post-Install Configuration
  • Configure Additional AppMap analysis rules

Step-by-step walkthrough

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 or join us in our Community Slack

Step 0: Install the AppMap GitHub App from the GitHub Marketplace.

Click to install the AppMap GitHub Action

Step 1: Create an initial baseline AppMap Inventory Report

AppMap operates by running as a GitHub action in your project. Ideally, you’ll have an existing GitHub workflow which can setup a testing environment and execute your tests successfully. Start by cloning your project to your local machine. Next, create a branch called appmap-ci, and make copy of the existing GitHub workflow.

Note: If you do not currently have a GitHub action that can run your test cases, refer to the GitHub documentation to build an Action that will execute your test cases.

Save a copy of your existing GitHub workflow as: .github/workflows/appmap-analysis.yml

Set the name of the action and set the action to run on a Pull Request, on a push to your mainline, and on a schedule to keep the archive updated and available.

name: appmap-analysis

on:
  pull_request:
  push:
    branches:
      - main # Change this to the name of the mainline branch
  schedule:
    - cron: '0 0 * * 0'

Create or modify your permissions settings to allow the AppMap GitHub action the correct permissions to interact with your project. These permissions should be added at the top level of your workflow file.

permissions:
  # Read the baseline artifact in order to perform the AppMap comparison.
  actions: read
  # Commit the AppMap configuration.
  # If the EndBug/add-and-commit is removed, this can be changed to 'read'.
  contents: write
  # Add check annotations to the source code when a problem is detected.
  checks: write
  # Add a comment to the pull request.
  pull-requests: write

In the GitHub action actions/checkout command, you need to modify the default option to include the with: ref: ${{ github.event.pull_request.head.ref }} option which tells the Action to checkout the branch so the later Action can commit AppMap configuration files to the working branch.

- uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.ref }}

Add the following command in your Action before the command which runs your tests. The install-appmap action will install AppMap software libraries and a default appmap.yml configuration file, and the add-and-commit action will commit this file to your branch so AppMaps can be generated in your project.

- name: Install AppMap tools
  uses: getappmap/install-action@v1
  with:
    project-type: # Choose the type of your project here:
                  # bundler, maven, gradle, pip, pipenv, poetry,
                  # yarn, npm, etc.
- name: Commit changes
  uses: EndBug/add-and-commit@v9

In the section after the command which runs your test cases, add this command to archive a baseline of the AppMaps.

- name: Archive AppMaps
  uses: getappmap/archive-action@v1
  with:
    revision: ${{ github.event.pull_request.base.sha }}

If your project uses a matrix-build setup to run tests across multiple runners, refer to the multi-runner matrix build documentation before completing Step 1.

To see complete examples of AppMap in GitHub actions refer to our example projects on GitHub.

Commit the change:

$ git add .
$ git commit -m "ci: Bootstrap initial AppMap archive"

Push the changes upstream to your branch and open a new Pull Request which will trigger the GitHub action. Once the build of this PR completes, AppMap will comment on the PR with an initial report about your software project.

The initial AppMap report will give you details about:

• Runtime Analysis: Analyzing the AppMap data for security flaws and anti-patterns
• REST API analysis For AppMaps that include HTTP server requests, AppMap can automatically generate OpenAPI definitions.
• SQL Profile When your code makes a SQL query, AppMap records the SQL query in detail. It even parses the queries to figure out which tables your app is using, and how it’s using them.

Step 2: Add the Build Triggers and Analysis Step

Now that we have created the initial baseline of AppMaps, replace the Archive AppMaps action at end of your GitHub Action configuration with a Save AppMaps job which saves AppMaps to the GitHub cache for later use.

Finally, add a workflow call to the reference AppMap workflow file. It will be nested at the same level as the test: job.

Replace this block

- name: Archive AppMaps
  uses: getappmap/archive-action@v1
  with:
    revision: ${{ github.event.pull_request.base.sha }}

with this block.

      - name: Save AppMaps
        uses: actions/cache/save@v3
        if: always()
        with:
          path: ./tmp/appmap
          key: appmaps-${{ github.sha }}-${{ github.run_attempt }}

Finally, add this block at end of your action with the same nesting level as the test: job.

  appmap-analysis:
    if: always()
    needs: [test] # You may need to change this to match the name of the step that runs your tests.
    uses: getappmap/analyze-action/.github/workflows/appmap-analysis.yml@v1
    permissions:
      actions: read
      contents: read
      checks: write
      pull-requests: write

Pull the latest commit made by the previous GitHub Action workflow run

$ git pull

Commit the changes:

$ git add .
$ git commit -m "ci: Add build triggers and analysis step"

Push the changes upstream to your branch.

$ git push

To see complete examples of AppMap in GitHub actions refer to our example projects on GitHub.

After the build completes, AppMap will post details of the Analysis build into your pull request.

If your pull request report shows changes to code behavior or new AppMaps (when no changes are made), you may have some non-deterministic tests. For additional help resolving this, please contact the AppMap engineering team via email or join the AppMap Community Slack.

(Optional) Step 3: Remove Installation Actions and Configuration

Now that AppMap configuration files are included in your project, you no longer need the permissions block at the top of your action (unless required for other actions), install-action, and add-and-commit actions in your project. If they are left in place your project will always update to the latest released versions of AppMap libraries. Remove the following lines to have more control over future software updates.

Unless needed for other Actions in your workflow, delete this section added in Step 1:

permissions:
  actions: read
  contents: write
  checks: write
  pull-requests: write

These actions can also be removed.

- name: Install AppMap tools
  uses: getappmap/install-action@v1
  with:
    project-type: # Choose the type of your project here:
                  # bundler, maven, gradle, pip, pipenv, poetry,
                  # yarn, npm, etc.
- name: Commit changes
  uses: EndBug/add-and-commit@v9

Finally, you can set your checkout action back to the default.

- name: Checkout
  uses: actions/checkout@v3

After removing those Actions, add and commit to your branch.

$ git add .
$ git commit -m "ci: Remove installation actions"

Push the changes upstream to your branch.

$ git push

Step 4: 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.

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 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.

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

Add these changes to Git and commit and put them into the PR branch.

$ git add .
$ git commit -m "ci: Add customized scanner configuration"

Push the changes upstream to your branch which updates the Pull Request.

$ git push

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