# Source<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== Description

The "source" stage retrieves information from a third "resource" like a file, or an API and then uses that information in later stages.

A source is the only stage that never modifies anything: it just reads a value, optionally reshapes it with
link:/docs/core/transformer/[transformers], and hands it over to the conditions and targets of the manifest.

Most sources return a list of candidate versions and pick one according to their `versionfilter`.
See link:/docs/core/versionfilter/[version filter] for the available strategies.

TIP: Within a single Updatecli run, sources sharing the same `kind`, `spec`, and resolved repository are executed only once, and the result is reused. Naming them differently, or attaching different transformers, does not trigger a second call (which keeps API rate limits under control when many pipelines track the same dependency).

== Parameters

{{< coreparameters "sources" >}}

== Example

=== Transform source output

.updatecli.yaml
```
sources:
  latestVersion:
    name: Get latest Venom release
    kind: githubrelease
    spec:
      owner: ovh
      repository: venom
      # Value from environment variable '$UPDATECLI_GITHUB_TOKEN'
      token: '{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}'
      versionfilter:
        kind: semver
    transformers:
      - trimprefix: "v"
```

The https://github.com/ovh/venom[ovh/venom] releases are tagged like `v1.2.0`, while the value we want to
write in a target is `1.2.0`.
The `trimprefix` transformer removes the leading `v`, so the output of this source becomes `1.2.0`.

=== Combine multiple sources

In Updatecli, sources define values (like version numbers) to use in your update logic.

You can combine outputs from multiple sources in a target, a condition, or even another source by using Go templating, like this:

```
sources:
  appVersion:
    kind: githubrelease
    spec:
      owner: myorg
      repository: myapp

  chartVersion:
    kind: helmchart
    spec:
      name: mychart

targets:
  updateChart:
    name: "Update Helm chart with app and chart versions"
    kind: file
    disablesourceinput: true
    spec:
      file: charts/myapp/Chart.yaml
      matchpattern: "version: .*"
      replacepattern: 'version: {{ source "chartVersion" }}'
```

Now, if you wanted to use both versions in one target, for example in a file or title, you can do something like this:

```
replacepattern: 'appVersion: {{ source "appVersion" }}, chartVersion: {{ source "chartVersion" }}'
```

Here are a few important concepts to understand:
By default any condition or target inherites a source output, so we want to disable that behavior by setting `disablesourceinput: true`.

Combining multiple sources output is useful when:

Another resource needs information from more than one source, like updating multiple versions in the same file or message.

You want to compose a more informative or specific change, like:

```
image: 'myapp:{{ source "appVersion" }}-{{ source "buildNumber" }}'
```

PR titles like:

```
"chore: 'bump app to {{ source "appVersion" }} and chart to {{ source "chartVersion" }}"'
```