🩹 [Patch]: Align Environment Variable and Output File Management Functions

[MariusStorhaug]

Describe the change

Problem Statement

Currently, our PowerShell module for GitHub Actions manages environment variables and outputs using separate code paths and conversion logic.

• Output handling uses ConvertTo-GitHubOutput, ConvertFrom-GitHubOutput, Set-GitHubOutput, and Get-GitHubOutput.
• Environment variable handling is implemented with Set-GitHubEnvironmentVariable, which is not aligned with the output functions, and there is no corresponding Get-GitHubEnvironmentVariable function.

However, the data storage format for $GITHUB_OUTPUT and $GITHUB_ENV files is nearly identical:

• Both support single-line (key=value) and multiline (key<<EOF...EOF) entries.
• Both can be parsed and generated using the same logic.

Goal

Unify and align the way data is converted to and from files for both GitHub environment variables and outputs.

• Refactor to ensure the same robust conversion logic (for single-line/multiline, and JSON parsing/serialization) is reused across both cases.
• Standardize naming and signatures for the “Get/Set” functions for environment variables and outputs.

Tasks

1. Refactor conversion functions:

   • Generalize ConvertTo-GitHubOutput and ConvertFrom-GitHubOutput to work for both output and environment variable files (support both $GITHUB_OUTPUT and $GITHUB_ENV).
   • Consider renaming or creating shared functions (e.g., ConvertTo-GitHubFileFormat and ConvertFrom-GitHubFileFormat).

2. Align Get/Set function implementations:

   • Update Set-GitHubEnvironmentVariable to use the shared conversion logic.
   • Implement Get-GitHubEnvironmentVariable, matching the approach of Get-GitHubOutput (including support for hashtable/PSCustomObject return, and customizable file path).

3. Standardize naming and usage:

   • Provide and document the following functions:

     • Get-GitHubOutput / Set-GitHubOutput
     • Get-GitHubEnvironmentVariable / Set-GitHubEnvironmentVariable

   • All of these should leverage the same core file-format conversion functions.

4. Ensure full compatibility:

   • Both Get/Set functions should handle all valid GitHub Actions file formats: single-line, multiline, and JSON values.
   • Properly handle appending/updating of values (as appropriate).

5. Update documentation and usage examples:

   • Ensure that inline documentation, usage examples, and parameter descriptions are accurate and consistent.

Acceptance Criteria

• Both outputs and environment variables can be set and retrieved using the same logic for encoding/decoding file formats.
• All Get/Set functions support both single-line and multi-line values (including complex/JSON objects).
• Conversion code is not duplicated between outputs and environment variable functions.
• Usage is consistent, with clear documentation.

---

References:

• GitHub Actions: Setting an environment variable
• GitHub Actions: Setting an output parameter

---

Let me know if you’d like this written in a different style, want additional checklist items, or need a migration/upgrade guide section for users!