Skip to content

Scripts for the actions monorepo

There are currently two scripts for the actions monorepo: - import_configs.sh - monorepo_updates.sh

The scripts update (and use) a import-config.yml file, which is stored for each individual action.

Table of Contents - Import Config File Specifications - Import Configs Script - Monorepo Updates Script

Import Config File Specifications

The import-config.yml file is a structured YAML configuration file generated or updated by the import_configs.sh script; the file is also updated by the monorepo_updates.sh script. The import-config.yml file provides metadata and specifications for GitHub Actions, whether they are locally created or imported from external sources. Below is a breakdown of its structure and an example/template:

File Structure

  1. Metadata Fields:
  2. name: The name of the action (derived from the directory name).
  3. author: The author of the action. If not specified, a placeholder is used.
  4. description: A brief description of the action. Defaults to "placeholder" if not provided.

  5. group: The name of the parent directory group.

  6. Import Status:

  7. imported: A boolean indicating if the action is imported (true) or locally created (false).

  8. Source Information (if imported is true):

  9. source.action_name: The name of the imported action.
  10. source.author: The author of the source action.
  11. source.repo_name: The name of the GitHub repository containing the action.
  12. source.repo_url: The URL of the source repository.
  13. source.current_version: The version currently in use.
  14. source.latest_version: The latest available version of the action.

  15. source.update_available: Boolean indicating if an update is available.

  16. Local Modifications:

  17. local.author: The author of the local action (if not imported).
  18. local.modifications: Boolean indicating if modifications have been made.

  19. local.update.exclusions: A list of files to exclude when updating from source.

  20. Specifications:

  21. specs.action_file: The name of the action file (action.yml or action.yaml).
  22. specs.inputs: A list of input keys defined in the action.
  23. specs.outputs: A list of output keys defined in the action.
  24. specs.runs.using: The execution environment (e.g., node12, docker).

  25. specs.runs.main: The entry point file for the action (if applicable).

  26. Tests:

  27. tests._comment: A reserved section for future test-related fields.

Example import-config.yml

name: example-action
author: "john-doe"
description: "An example GitHub Action for demonstration purposes."
group: "example-group"
imported: true

source:
  action_name: "example-action"
  author: "external-author"
  repo_name: "example-repo"
  repo_url: "https://github.com/external-author/example-repo"
  current_version: "v1.0.0"
  latest_version: "v1.1.0"
  update_available: true
  monorepo: true
  monorepo_path: "example/"

local:
  author: "john-doe"
  modifications: false
  update:
    exclusions:
      - README-examples.md
      - example-custom-notes.md

specs:
  action_file: "action.yml"
  inputs: ["input1", "input2"]
  outputs: ["output1"]
  runs:
    using: "node20"
    main: "dist/index.js"

tests:
  _comment: "reserved for future use"

Notes

  • Placeholders: If the script cannot determine certain values, placeholders ("placeholder") are inserted to prompt the user for manual updates.
  • Dynamic Updates: For imported actions, fields such as source.latest_version and source.update_available are dynamically updated based on the GitHub API.
  • Flexibility: The file structure accommodates both locally created and imported actions, ensuring versatility in various workflows.

Import Configs Script

The import_configs.sh script automates the creation and maintenance of import-config.yml files for actions found in specified directories. It achieves the following:

  1. Read Configuration:

  2. Reads target directories from a configuration file target_dirs.conf.

  3. Identify Action Files:

  4. Checks each subdirectory for the presence of an action.yml or action.yaml file.

  5. Process import-config.yml:

  6. For each subdirectory:

    • If import-config.yml exists:
    • Updates fields like author, description, specs (including inputs, outputs, runs), and source (if applicable).
    • Checks for updates if the action is marked as "imported" by querying the GitHub API for the latest release.
    • If import-config.yml does not exist:
    • Prompts the user to specify if the action is "imported" or "local."
    • Generates an initial import-config.yml with fields such as author, group, imported, specs, and optionally, source details for imported actions.

  7. Extract and Format Data:

  8. Uses the yq tool to parse and extract data from YAML files and to update/create YAML fields.

  9. Extracts keys (e.g., inputs, outputs) and converts them into a suitable format for YAML.

  10. GitHub Integration:

  11. For imported actions, fetches the latest version information from GitHub API to determine if an update is available.

  12. Handle User Input:

  13. Prompts the user to input metadata when creating import-config.yml for new actions, especially for imported actions.

  14. Iterate Over All Actions:

  15. Processes every subdirectory in the target directories, ensuring that all actions are updated or have an import-config.yml generated.

  16. Placeholder Values:

  17. Inserts placeholders for fields like author or description if they are missing in the action file.

  18. Reserved Tests Section:

  19. Adds a tests block in the import-config.yml file for future use.

  20. Output:

    • Displays progress and completion messages for each action processed.

Notes

This script is designed to be extensible and works efficiently for managing configurations of multiple GitHub Actions. It uses yq for YAML manipulation, jq for JSON parsing, and assumes user access to GitHub API for imported action metadata.

Monorepo Updates Script

This script automates the process of checking for updates in repositories and applying those updates to the actions monorepo based on configurations specified in import-config.yml files within target directories. It achieves the following:

  1. Configuration Loading:
  2. Reads target directories from target_dirs.conf.

  3. Optionally allows specifying a specific group and action to process instead of using all target directories.

  4. Update Check Logic:

  5. For each import-config.yml file found in the target directories:

    • Checks if the action is "imported."
    • Verifies if an update is available by comparing the current version with the latest version.
    • Fetches the latest version information from the repository using GitHub APIs (via curl and jq).

  6. Repository Update Process:

  7. Clones the repository at the specified latest version.
  8. Processes the repository:
    • Renames .github/ directory to __dot_github/ and disables .yml files within.
    • Adds a repository name prefix to .md and .yml files.
  9. Creates a new branch in the actions monorepo for the update.

  10. Generates a new README.md based on a template (imported_readme_template.md), using sed to populate placeholders with details (e.g., group name, action name, new version).

    • Eventually this will be managed by a workflow within the actions repo.

  11. Git Workflow:

  12. Prepares changes for a commit (does not auto-commit or push).

  13. Provides instructions for the user to commit and push changes manually.

  14. Temporary Directory Management:

  15. Uses a temporary directory for processing repository updates.

  16. Prompts the user for cleanup after processing.

  17. Configuration File Update:

  18. Updates the current_version and update_available fields in import-config.yml after successful processing.

Notes

The script also has some interactive features: - Prompts the user for specifying specific actions to update. - Offers manual intervention for committing, pushing changes, and cleaning up temporary directories.