(Discussion) Documentation on how to use the provided in github action (e.g., .github/workflows/make-release.yml)

[kefeimo]

Note:

This memo should be relocated as needed.

Background

Describe how github-tooling/.github/workflows/deploy-release.yml is used by example of volttron-core/.github/workflows/make-release.yml

Overview of the GitHub Actions Workflow

Main Steps/Jobs

1. Trigger Workflow: The workflow is triggered manually via the workflow_dispatch event in the GitHub UI.

2. Input Parameters: Several inputs are required:

   • merge-strategy: Strategy for merging branches.
   • release-version: Specific version number for the release.
   • bump-rule: Rule for version bumping (patch, minor, major, etc.).
   • run-tests-wait: Time to wait for running tests.
   • publish-option: Determines where to publish (pypi, test-pypi, none).

3. Secrets and Environment Variables:

   • git-token: GitHub token for repository access.
   • pypi-token: Token for publishing to PyPI.
   • PYTHON_VERSION: Set to 3.10.
   • LANG and LC_ALL: Set to en_US.utf-8.

4. Check Out Repository: Checks out the code from the develop branch.

5. Merge and Conflict Handling: Merges develop into main, aborts if conflicts occur.

6. Set Up Python and Node.js: Sets up Python 3.10 and Node.js for dependency management.

7. Install SBOM Tools: Installs cdxgen and depscan to generate a Software Bill of Materials (SBOM).

8. Generate SBOM: Runs cdxgen to generate SBOM and depscan for vulnerability reports.

9. Install Poetry: Installs Poetry for dependency management and project configuration.

10. Update and Install Dependencies: Updates the lock file and installs dependencies, including development dependencies.

11. Set Release Version: Uses the provided release version or bumps the version based on the bump-rule.

12. Create Release Branch: Creates a new branch for the release.

13. Run Tests: Runs tests on the main branch using pytest with a timeout specified by run-tests-wait.

14. Handle Test Failures: Reverts changes and deletes the release branch if tests fail.

15. Build Artifacts: Builds the project artifacts using Poetry.

16. Publish Artifacts: Publishes to PyPI or Test PyPI based on publish-option.

17. Handle Publishing Failures: Reverts changes if publishing fails.

18. Merge Back to Develop: Merges changes back to the develop branch.

Configuration in GitHub UI

• Secrets: Ensure AUTO_PROJECT_PAT and PYPI_TOKEN are configured in the repository secrets.
• Environment Variables: These are set within the workflow file and don't require additional setup in the UI.
  • Note: The AUTO_PROJECT_PAT is a secret in GitHub that stands for "Automated Project Personal Access Token." It is a Personal Access Token (PAT) created and used to authenticate actions or workflows running in your GitHub repository.

Manually Triggering the Workflow

1. Go to the "Actions" tab in your GitHub repository.
2. Select the "Make full release" workflow.
3. Click "Run workflow."
4. Fill in the required inputs:
   • Merge Strategy: Choose the merge strategy.
   • Release Version: Specify the release version or leave empty to use the bump rule.
   • Bump Rule: Select the appropriate bump rule.
   • Run Tests Wait: Set the wait time for running tests.
   • Publish Option: Choose where to publish (pypi, test-pypi, or none).
5. Click "Run workflow" to start the process.

This streamlined process ensures that the release workflow is flexible, handles dependencies effectively, and manages potential conflicts and errors gracefully.