diff --git a/.github/workflows/gem_ci.yml b/.github/workflows/gem_ci.yml index 98c54e4..b2faf4e 100644 --- a/.github/workflows/gem_ci.yml +++ b/.github/workflows/gem_ci.yml @@ -30,15 +30,20 @@ on: default: false type: "boolean" +# ENABLE PUPPETCORE. The calling workflow must: +# - Set a valid PUPPET_FORGE_TOKEN secret on its repository. +# - Set ruby_version >= 3.1 to override this workflow's default 2.7; otherwise bundle install will fail. +env: + PUPPET_GEM_VERSION: ${{ inputs.puppet_gem_version }} + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + PUPPET_FORGE_TOKEN: ${{ secrets.PUPPET_FORGE_TOKEN }} + BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "forge-key:${{ secrets.PUPPET_FORGE_TOKEN }}" + jobs: spec: name: "spec" runs-on: ${{ inputs.runs_on }} - env: - PUPPET_GEM_VERSION: ${{ inputs.puppet_gem_version }} - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - steps: - name: "checkout" uses: "actions/checkout@v4" diff --git a/.github/workflows/module_ci.yml b/.github/workflows/module_ci.yml index 53f23be..e0f4d62 100644 --- a/.github/workflows/module_ci.yml +++ b/.github/workflows/module_ci.yml @@ -24,18 +24,13 @@ on: required: false default: '3.1' type: "string" - puppetcore_api_type: - description: "The type of API to use for Puppet Core." - required: false - default: 'forge-key' - type: "string" # ENABLE PUPPETCORE. The calling workflow must: # - Set a valid PUPPET_FORGE_TOKEN secret on its repository. # - Set ruby_version >= 3.1 to override this workflow's default 2.7; otherwise bundle install will fail. env: PUPPET_FORGE_TOKEN: ${{ secrets.PUPPET_FORGE_TOKEN }} - BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "${{ inputs.puppetcore_api_type }}:${{ secrets.PUPPET_FORGE_TOKEN }}" + BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "forge-key:${{ secrets.PUPPET_FORGE_TOKEN }}" jobs: setup_matrix: diff --git a/.github/workflows/tooling_mend_ruby.yml b/.github/workflows/tooling_mend_ruby.yml index 4d4099b..2a0d188 100644 --- a/.github/workflows/tooling_mend_ruby.yml +++ b/.github/workflows/tooling_mend_ruby.yml @@ -25,6 +25,11 @@ env: MEND_TOKEN: ${{ secrets.MEND_TOKEN != '' && secrets.MEND_TOKEN || inputs.token }} PRODUCT_NAME: ${{ inputs.PRODUCT_NAME != '' && inputs.PRODUCT_NAME || inputs.product_name }} REQUIRE_SECRETS: MEND_API_KEY MEND_TOKEN + # ENABLE PUPPETCORE. The calling workflow must: + # - Set a valid PUPPET_FORGE_TOKEN secret on its repository. + # - Set ruby_version >= 3.1 to override this workflow's default 2.7; otherwise bundle install will fail. + PUPPET_FORGE_TOKEN: ${{ secrets.PUPPET_FORGE_TOKEN }} + BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "forge-key:${{ secrets.PUPPET_FORGE_TOKEN }}" jobs: mend: diff --git a/docs/how-to/how_to_inject_puppetcore_authentication_into_the_shared_workflows.md b/docs/how-to/how_to_inject_puppetcore_authentication_into_the_shared_workflows.md new file mode 100644 index 0000000..0b04269 --- /dev/null +++ b/docs/how-to/how_to_inject_puppetcore_authentication_into_the_shared_workflows.md @@ -0,0 +1,84 @@ +# How to inject puppetcore authentication into the shared workflows + +## Description + +This guide explains how to configure your repository to consume the following shared workflows and ensure that puppetcore dependencies are successfully bundle installed: + +- `module_ci.yml` +- `gem_ci.yml` +- `tooling_mend_ruby.yml` + +The above workflows are backward compatible and designed to work with both puppetcore and non-puppetcore repositories. + +## Prerequisites + +- A puppetcore repository that needs to use a shared workflow. +- Access to repository settings to configure secrets +- A valid `PUPPET_FORGE_TOKEN` with access to the private puppetcore gem source + +## Configuration Requirements + +### Required Settings + +To use PuppetCore Gems with the above shared workflows, your repository must meet these requirements: + +1. **Set up the PUPPET_FORGE_TOKEN secret**: + - Navigate to your repository on GitHub + - Go to Settings > Secrets and variables > Actions + - Add a new repository secret named `PUPPET_FORGE_TOKEN` with your valid token value + +2. **Configure Ruby Version to be >= 3.1**: + - Ruby version >= 3.1 is required for PuppetCore Gems. + - Some shared worklows, like `module_ci.yml`, have an old default Ruby version that must be overridden + +## Usage + +Create or update your workflow file (typically `.github/workflows/ci.yml`) to look something like: + +```yaml +name: "ci" + +on: + pull_request: + branches: + - "main" + workflow_dispatch: + +jobs: + Spec: + uses: "puppetlabs/cat-github-actions/.github/workflows/module_ci.yml@main" + with: + run_shellcheck: true + ruby_version: '3.1' # Required for PuppetCore Gems + secrets: "inherit" # Required to pass PUPPET_FORGE_TOKEN +``` + +For 2 example consumers, see: + +* [puppet-upgrade ci.yml](https://github.com/puppetlabs/puppet-upgrade/blob/main/.github/workflows/ci.yml) +* [provision ci.yml](https://github.com/puppetlabs/provision/blob/main/.github/workflows/ci.yml) + +## How It Works + +The above shared workflows are designed to install gems from . They + +- **Inherit** the `PUPPET_FORGE_TOKEN` secret from the consumer repository and then **set** an environment variable of the same name. This environment variable is required by some repositories to "switch" between either the public or puppetcore gems. +- **Set** the `BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM` environment variable ensuring authentication against the gemsource. For example, + +```bash +BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "forge-key:${{ secrets.PUPPET_FORGE_TOKEN }}" +``` + +## Troubleshooting + +Common issues and their solutions: + +- **Bundle install fails**: Ensure Ruby version is set to at least 3.1 +- **Authentication errors**: Verify the PUPPET_FORGE_TOKEN is correctly set and has appropriate permissions + +## Appendix + +### Security Considerations + +- Use the `secrets: "inherit"` pattern to securely pass tokens from your consumer to shared workflow. +- Push secrets into environment variables for use by code. This is another github pattern that maintains redaction of secrets in logs diff --git a/docs/how-to/how_to_using_module_ci_workflow_with_puppetcore_gems.md b/docs/how-to/how_to_using_module_ci_workflow_with_puppetcore_gems.md deleted file mode 100644 index e58dff0..0000000 --- a/docs/how-to/how_to_using_module_ci_workflow_with_puppetcore_gems.md +++ /dev/null @@ -1,105 +0,0 @@ -# How to use the module_ci workflow with puppetcore gems - -## Description - -This guide explains how to configure your repository to use the shared `module_ci.yml` workflow with PuppetCore Gems. The workflow is designed to maintain backward compatibility with existing consumers (like puppetlabs-apache and puppetlabs-ntp) while providing the capability to install and use gems from the private PuppetCore gem source. - -## Prerequisites - -- A GitHub repository that needs to use the `module_ci.yml` workflow -- Access to repository settings to configure secrets -- A valid `PUPPET_FORGE_TOKEN` with access to the private gem source - -## Configuration Requirements - -### Required Settings - -To use PuppetCore Gems with the module_ci workflow, your repository must meet these requirements: - -1. **Set up the PUPPET_FORGE_TOKEN secret**: - - Navigate to your repository on GitHub - - Go to Settings > Secrets and variables > Actions - - Add a new repository secret named `PUPPET_FORGE_TOKEN` with your valid token value - -2. **Configure Ruby Version**: - - Must specify a Ruby version >= 3.1 (required for PuppetCore Gems) - - The default Ruby version in module_ci.yml is 2.7 and must be overridden - -### Optional Settings - -- **PuppetCore API Type**: - - By default, set to 'forge-key' - - Can be changed to 'license-key' if required - -## Usage - -Create or update your workflow file (typically `.github/workflows/ci.yml`) to look something like: - -```yaml -name: "ci" - -on: - pull_request: - branches: - - "main" - workflow_dispatch: - -jobs: - Spec: - uses: "puppetlabs/cat-github-actions/.github/workflows/module_ci.yml@main" - with: - run_shellcheck: true - ruby_version: '3.1' # Required for PuppetCore Gems - secrets: "inherit" # Required to pass PUPPET_FORGE_TOKEN -``` - -## How It Works - -When properly configured, the `module_ci.yml` workflow will: - -1. Inherit the `PUPPET_FORGE_TOKEN` secret from the consumer repository. -2. Set the following `BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM` environment variable ensuring authentication against the gemsource, e.g,: - - ```shell - BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM: "forge-key:${{ secrets.PUPPET_FORGE_TOKEN }}" - ``` - -3. Install gems from . - -## Troubleshooting - -Common issues and their solutions: - -- **Bundle install fails**: Ensure Ruby version is set to at least 3.1 -- **Authentication errors**: Verify the PUPPET_FORGE_TOKEN is correctly set and has appropriate permissions - -## Appendix - -### Sample Implementation - -Example configuration in a consuming repository: - -```yaml -name: "ci" - -on: - pull_request: - branches: - - "main" - workflow_dispatch: - -jobs: - Spec: - uses: "puppetlabs/cat-github-actions/.github/workflows/module_ci.yml@main" - with: - run_shellcheck: true - ruby_version: '3.1' - puppetcore_api_type: 'license-key' - secrets: "inherit" -``` - -### Security Considerations - -- Never hardcode the PUPPET_FORGE_TOKEN in your workflow files -- Use the `secrets: "inherit"` pattern to securely pass tokens -- Regularly rotate your tokens following security best practices