Skip to content

docs: update README to reflect the current api #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sebastian-alfers wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update README to reflect the current api #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 70 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<mirrors>` 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 `<mirrors>` 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 `<activeByDefault>`.
* **Credentials:** If Sonatype variables are found, it injects `<servers>` 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 }}
```