Integration with CI/CD

Your existing test suite is an amazing source of data when recorded and analyzed with AppLand. By following the steps shown here, you will generate AppMaps from your automated tests and upload them to AppLand. In so doing, you'll automatically create an up-to-date knowledge base about your application's development history, branches, and versions.

Once you've configured your CI/CD system to automatically generate and upload AppMaps, your application will contain the latest scenarios for each branch of your code. When a new mapset is uploaded for an existing branch, old mapsets on that branch are automatically deleted.

Before you continue, you should complete the setup instructions on your local machine to Create AppMaps and Upload to AppLand. You should also have a continuous integration (CI) job configured to build and test your project.

Once you've done these things, you can continue with the instructions.

The AppLand Command Line tools must be available in your testing environment.

How you install the command line tools is up to you. For instance, you may download the tools in a pre-build step, or use a Docker image which has the command line tools built in.

Configure your build job to provide the environment variables APPLAND_URL and APPLAND_API_KEY at runtime. These environment variables enable the AppLand Command Line tools to authenticate with the AppLand server.

To generate an API key for use by your CI/CD system:

Then export APPLAND_URL and APPLAND_API_KEY :

export APPLAND_API_KEY=<API Key> \
       APPLAND_URL=https://app.land

You can manage all your API keys from the account page .

Make sure your application is configured properly to be recorded. If you haven't already, follow the client setup instructions to learn how to configure your application and record tests.

Once your application is configured, modify your test build step to generate AppMaps for the test cases that you want to record. The most useful tests to record are integration or functional tests that exercise the whole application stack.

Once the tests have completed, the CLI can be used to upload appmaps.

$ appmap upload --branch "${BRANCH_NAME}" --environment ci --no-open *.appmap.json

In the example above, the --branch/-b flag is provided to link the AppMaps to the Git branch the tests were run on. If branch refs are available this flag can be omitted.

The --no-open flag instructs the CLI not to open the web browser after a successful upload.

The --environment flag tells AppLand that the AppMaps are coming from an official CI/CD system, rather than from a developer's local environment. Passing this flag enables auto-deletion of older mapsets on the same branch.

Note that the name of the BRANCH_NAME variable will vary depending on which build system you use. For Travis CI, it's called TRAVIS_PULL_REQUEST_BRANCH .

The directory containing your AppMaps will vary depending on how you configured the job. For Java, the default output directory is the build directory. For Ruby, the default output directory for RSpec tests is tmp/appmap/rspec .

Once you've got the basics working, you may want to take it one step further with these more advanced options.

Build all branches

Most CI/CD systems are configured by default to build pull requests. This means that by default, you'll get AppMaps for pull request branches, but not for the main master branch.

To get AppMaps of each change to the master branch, configure your CI/CD system to build all push events, rather than just pull requests.

For information about building push events vs pull requests with Travis CI, see How Pull Requests are Built .

Record application version numbers

When you release an official version of your app, you can mark the mapset with the version number. This way, you can always have access to a record of the specific application behavior for each released version of your code. This can be very helpful for analyzing bugs in old versions, and for settling debates about whether an older version of your code contained a particular feature or not!

Versioned mapsets are never automatically deleted.