GitHub integration
for continuous flaw scanning

AppMap provides a GitHub status check for your CI flow to ensure that pull requests meet crucial performance, security, and quality requirements before they are merged and deployed to production.

Prerequisites

The AppMap ci command is integrated with the testing step of your build job in CI.

Connect AppMap Server and GitHub

Connecting your AppMap org to your GitHub org is required to get continuous AppMap status checks.

1. Go to your account settings on AppMap Server and select an AppMap organization. This will bring you to the settings page for that AppMap organization.

click on organization

2. Under Third party integrations click the Install button. This will bring you to the app installation page on GitHub.

click install

3. Select the GitHub organization you want to map to your AppMap organization.

select a github org

4. GitHub will make you aware of what minimal permissions are required by AppMap Server to provide the status check, and ask you to select a repository (or repositories) to report on. Select projects that are being scanned by AppMap Analysis in ci.

github permissions

Upon granting access you will be automatically redirected back to AppMap Server.

5. On AppMap Server navigate to the application you want to link the repository you selected in the previous step, and click on the settings icon next to the application name. This will bring you to the settings page for that application.

app settings icon

6. In the Third party integrations pane select which GitHub repository you want to track.

select a repo

AppMap is now linked to your GitHub repository.

Triggering a GitHub status check

Assuming that the AppMap ci command is integrated into the test step of your build job, then any time a PR is opened or updated, AppMap Analysis will scan the code, push any findings to AppMap Server and update the associated commit status in GitHub.

github status check

Note: When uploading findings to AppMap Server, branch and commit information will be resolved from the environment if possible. If you have a non-standard configuration, or you’re running locally, you may provide these values yourself using the -b and -C options to specify the branch and commit details, respectively. For example:

npx @appland/scanner ci --appmap-dir tmp/appmap -C $(git rev-parse HEAD) -b $(git branch --show-current)

Managing findings to turn PR status to green

The best way to remove a finding and get the AppMap status check to pass is to update the code to fix the behavior that generated the finding. If a PR is updated to fix a finding , it will trigger another AppMap Analysis scan, and (assuming there are no other findings) the status check will then pass.

Clicking on the details link of the AppMap commit status will bring you to AppMap Server and show you the detailed results of the scan that generated the findings.

click on details

Here you can choose to defer findings to be addressed later.

change status to deferred

Deferring a finding will automatically update the status of the PR.

Making AppMap a required check by updating your setting in GitHub

  1. Go to the Settings for your repository.
  2. In the left menu, click Branches.
  3. Click add rule
  4. Enter the name of the branch you want to protect in the Branch name field.
  5. Under Protect matching branches, check Require status checks to pass before merging.

Suspending or Uninstalling the Integration

  1. Go to account settings and click on the organization you want to unlink from AppMap
  2. Click on manage in “Third party integrations”
  3. Select the GitHub org which you want to uninstall from
  4. Scroll down to the bottom of the page in Danger Zone and click to suspend or uninstall

See the Integrating with CI (Basic) guide for details.


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!