Release Targets 🎯

The targets subsection in your Rlsr configuration specifies where the releases will be published. Rlsr supports multiple target types, allowing you to publish your releases to various platforms.

Supported Targets

Currently, Rlsr supports the following targets:

1. GitHub
2. GitLab
3. Docker

Let’s explore each target type in detail.

GitHub

To release to GitHub, you need to specify the following in your configuration:

targets:
  github:
    owner: "username"
    repo: "repository"
    draft: false # optional
    name: "{{ meta.project_name }} {{ meta.tag }}" # optional
    replace_existing_assets: false # optional

• owner: The GitHub username or organization name where the repository is hosted.
• repo: The name of the GitHub repository.
• draft: (Optional) Create the release as a draft so you can review it before publishing. Defaults to false.
• name: (Optional) The release title. Supports templating with the release fields (meta.tag, meta.version, meta.project_name and so on). Defaults to the tag.
• replace_existing_assets: (Optional) When the release already has an asset with the same name as one being uploaded, delete it and upload the new one. Defaults to false, which stops the publish with an error before anything is uploaded.

If a release for the tag already exists, including a draft, rlsr uploads to it instead of creating a new one, and leaves its title, notes and draft/prerelease state alone. This lets you write the release notes in GitHub first, or rerun a publish that failed partway. On a rerun, set replace_existing_assets: true to replace the assets that were already uploaded.

Each asset upload is tried up to 3 times. If some uploads still fail, rlsr reports all of them and exits with an error after the other uploads finish.

Tags with a semver prerelease part, such as v1.2.0-rc.1, are published as GitHub prereleases, so they don’t become the repository’s latest release.

Important Note

To release to GitHub, you must set the GITHUB_TOKEN environment variable with a valid GitHub Personal Access Token. This token is used to authenticate and perform release operations on your GitHub repository.

GitLab

To release to GitLab, you need to specify the following in your configuration:

targets:
  gitlab:
    owner: "namespace"
    repo: "project-name"
    url: "https://gitlab.com" # optional, for self-hosted instances

• owner: The GitLab group/namespace or username where the project lives.
• repo: The GitLab project name.
• url: The GitLab instance URL (optional, defaults to https://gitlab.com).

Important Note

To release to GitLab, you must set the GITLAB_TOKEN environment variable with a valid GitLab Personal Access Token that has the api scope.

For more details on GitLab behavior, see GitLab Releases.

Docker

To publish Docker images, you can either build + push an image or push existing tags.

Build and push (legacy)

targets:
  docker:
    image: "username/image:tag"
    dockerfile: "path/to/Dockerfile"
    context: "."
    push: true

• image: The full name of the Docker image, including the registry if applicable.
• dockerfile: The path to the Dockerfile relative to your project root.
• context: The build context for Docker, usually the root of your project.
• push: Optional. Defaults to true. Set to false to skip docker push.

The image value supports templating (see Templating). If you omit a tag or digest, rlsr appends the current tag automatically.

Push existing images

targets:
  docker:
    images:
      - "ghcr.io/acme/app:{{ meta.tag }}"
      - "ghcr.io/acme/app:latest"
    push: true

• images: Optional list of image references to push. Each entry supports templating and will receive the latest tag if one is missing.

Buildx publishing

If you build images with type: "buildx", rlsr records the rendered Buildx tags during the build. When a Docker target is configured without image/dockerfile/context or images, rlsr pushes the Buildx tags instead. This lets Buildx builds publish images without a separate docker build step.

When using Buildx outputs:

• type=registry pushes the multi-arch image during the build step. In this case, set targets.docker.push: false to avoid a second push pass.
• load: true loads a single-platform image into the local Docker daemon; the Docker target can push it when targets.docker.push is true, but it is not multi-arch.
• type=local or type=tar writes files locally and does not publish.

targets.docker.push only controls whether the Docker target performs docker push for images it handles (configured image/images or captured Buildx tags). It does not change the Buildx build behavior.

Multiple Targets

You can specify multiple targets in your configuration to release to different platforms simultaneously. For example:

targets:
  github:
    owner: "username"
    repo: "repository"
  docker:
    image: "username/image:tag"
    dockerfile: "./Dockerfile"
    context: "."

This configuration will release your project to both GitHub and Docker.