Skip to content
Permalink
Browse files
docs: improve wording/formatting in several places (#3384)
this just improves docs wording and formatting in several places.

Signed-off-by: Carlos A Becker <caarlos0@users.noreply.github.com>
  • Loading branch information
caarlos0 committed Sep 17, 2022
1 parent 36a48ea commit c1965923b0c52429718b1dd4948b796d6c8aaad2
Show file tree
Hide file tree
Showing 33 changed files with 502 additions and 356 deletions.
@@ -11,7 +11,7 @@ type ErrDirty struct {
}

func (e ErrDirty) Error() string {
return fmt.Sprintf("git is currently in a dirty state\nPlease check in your pipeline what can be changing the following files:\n%v\nLearn more at https://goreleaser.com/errors/dirty\n", e.status)
return fmt.Sprintf("git is in a dirty state\nPlease check in your pipeline what can be changing the following files:\n%v\nLearn more at https://goreleaser.com/errors/dirty\n", e.status)
}

// ErrWrongRef happens when the HEAD reference is different from the tag being built.
@@ -1,10 +1,10 @@
# GitHub Actions

GoReleaser can also be used within our official [GoReleaser Action][goreleaser-action]
through [GitHub Actions][actions].
GoReleaser can also be used within our official [GoReleaser
Action][goreleaser-action] through [GitHub Actions][actions].

You can create a workflow for pushing your releases by putting YAML configuration to
`.github/workflows/release.yml`.
You can create a workflow for pushing your releases by putting YAML
configuration to `.github/workflows/release.yml`.

## Usage

@@ -77,8 +77,8 @@ jobs:

### Signing

If [signing is enabled][signing] in your GoReleaser configuration, you can use the [Import GPG][import-gpg]
GitHub Action along with this one:
If [signing is enabled][signing] in your GoReleaser configuration, you can use
the [Import GPG][import-gpg] GitHub Action along with this one:

```yaml
-
@@ -99,7 +99,8 @@ GitHub Action along with this one:
GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}
```

And reference the fingerprint in your signing configuration using the `GPG_FINGERPRINT` environment variable:
And reference the fingerprint in your signing configuration using the
`GPG_FINGERPRINT` environment variable:

```yaml
signs:
@@ -109,54 +110,64 @@ signs:

## Customizing

<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->

### Inputs

Following inputs can be used as `step.with` keys

| Name | Type | Default | Description |
|------------------|---------|--------------|------------------------------------------------------------------|
| `distribution` | String | `goreleaser` | GoReleaser distribution, either `goreleaser` or `goreleaser-pro` |
| `version`[^1] | String | `latest` | GoReleaser version |
| `args` | String | | Arguments to pass to GoReleaser |
| `workdir` | String | `.` | Working directory (below repository root) |
| `install-only` | Bool | `false` | Just install GoReleaser |
Name |Type |Default |Description
--------------|------|------------|----------------------------------------------------------------
`distribution`|String|`goreleaser`|GoReleaser distribution, either `goreleaser` or `goreleaser-pro`
`version`[^1] |String|`latest` |GoReleaser version
`args` |String| |Arguments to pass to GoReleaser
`workdir` |String|`.` |Working directory (below repository root)
`install-only`|Bool |`false` |Just install GoReleaser

[^1]: Can be a fixed version like `v0.117.0` or a max satisfying SemVer one like `~> 0.132`. In this case this will return `v0.132.1`.
[^1]: Can be a fixed version like `v0.117.0` or a max satisfying SemVer one like
`~> 0.132`. In this case this will return `v0.132.1`.

### Outputs

Following outputs are available

| Name | Type | Description |
|-------------------|---------|---------------------------------------|
| `artifacts` | JSON | Build result artifacts |
| `metadata` | JSON | Build result metadata |
Name |Type|Description
-----------|----|----------------------
`artifacts`|JSON|Build result artifacts
`metadata` |JSON|Build result metadata

### Environment Variables

Following environment variables can be used as `step.env` keys

| Name | Description |
|------------------|---------------------------------------|
| `GITHUB_TOKEN` | [GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) as provided by `secrets` |
| `GORELEASER_KEY` | Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution |
Name |Description
----------------|---------------------------------------------------------------------------------------------------------------------------------------------------
`GITHUB_TOKEN` |[GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) as provided by `secrets`
`GORELEASER_KEY`|Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution

## Token Permissions

The following [permissions](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) are required by GoReleaser:
The following
[permissions](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token)
are required by GoReleaser:

- `contents: write` if you wish to
- [upload archives as GitHub Releases](/customization/release/), or
- publish to [Homebrew](/customization/homebrew/), or [Scoop](/customization/scoop/) (assuming it's part of the same repository)
- publish to [Homebrew](/customization/homebrew/), or
[Scoop](/customization/scoop/) (assuming it's part of the same repository)
- or just `contents: read` if you don't need any of the above
- `packages: write` if you [push Docker images](/customization/docker/) to GitHub
- `issues: write` if you use [milestone closing capability](/customization/milestone/)

`GITHUB_TOKEN` permissions [are limited to the repository][about-github-token] that contains your workflow.

If you need to push the homebrew tap to another repository, you must create a custom
[Personal Access Token][pat] with `repo` permissions and [add it as a secret in the repository][secrets]. If you
create a secret named `GH_PAT`, the step will look like this:
- `packages: write` if you [push Docker images](/customization/docker/) to
GitHub
- `issues: write` if you use [milestone closing
capability](/customization/milestone/)

`GITHUB_TOKEN` permissions [are limited to the repository][about-github-token]
that contains your workflow.

If you need to push the homebrew tap to another repository, you must create a
custom [Personal Access Token][pat] with `repo` permissions and [add it as a
secret in the repository][secrets]. If you create a secret named `GH_PAT`, the
step will look like this:

```yaml
-
@@ -1,7 +1,7 @@
# Azure Pipelines

GoReleaser can also be used within our official [GoReleaser Extensions for Azure DevOps][goreleaser-extension]
through [Visual Studio marketplace][marketplace].
GoReleaser can also be used within our official [GoReleaser Extensions for Azure
DevOps][goreleaser-extension] through [Visual Studio marketplace][marketplace].

### Task definition

@@ -16,18 +16,21 @@ through [Visual Studio marketplace][marketplace].

### Task inputs

Following inputs can be used
Following inputs can be used:

| Name | Type | Default | Description |
|------------------|---------|--------------|------------------------------------------------------------------|
| `distribution` | String | `goreleaser` | GoReleaser distribution, either `goreleaser` or `goreleaser-pro` |
| `version`[^version] | String | `latest` | GoReleaser version |
| `args` | String | | Arguments to pass to GoReleaser |
| `workdir` | String | `$(Build.SourcesDirectory)` | Working directory (below repository root) |
| `installOnly` | Bool | `false` | Just install GoReleaser |
<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->

Name |Type |Default |Description
-------------------|------|---------------------------|----------------------------------------------------------------
`distribution` |String|`goreleaser` |GoReleaser distribution, either `goreleaser` or `goreleaser-pro`
`version`[^version]|String|`latest` |GoReleaser version
`args` |String| |Arguments to pass to GoReleaser
`workdir` |String|`$(Build.SourcesDirectory)`|Working directory (below repository root)
`installOnly` |Bool |`false` |Just install GoReleaser

[^version]: Can be a fixed version like `v1.10.0` or a max satisfying semver one like `~> v1.10`. In this case this will return the latest patch release of `v1.10`. For the `pro` version, add `-pro` to the string
[^version]: Can be a fixed version like `v1.10.0` or a max satisfying semver one
like `~> v1.10`. In this case this will return the latest patch release of
`v1.10`. For the `pro` version, add `-pro` to the string

### Task environment variables

@@ -48,10 +51,10 @@ variables:

Following environment variables can be used, as environment variable.

| Name | Description |
|------------------|---------------------------------------|
| `GITHUB_TOKEN` | [GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) for e.g. `brew` |
| `GORELEASER_KEY` | Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution |
Name |Description
----------------|------------------------------------------------------------------------------------------------------------------------------------------
`GITHUB_TOKEN` |[GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) for e.g. `brew`
`GORELEASER_KEY`|Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution

### Example pipeline

@@ -10,7 +10,7 @@ each configured Artifactory.

If you have only one Artifactory instance,
the configuration is as easy as adding the
upload target and a username to your `.goreleaser.yaml` file:
upload target, and a username to your `.goreleaser.yaml` file:

```yaml
artifactories:
@@ -53,13 +53,11 @@ Supported variables:

Your configured username needs to be authenticated against your Artifactory.

You can have the username set in the configuration file as shown above
or you can have it read from an environment variable.
The configured name of your Artifactory instance will be used to build
the environment variable name.
This way we support auth for multiple instances.
This also means that the `name` per configured instance needs to be unique
per goreleaser configuration.
You can have the username set in the configuration file as shown above, or you
can have it read from an environment variable. The configured name of your
Artifactory instance will be used to build the environment variable name. This
way we support authentication for multiple instances. This also means that the
`name` per configured instance needs to be unique per GoReleaser configuration.

The name of the environment variable will be `ARTIFACTORY_NAME_USERNAME`.
If your instance is named `production`, you can store the username in the
@@ -56,7 +56,7 @@ aurs:
# The SSH private key that should be used to commit to the Git repository.
# This can either be a path or the key contents.
#
# WARNING: do not expose your private key in the config file!
# WARNING: do not expose your private key in the configuration file!
private_key: '{{ .Env.AUR_KEY }}'
# The AUR Git URL for this package.
@@ -84,7 +84,7 @@ chain in the following order:

### Azure Blob Provider

Currently it supports authentication only with
It supports authentication only with
[environment variables](https://docs.microsoft.com/en-us/azure/storage/common/storage-azure-cli#set-default-azure-storage-account-environment-variables):

- `AZURE_STORAGE_ACCOUNT`
@@ -257,13 +257,15 @@ builds:

The binary name field supports [templating](/customization/templates/). The following build details are exposed:

| Key | Description |
|---------|----------------------------------|
| .Os | `GOOS` |
| .Arch | `GOARCH` |
| .Arm | `GOARM` |
| .Ext | Extension, e.g. `.exe` |
| .Target | Build target, e.g. `darwin_amd64`|
<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->

Key |Description
-------|---------------------------------
.Os |`GOOS`
.Arch |`GOARCH`
.Arm |`GOARM`
.Ext |Extension, e.g. `.exe`
.Target|Build target, e.g. `darwin_amd64`

## Passing environment variables to ldflags

@@ -333,12 +335,15 @@ All properties of a hook (`cmd`, `dir` and `env`) support [templating](/customiz
with `post` hooks having binary artifact available (as these run _after_ the build).
Additionally the following build details are exposed to both `pre` and `post` hooks:

| Key | Description |
|---------|----------------------------------------|
| .Name | Filename of the binary, e.g. `bin.exe` |
| .Ext | Extension, e.g. `.exe` |
| .Path | Absolute path to the binary |
| .Target | Build target, e.g. `darwin_amd64` |

<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->

Key |Description
-------|--------------------------------------
.Name |Filename of the binary, e.g. `bin.exe`
.Ext |Extension, e.g. `.exe`
.Path |Absolute path to the binary
.Target|Build target, e.g. `darwin_amd64`

Environment variables are inherited and overridden in the following order:

@@ -1,19 +1,22 @@
# Docker Manifests

GoReleaser can also create and push Docker multi-platform images using the `docker manifest` tool.
GoReleaser can also create and push Docker multi-platform images using the
`docker manifest` tool.

For it to work, it needs to be enabled in the [client's configuration](https://github.com/docker/cli/blob/master/experimental/README.md).
For it to work, it needs to be enabled in the
[client's configuration](https://github.com/docker/cli/blob/master/experimental/README.md).

Please make sure `docker manifest` works before opening issues.

Notice that if you have something in the `docker_manifests` section in your
config file, GoReleaser will add the manifest's to the release notes
instead of the Docker images names.
config file, GoReleaser will add the manifest's to the release notes instead of
the Docker images names.

!!! warning
Notice that the images used in the manifest **need to be pushed** for this to work.
This is a limitation of how `docker manifest create` works.
For more info, check [this issue](https://github.com/goreleaser/goreleaser/issues/2606).
Notice that the images used in the manifest **need to be pushed** for this
to work. This is a limitation of how `docker manifest create` works. For
more info, check
[this issue](https://github.com/goreleaser/goreleaser/issues/2606).

## Customization

@@ -25,7 +28,8 @@ options available:
docker_manifests:
# You can have multiple Docker manifests.
-
# ID of the manifest, needed if you want to filter by it later on (e.g. on custom publishers).
# ID of the manifest, needed if you want to filter by it later on (e.g. on
# custom publishers).
id: myimg
# Name template for the manifest.
@@ -63,7 +67,8 @@ docker_manifests:
#
# Relevant notes:
# 1. podman is a GoReleaser Pro feature and is only available on Linux;
# 2. if you set podman here, the respective docker configs need to use podman too.
# 2. if you set podman here, the respective docker configs need to use podman
# too.
#
# Defaults to docker.
use: docker
@@ -75,7 +80,7 @@ docker_manifests:
## How it works

We basically build and push our images as usual, but we also add a new
section to our config defining which images are part of which manifests.
section to our configuration defining, which images are part of which manifests.

GoReleaser will create and publish the manifest in its publishing phase.

@@ -86,7 +91,7 @@ GoReleaser will create and publish the manifest in its publishing phase.
## Example config

In this example we will use Docker's `--platform` option to specify the target platform.
This way we can use the same `Dockerfile` for both the `amd64` and the `arm64`
This way we can use the same `Dockerfile` for both the `amd64`, and the `arm64`
images (and possibly others):

```dockerfile
@@ -96,8 +101,8 @@ ENTRYPOINT ["/usr/bin/mybin"]
COPY mybin /usr/bin/mybin
```

Then, on our GoReleaser config file, we need to define both the `dockers` and
the `docker_manifests` section:
Then, on our GoReleaser configuration file, we need to define both the
`dockers`, and the `docker_manifests` section:

```yaml
# .goreleaser.yaml
@@ -142,7 +147,8 @@ and push everything to Docker Hub.
!!! success "GoReleaser Pro"
The podman backend is a [GoReleaser Pro feature](/pro/).

You can use [`podman`](https://podman.io) instead of `docker` by setting `use` to `podman` on your config:
You can use [`podman`](https://podman.io) instead of `docker` by setting `use`
to `podman` on your configuration:

```yaml
# .goreleaser.yaml
@@ -154,4 +160,5 @@ docker_manifests:
use: podman
```

Note that GoReleaser will not install Podman for you, nor change any of its configuration.
Note that GoReleaser will not install Podman for you, nor change any of its
configuration.

0 comments on commit c196592

Please sign in to comment.