From fc4232c0c49f21ead8ac1b53313cdd930f81d987 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Tue, 10 Mar 2026 17:07:35 +0100 Subject: [PATCH] docs: update README to reflect the current api --- README.md | 137 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 70 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 28f5ef4..5205090 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,97 @@ -# Script Definitions +# github-actions-scripts -## Setup Global Resolver Script - -This script is a utility designed for CI/CD environments (primarily GitHub Actions) to globally configure **sbt, Maven, and Gradle** to use the Akka repository. This ensures that dependencies hosted by Akka can be resolved without modifying individual project source files. -It automates the setup of repository resolvers and deployment credentials across multiple build systems with primary goals of: -* **Global Dependency Resolution:** Injects Akka Release and Snapshot URLs into global config files. -* **Credential Injection:** Dynamically sets up Sonatype Maven Central deployment credentials if environment variables are present. -* **Security:** Configures a Maven HTTP blocker to prevent insecure repository connections. -* **Test Isolation:** Specifically configures sbt "scripted" tests for plugin development. +A collection of reusable GitHub Actions composite actions for Akka projects. --- -### Script Parameters +## `setup_global_resolver` -The script accepts two positional arguments. It includes logic to handle cases where only one argument is provided. +Globally configures **sbt, Maven, and Gradle** to resolve dependencies from the Akka repository. Use this in CI workflows to inject Akka resolvers without modifying individual project source files. -| Parameter | Position | Required | Description | -| :--- | :--- | :--- | :--- | -| **SBT Project Name** | `$1` | No | The name of the sbt plugin project directory. Used to locate `src/sbt-test` for scripted test setup. | -| **Mirror Control** | `$2` | No | Set to `NO_MIRROR` to prevent the script from injecting `` into the Maven `settings.xml`. **Required for projects using `protoc`**, which brute forces its own resolver and fails to handle mirrored edge cases. | +### What it does -#### Argument Logic -* **If 2 arguments are provided:** `$1` is the project name, `$2` is the mirror control. -* **If 1 argument is provided and it contains "MIRROR":** The script treats it as the mirror control flag and leaves the project name empty. -* **If 1 argument is provided and it does NOT contain "MIRROR":** It is treated as the sbt project name. +- Injects Akka release and snapshot repository URLs into global config files for sbt, Maven, and Gradle +- Optionally configures Sonatype Maven Central deployment credentials from environment variables +- Configures a Maven HTTP blocker to prevent insecure repository connections +- Optionally sets up sbt scripted test resolvers for plugin development ---- +### Installation -### Environment Variables +Reference the action directly in your workflow using the `akka/github-actions-scripts/setup_global_resolver` path: -The script utilizes the following environment variables for advanced configuration: +```yaml +- name: Setup Global Akka Resolver + uses: akka/github-actions-scripts/setup_global_resolver@main +``` -* `SONATYPE_USERNAME`: The username for Sonatype/Maven Central. -* `SONATYPE_PASSWORD`: The password/token for Sonatype/Maven Central. -* `PGP_PASSPHRASE`: The passphrase used for GPG signing of artifacts. +No checkout of this repository is required. ---- +### Inputs -### Usage Examples +| Input | Required | Default | Description | +| :--- | :--- | :--- | :--- | +| `sbt-plugin-project-name` | No | `''` | The name of the sbt plugin project directory. When provided, configures resolvers for each `sbt-test` scripted test case found under that project. | +| `maven-mirror-control` | No | `''` | Set to `NO_MIRROR` to skip injecting `` into Maven `settings.xml`. Required for projects using `protoc`, which manages its own resolver and does not handle mirrored repositories. | -The general format for use in Github Actions is: +### Environment Variables -``` - - name: Checkout Global Scripts - uses: actions/checkout@v4 - with: - repository: akka/github-actions-scripts - path: scripts - fetch-depth: 0 - - - name: Setup global resolver - run: | - chmod +x ./scripts/setup_global_resolver.sh - ./scripts/setup_global_resolver.sh -``` +Set these as GitHub Actions secrets/variables if you need Sonatype deployment or GPG signing: -Then the specific use of the shell would look like the followin +| Variable | Description | +| :--- | :--- | +| `SONATYPE_USERNAME` | Sonatype / Maven Central username | +| `SONATYPE_PASSWORD` | Sonatype / Maven Central password or token | +| `PGP_PASSPHRASE` | GPG signing passphrase | -**Standard usage for a library (No scripted tests):** -```bash -./scripts/setup_global_resolver.sh -``` +### Usage Examples -**Usage for an sbt plugin (Enables scripted test setup):** -```bash -./scripts/setup_global_resolver.sh sbt-plugin -``` +**Standard library (no scripted tests):** -**Usage where Maven mirrors must be disabled:** -```bash -./scripts/setup_global_resolver.sh NO_MIRROR -``` +```yaml +steps: + - uses: actions/checkout@v4 ---- + - name: Setup Global Akka Resolver + uses: akka/github-actions-scripts/setup_global_resolver@main +``` -### Key Functions +**sbt plugin project (enables scripted test resolver setup):** -#### `setup_sbt()` -Creates or appends to `~/.sbt/1.0/resolvers.sbt`. It adds the Akka release and snapshot URLs as global resolvers for all sbt builds on the machine. +```yaml +steps: + - uses: actions/checkout@v4 -#### `setup_scripted_tests()` -If a project name is provided, the script searches for `build.sbt` files within the `sbt-test` directory. It then creates a `global/resolvers.sbt` file for **every** individual test case found. This is critical for sbt plugin testing where each test case runs in an isolated environment. + - name: Setup Global Akka Resolver + uses: akka/github-actions-scripts/setup_global_resolver@main + with: + sbt-plugin-project-name: 'my-sbt-plugin' +``` -#### `setup_gradle()` -Generates a Gradle Init Script at `~/.gradle/init.d/akka-resolvers.init.gradle`. This uses the `allprojects` block to inject the Akka Maven repositories into both the `buildscript` (for plugins) and the standard `repositories` (for dependencies). +**Project using `protoc` (disables Maven mirrors):** -#### `setup_maven()` -Generates a `~/.m2/settings.xml` file with: -* **Mirrors:** Blocks all plain `http` traffic for security and redirects Akka requests. -* **Profiles:** Creates an `akka-repo` profile and sets it to ``. -* **Credentials:** If Sonatype variables are found, it injects `` and GPG properties into the settings file. +```yaml +steps: + - uses: actions/checkout@v4 + - name: Setup Global Akka Resolver + uses: akka/github-actions-scripts/setup_global_resolver@main + with: + maven-mirror-control: 'NO_MIRROR' +``` +**Full example with all options and credentials:** + +```yaml +steps: + - uses: actions/checkout@v4 + + - name: Setup Global Akka Resolver + uses: akka/github-actions-scripts/setup_global_resolver@main + with: + sbt-plugin-project-name: 'my-sbt-plugin' + maven-mirror-control: 'NO_MIRROR' + env: + SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }} + SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }} + PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }} +```