Skip to content

How to create a SAF Action Release

Jump to bottom
Joyce Quach edited this page Oct 28, 2024 · 23 revisions

The SAF Action allows the automation of building, testing, and deployment of the SAF CLI pipeline. To create a release of the SAF Action so that it includes the latest SAF CLI node module dependency, new updates or functionality, follow the instructions posted here.

These instructions ensure that the latest dependencies or any changes are included, and the appropriate tags when making a release are specified.

Follow the steps listed below:

1. Ensure you have the most recent commits to the SAF Action locally.
  • If this is the first time accessing the repository run:
    • git clone <repo>
  • If the repository was previously cloned locally run:
    • git pull
2. Determine the new SAF Action version.

To determine the new SAF Action version number, first identify the latest version of the SAF Action, found under the Releases section of the main GitHub page, then determine what segment of the version needs to be incremented depending on the type of change. The SAF Action major version should correspond to the SAF CLI major version in its dependencies. Minor and patch versions do not need to match (SAF CLI to SAF Actions).

The SAF Action and SAF CLI versioning follow the guidelines provided Semantic Versioning 2.0.0

The table below indicates how and what segment of the SAF Actions version number should be incremented based on applied changes to the SAF CLI:

UPDATE SAF Action VERSION NUMBER
SAF CLI new patch version Increment SAF Action patch version
SAF CLI new minor version Increment SAF Action minor version
SAF CLI new major version Increment SAF Action major version
3. Update package.json file and node modules.

The node_modules directory and the package.json must be updated to reflect modifications made to the SAF Action versioning.

  • Remove the current node_modules directory: rm -rf node_modules/*

    image

  • Update package.json file to include the latest SAF CLI version and the new SAF Action version number that you want to release (determined in step 2). In this example, we assume that the CLI Action version was updated to 1.3.0 image

  • Rebuild node modules: npm i

NOTE If using windows the DO NOT use a cmd or PowerShell terminal as it includes (adds) cmd and ps1 scripts to any script for the node modules being included, this will cause the .github/workflows/example-usages.yml action to fail. Use the Windows Subsystem for Linux (WSL) if installed.

image

  • add changes: git add . image

  • commit changes: git commit -s -m "Updated node modules to use new SAF CLI version and updated SAF Action version number"

image

4. Update SAF Action version based on the following criteria.

a. For updating MINOR or PATCH version change:

  • Create a release tag with annotations by doing the following. The annotation will be displayed in the release notes.
    • (You can view SAF Action tags by writing git tag)
    • Add the new release tag from step 2 (ex tag name full: v1.2.1) with an annotation. This tag name full is the new version of the SAF Action, and is only required to have the same major version number as the SAF CLI, but can have different minor or patch numbers.
      • Ex: git tag -a -m "Using SAF CLI version 1.0.6" <tagNameFull>
    • Delete previous major release tag (ex tag name major: v1) by running
      • Ex: git push --delete origin <tagNameMajor>
    • Re-add the major release tag (ex tag name major: v1) to reference the latest SAF Action semantic version tag. You can use the same annotation. Notice this includes a force flag: -f.
      • Ex: git tag -f -a -m "Using SAF CLI version 1.0.6" <tagNameMajor>
    • Push the tags to the remote repository. git push --atomic origin main <tagNameFull> <tagNameMajor>
    • If you receive an error when pushing the tag, try pushing individually with:
      • git push origin tag <tagNameFull>
      • git push origin tag <tagNameMajor>

b. For updating MAJOR version change:

  • Create a release tag with annotations by doing the following. The annotation will be displayed in the release notes.
    • (You can view SAF Action tags by writing git tag)
    • Add the new release tag from step 2 (ex tag name full: v1.2.1) with an annotation. This tag name full is the new version of the SAF Action, and is only required to have the same major version number as the SAF CLI, but can have different minor or patch numbers.
      • Ex: git tag -a -m "Using SAF CLI version 1.0.6" <tagNameFull>
  • Add the major release tag (ex tagNameMajor: v1) to reference the latest SAF Action semantic version tag. You can use the same annotation.
    • Ex: git tag -f -a -m "Using SAF CLI version 1.0.6" <tagNameMajor>
  • Push the tags to the remote repository. git push --atomic origin <branch name> <tagNameFull> <tagNameMajor>
5. Check that the updated SAF Action is working.
  • The test workflows will run using the code in the main branch. Check the unit test results and the integration test results to see if they pass.
  • If they do not pass, try to identify any issues, perhaps in dependencies or the release process. Check to see if there are any pull requests pending from dependabot. If you need to make updates, go through steps 3 and 4 again to add, commit, and tag (you can reuse the same tag but may need to delete it first) the new changes.
  • If they pass, continue on to the next step.
6. Release the newly tagged version.
  • Wait for the draft-release workflow to complete.
  • Click "Releases"
  • Click on the newly drafted release and click the edit button to edit the draft
  • If not already checked, check "Publish this Action to the GitHub Marketplace"
  • Click "Publish release"
Optional Information: Running Dependabot manually to detect the latest dependency updates and update node modules
  1. Ensure the SAF Action has the latest version of the mitre/saf node module by manually running a dependabot check if necessary.
    • From the saf_action GitHub page, click "Insights" from the top menu bar.
    • Click "Dependency Graph" on the left menu list
    • Click "Dependabot"
    • Click "Last checked X days/hours ago"
    • Click "Check for updates"
  2. Wait for the Dependabot check and the "Auto Approve and Merge Dependabot PRs" workflow to complete, building the latest node modules. (This can be seen by clicking the "Actions" option in the top menu.)
Clone this wiki locally