{"id":28961741,"url":"https://github.com/getappmap/archive-action","last_synced_at":"2025-06-24T02:04:50.621Z","repository":{"id":149303391,"uuid":"621503302","full_name":"getappmap/archive-action","owner":"getappmap","description":"GitHub action to build and store an AppMap archive","archived":false,"fork":false,"pushed_at":"2023-11-01T14:02:12.000Z","size":8016,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-20T19:09:22.835Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getappmap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-03-30T19:51:02.000Z","updated_at":"2024-02-29T21:40:33.000Z","dependencies_parsed_at":"2023-04-07T12:46:52.882Z","dependency_job_id":"f0b1f11b-69a3-49fb-8137-1fabfb404c56","html_url":"https://github.com/getappmap/archive-action","commit_stats":null,"previous_names":["getappmap/archive-appmap-action"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/getappmap/archive-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Farchive-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Farchive-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Farchive-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Farchive-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getappmap","download_url":"https://codeload.github.com/getappmap/archive-action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getappmap%2Farchive-action/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261589912,"owners_count":23181437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-24T02:04:49.804Z","updated_at":"2025-06-24T02:04:50.540Z","avatar_url":"https://github.com/getappmap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# getappmap/archive-appmap \u003c!-- omit from toc --\u003e\n\n\u003e To get started with AppMap in GitHub actions, you need to start by installing the\n\u003e [AppMap App on the official GitHub Marketplace](https://github.com/marketplace/get-appmap)\n\u003e\n\u003e To see a step-by-step example of how to install this action into your software project,\n\u003e [review the official AppMap Documentation](http://appmap.io/docs/analysis/in-github-actions).\n\n`getappmap/archive-action` is a GitHub Action used during initial setup of AppMap in CI to create a\nConfiguration report. It's also used in matrix builds to create an archive of AppMaps on a worker\nnode and save them to the GitHub cache. Finally, it's used when a PR is merged (both in matrix and\nnon-matrix mode) to build and store a baseline artifact. This is also done on a schedule (cron) to\nensure that the artifacts don't expire and disappear.\n\n`getappmap/archive-action/merge` is an action used to merge AppMaps created in a matrix build into\none unified archive.\n\n_Note_ Default GitHub artifact expiration is 90 days. This is a configurable GitHub org or project\nsetting.\n\n## Table of contents \u003c!-- omit from toc --\u003e\n\n- [Requirements](#requirements)\n- [Inputs](#inputs)\n  - [`getappmap/archive-action`](#getappmaparchive-action)\n  - [`getappmap/archive-action/merge`](#getappmaparchive-actionmerge)\n- [Effects](#effects)\n  - [Creation of artifact 'appmap-archive-full'](#creation-of-artifact-appmap-archive-full)\n  - [Submission of PR comment 'AppMap configuration report'](#submission-of-pr-comment-appmap-configuration-report)\n- [Examples](#examples)\n  - [Initial Setup (`pull_request` workflow trigger)](#initial-setup-pull_request-workflow-trigger)\n  - [Matrix Build (`pull_request` workflow trigger)](#matrix-build-pull_request-workflow-trigger)\n- [Development](#development)\n\n## Requirements\n\n1. Your project must be configured to run tests with AppMap enabled.\n   [`getappmap/install-action`](https://github.com/getappmap/install-action) is a companion GitHub\n   Action that can be used to do this automatically. For more information about how to setup AppMap\n   in your project\n   [review the official AppMap Documentation](http://appmap.io/docs/analysis/in-github-actions).\n2. `getappmap/archive-action` needs to run AFTER your test cases have executed, so that there will\n   be AppMaps for it to process.\n\n## Inputs\n\n### `getappmap/archive-action`\n\nAdd a step like this to your workflow:\n\n```yaml\n- name: Archive AppMaps\n  uses: getappmap/archive-action@v1\n  with:\n    # Command working directory. Use this option this to install AppMap to a\n    # subdirectory of a monorepo / multi-folder project. When this input is specified,\n    # AppMaps that project will be written to the directory `$directory/tmp/appmap`.\n    # Be aware of this in any subsequent steps.\n    # Default: '.'\n    directory: ./projects/backend\n\n    # 0-based numerical id of a matrix job. This id is used to store the AppMap\n    # archive in the action cache. Once the matrix jobs complete, the `merge`\n    # action can be used to merge the archives into a single archive, and then\n    # save it as an artifact. If `archive-id` is set, the archive is saved to the\n    # cache. Otherwise, it's uploaded to the artifact store. For a non-matrix\n    # job, `archive-id` should not be used.\n    # Required for Multi-runner matrix builds.\n    archive-id: ${{ matrix.ci_node_index }}\n\n    # Revision (commit SHA) to name the AppMap archive with. The default is the\n    # GITHUB_SHA. Under normal circumstances, the default value is correct\n    # and this input does not need to be specified.\n    revision: 6056b0cfbacd562f4a4f274122c4a5e85542e040\n\n    # The GitHub token to used to interact with GitHub Caches, Pull Requests, etc.\n    # Default: `${{ github.token }}`\n    github-token: secrets.CUSTOM_GITHUB_TOKEN\n\n    # Number of worker threads to use for processing the archive. Defaults to the\n    # number of CPUs / cores, as reported by Node.js. If the worker machine has\n    # a high number of CPUs/cores, the archive action may become I/O-bound rather\n    # than CPU-bound, and better performance might be obtained by setting this\n    # value to a lower number.\n    # Default: One worker thread for each core.\n    thread-count: 4\n\n    # Enable verbose logging of CLI subcommands. You can use the standard GitHub\n    # Action log level option to control verbosity of this Action itself.\n    # Default: false\n    verbose: true\n```\n\n### `getappmap/archive-action/merge`\n\nAdd a step like this to your workflow.\n\n```yaml\n- name: Merge AppMaps\n  uses: getappmap/archive-action/merge@v1\n  with:\n    # Command working directory. Use this option this to install AppMap to a\n    # subdirectory of a monorepo / multi-folder project. When this input is specified,\n    # AppMaps that project will be written to the directory `$directory/tmp/appmap`.\n    # Be aware of this in any subsequent steps.\n    # Default: '.'\n    directory: ./projects/backend\n\n    # Revision (commit SHA) to name the AppMap archive with. The default is the\n    # GITHUB_SHA. Under normal circumstances, the default value is correct\n    # and this input does not need to be specified.\n    revision: ${{ github.event.pull_request.base.sha }}\n\n    # Set this equal to the total number of test runners (i.e. total archives created)\n    archive-count: 2\n\n    # Enable verbose logging of CLI subcommands. You can use the standard GitHub\n    # Action log level option to control verbosity of this Action itself.\n    # Default: false\n    verbose: true\n```\n\n## Effects\n\n### Creation of artifact 'appmap-archive-full'\n\nBoth `getappmap/archive-action` and `getappmap/archive-action/merge` create an AppMap archive file,\nwhich is a compressed TAR file. `getappmap/archive-action` uploads the archive to the GitHub\nartifact store, unless it's running in matrix mode (), in which case the archive is stored to the\nGitHub Actions cache. `getappmap/archive-action/merge` always uploads the archive to the GitHub\nartifact store.\n\nThe archive is named for the commit SHA that was used to generate it. For example, if the commit SHA\nis `6056b0cfbacd562f4a4f274122c4a5e85542e040`, the archive will be named\n`appmap-archive-full_6056b0cfbacd562f4a4f274122c4a5e85542e040.tar`.\n\nDuring initial setup, the `getappmap/archive-action` is run by a pull request workflow trigger, and\nthe revision is the base revision of the pull request. During ongoing operation, the\n`getappmap/archive-action` is run either by a `push` trigger on merge to the main branch, or by a\nschedule (cron) trigger, and the revision is the HEAD revision of the main or pull request\nintegration branch (e.g. `main`, `master`, `develop`).\n\nYou can view all artifacts created by a workflow by visiting the `Actions` tab in GitHub and looking\nfor the `Summary` section.\n\n![Archive action artifacts](artifacts.png)\n\n**Note** The AppMap archive will be retained for the default retention period specified in your\nGitHub account.\n\n### Submission of PR comment 'AppMap configuration report'\n\nWhen `getappmap/archive-action` is run in a pull request context with the `revision` equal to\n`${{ github.event.pull_request.base.sha }}`, it will submit a comment to the pull request entitled\n`AppMap configuration report`.\n\n![AppMap configuration report](configuration_report.png)\n\nFor a live example, see this\n[sample Django (Python) pull request](https://github.com/land-of-apps/sample_django_app/pull/9#issuecomment-1768614384).\n\nThe `AppMap configuration report` primarily provides confirmation that the initial setup step of\nconfiguring the project to run tests with AppMap was successful. It also provides information about\nwhat type of information has been recorded in the AppMaps, such as:\n\n- Which code has been recorded.\n- What HTTP server requests routes have been observed.\n- What SQL queries have been observed.\n\n**Note** Creation of this PR comment requires the permission `pull-requests: write`.\n\n## Examples\n\n### Initial Setup (`pull_request` workflow trigger)\n\nThis example is used during installation to build an AppMap archive based on the base SHA of the\nsetup Pull Request:\n\n```yaml\n- name: Archive AppMaps\n  uses: getappmap/archive-action@v1\n  with:\n    revision: ${{ github.event.pull_request.base.sha }}\n```\n\n### Matrix Build (`pull_request` workflow trigger)\n\nThis example shows how to use the archive actions in a matrix build to archive the AppMaps on each\nworker node, then to combine them together for analysis.\n\nTo learn more about how to setup a multi-build matrix runner with AppMap refer to the\n[AppMap Documentation](https://appmap.io/docs/setup-appmap-in-ci/matrix-builds.html)\n\nUse the `archive-id` when building a multi-runner matrix build. Set the `archive-id` equal to the\nunique index ID of the runner which executed the build. For example, if you have split your runners\nwith the following strategy.\n\n```yaml\nstrategy:\n  fail-fast: false\n  matrix:\n    ci_node_total: [2]\n    ci_node_index: [0, 1]\n```\n\nIn this example, you will use the `matrix.ci_node_index` variable to set either `0` or `1` as the\nunique node index ID for the `archive-id`.\n\n**NOTE:** The `if: always()` is used to ensure that the AppMap Archive is generated even if there\nare failed test cases. The failed test cases will be included in the AppMap analysis report. Since\nthe `archive-id` is being passed to the action, the `archive-action` will save the AppMaps from this\nrunner to the GitHub build cache. After this step you will use the `archive-action/merge` action to\nmerge and archive AppMaps as a build asset.\n\n```yaml\n- name: Archive AppMaps\n  if: always()\n  uses: getappmap/archive-action@v1\n  with:\n    archive-id: ${{ matrix.ci_node_index }} # Set this equal to the unique index of the runner\n```\n\nIn a build job after all multi-runners have completed, use this to merge and archive the individual\nrunners maps. This `getappmap/archive-action/merge@v1` action will both merge and archive the\nAppMaps.\n\n```yaml\n- name: Merge AppMaps\n  uses: getappmap/archive-action/merge@v1\n  with:\n    revision: ${{ github.event.pull_request.base.sha }}\n    archive-count: 2 # Set this equal to the total number of test runners (i.e. total archives created)\n```\n\nFor more examples, refer to the\n[AppMap example projects](https://appmap.io/docs/setup-appmap-in-ci/example-projects.html)\n\n## Development\n\n```\n# Remove build artifacts\n$ yarn clean\n\n# Build the project\n$ yarn build\n\n# Run tests\n$ yarn test\n\n# Package the project into a distributable GitHub action\n$ yarn package\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetappmap%2Farchive-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetappmap%2Farchive-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetappmap%2Farchive-action/lists"}