@lukaswestholt/semantic-release-skopeo/docs/usage.md

This is a plugin for semantic-release that copies OCI images to a custom registry using daemonless open-source tool skopeo.

# Usage

## Overview

This guide provides usage examples and configurations for the [`.releaserc` file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file), demonstrating its use with different formats and Continuous Integration (CI) environments.
The `.releaserc` file is used for configuring release settings, including plugins, branches, and other options for the [`semantic-release`](https://semantic-release.gitbook.io/semantic-release) tool,
which automates the release process.

## .releaserc

`.releaserc` supports several file formats including JSON, YAML, and JavaScript.

### JSON Example

```json
{
    "branches": ["main"],
    "plugins": [
        "@semantic-release/commit-analyzer",
        [
            "@lukaswestholt/semantic-release-skopeo",
            {
                "source": "docker://registry.example.com/my-project/my-image:latest",
                "destination": [
                    "docker://registry.example.com/my-project/my-image:${version}"
                ]
            }
        ]
    ]
}
```

### YAML Example

```yaml
branches:
    - main
plugins:
    - '@semantic-release/commit-analyzer'
    - - '@lukaswestholt/semantic-release-skopeo'
        - source: docker://registry.example.com/my-project/my-image:latest
        - destination:
            - docker://registry.example.com/my-project/my-image:${version}
```

### JavaScript Example

```javascript
module.exports = {
    branches: ["main"],
    plugins: [
        "@semantic-release/commit-analyzer",
        [
            "@lukaswestholt/semantic-release-skopeo",
            {
                source: "docker://registry.example.com/my-project/my-image:latest",
                destination: [
                    "docker://registry.example.com/my-project/my-image:${version}",
                ],
            },
        ],
    ],
};
```

## Environment Variables for Plugin Configuration

In cases where sensitive data or variable configuration is necessary, we support providing config values as env vars. This approach is especially beneficial in CI/CD environments where the configuration should not be hardcoded in the `.releaserc` file.

The environment variable names are derived from the configuration options by converting the option name to uppercase and prefixing with `SKOPEO`. For example, the `destination` option would be set with the `SKOPEO_DESTINATION` environment variable.

Anything more complex than a simple key/value pair should be represented as JSON. Some examples:

- `SKOPEO_SOURCE="docker://registry.example.com/my-project/my-image:latest"`
- `SKOPEO_DESTINATION='["docker://registry.example.com/my-project/my-image:\${version}","docker://registry.example.com/my-project/my-image:latest"]'`

Full list of configuration options and examples can be found in the [Configuration](./configuration.md) documentation.

### Environment Variables Example

1. Include the `@lukaswestholt/semantic-release-skopeo` plugin in your `.releaserc` file:

    ```json
    {
        "branches": ["main"],
        "plugins": [
            "@semantic-release/commit-analyzer",
            "@lukaswestholt/semantic-release-skopeo"
        ]
    }
    ```

2. Define the environment variables in your CI configuration. For instance, in a GitHub Actions workflow:

    ```yaml
    name: Release

    on:
        push:
            branches:
                - main

    jobs:
        release:
            runs-on: ubuntu-latest
            container:
                image: ghcr.io/lukaswestholt/semantic-release-skopeo:latest
            steps:
                - name: Checkout code
                  uses: actions/checkout@v3

                - name: Install dependencies
                  run: npm i

                - name: Release
                  run: npx semantic-release
                  env:
                      SKOPEO_SOURCE: "docker://registry.example.com/my-project/my-image:latest"
                      SKOPEO_DESTINATION: '["docker://registry.example.com/my-project/my-image:\${version}","docker://registry.example.com/my-project/my-image:latest"]'
    ```

### Using `nextRelease` version variables

You can use version variables in the `destination` to automatically tag images based on the `nextRelease` version:

| Variable          | Description           | Example |
| ----------------- | --------------------- | ------- |
| `${version}`      | Full semantic version | `1.2.3` |
| `${majorVersion}` | Major version only    | `1`     |
| `${minorVersion}` | Major + minor version | `1.2`   |

**Example:**

```json
{
    "plugins": [
        [
            "@lukaswestholt/semantic-release-skopeo",
            {
                "source": "docker://registry.example.com/my-project/my-image:latest",
                "destination": [
                    "docker://registry.example.com/my-project/my-image:${version}"
                ]
            }
        ]
    ]
}
```

This will copy the image to `docker://registry.example.com/my-project/my-image:1.2.3`.
You can also add tags like `1` and `1.2` by adding multiple destinations:

```json
{
    "plugins": [
        [
            "@lukaswestholt/semantic-release-skopeo",
            {
                "source": "docker://registry.example.com/my-project/my-image:latest",
                "destination": [
                    "docker://registry.example.com/my-project/my-image:${version}",
                    "docker://registry.example.com/my-project/my-image:${majorVersion}",
                    "docker://registry.example.com/my-project/my-image:${minorVersion}"
                ]
            }
        ]
    ]
}
```

---

### Using external environment variables

You can also reference external environment variables in `source` and `destination` using `${VAR}` or `$VAR`.
These are resolved at runtime.

**Example:**

```json
{
    "plugins": [
        [
            "@lukaswestholt/semantic-release-skopeo",
            {
                "source": "docker://registry.example.com/my-project/my-image:latest",
                "destination": [
                    "docker://registry.example.com/my-project/my-image:${BITBUCKET_COMMIT}"
                ]
            }
        ]
    ]
}
```

In this example, `${BITBUCKET_COMMIT}` will be replaced with the commit hash from your CI environment.

---

**Note:** If both `nextRelease` variables and environment variables have the same syntax (`${}`),
the plugin will resolve `nextRelease` variables first, then environment variables.

## Example Workflows

Here are some examples showing how to integrate `semantic-release` and the `@lukaswestholt/semantic-release-skopeo` plugin into various CI/CD pipelines.

### GitHub Actions Workflow Example

```yaml
name: Release

on:
    push:
        branches:
            - main

jobs:
    release:
        runs-on: ubuntu-latest
        container:
            image: ghcr.io/lukaswestholt/semantic-release-skopeo:latest
        steps:
            - name: Checkout code
              uses: actions/checkout@v3

            - name: Release
              run: npx semantic-release
```

### GitLab CI Example

```yaml
stages:
    - release

release:
    stage: release
    image: ghcr.io/lukaswestholt/semantic-release-skopeo:latest
    script:
        - npm ci
        - npx semantic-release
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

### CircleCI Example

```yaml
version: 2.1

executors:
    skopeo:
        docker:
            - image: ghcr.io/lukaswestholt/semantic-release-skopeo:latest

jobs:
    release:
        executor: skopeo
        steps:
            - checkout
            - run:
                  name: Install dependencies
                  command: npm ci
            - run:
                  name: Run semantic-release
                  command: npx semantic-release

workflows:
    version: 2
    release:
        jobs:
            - release:
                  filters:
                      branches:
                          only: main
```

## Private Registry Authorization

You can execute `skopeo login` before `npx semantic-release`. See [here](https://github.com/containers/skopeo/blob/main/docs/skopeo-login.1.md).

### GitHub Actions Example

```yaml
name: Release

on:
    push:
        branches:
            - main

jobs:
    release:
        runs-on: ubuntu-latest
        container:
            image: ghcr.io/lukaswestholt/semantic-release-skopeo:latest
        steps:
            - name: Checkout code
              uses: actions/checkout@v3

            - name: Skopeo login
              run: |
                  skopeo login -u ${{ secrets.REGISTRY_USER }} -p ${{ secrets.REGISTRY_PASSWORD }} localhost:5000

            - name: Release
              run: npx semantic-release
```

## Advanced Configuration

For more detailed information on all available configuration flags, refer to the [Configuration](configuration.md) doc.