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

== Description

In the lifecycle of a software project, dependencies are everywhere.
From that third application used to lint our code, the tool used to build our documentation website, or the container image used to distribute our application.
As the project grows, the number of dependencies grows as long.
Some dependencies are context-dependent, and others are expressed using a standard data structure.

Updatecli is a great tool to handle both situations.
It can either manage tailored update scenarios by using a manifest provided by a maintainer or automatically identify available update scenarios.

The latter approach removes the need to write a manifest.
This behavior is referred to as "autodiscovery".
With autodiscovery enabled, updatecli generates manifests in-memory before applying them (instead of reading manifests and applying).

A use case: a repository with a collection of `Dockerfile`s.
To keep the Dockerfiles' `FROM` instructions up to date, writing one manifest file per `Dockerfile` isn't practical. With autodiscovery enabled, Updatecli scans the repository for all `Dockerfile` and automatically tracks the `FROM` instruction to propose updates if needed.
This helps us maintain our Dockerfile images without having to write manifests.
Each autodiscovery scenario is handled by a crawler.
The goal of the crawler is to recursively parse all files in a directory, looking for the pattern and then try to generate as many updatecli manifests as possible.
Once all manifests have been generated, we run them as we would do with custom manifests, by running updatecli diff or updatecli apply.
This autodiscovery is enabled by default and should work out of the box just by running one of the following commands.

* `updatecli diff`
* `updatecli show`
* `updatecli apply`

As with any opinionated way of working, a bit of adaptability is required.
The next part of this document covers the different kinds of customization that can be used with autodiscovery.


== Parameters


{{< autodiscoverycoreparameters >}}


Autodiscovery could benefit from some customization, such as providing SCM configuration or defining pull request information.
Some parameters are crawler specific and others apply to all crawlers.

If a updatecli manifest specifies the root key "autodiscovery", such as in the following example, then on top of the default autodiscovery, it enables an additional autodiscovery feature.
Here we clone the epinio/helm-chart repository in a temporary location and then look in that location for all Helm charts that specify dependencies and we try to update them.

++++
<details><summary>Example</summary>

<pre>
scms:
  default:
    kind: git
    spec:
      url: https://github.com/epinio/helm-charts.git
autodiscovery:
  scmid: default
  crawlers:
    helm:
</pre>

</details>
++++

By default, autodiscovery looks for patterns from the local directory.
We can also specify manifests from remote git repositories.

=== SCM

We assume that each crawler relies on the same SCM configuration and we can add more autodiscovery manifests to handle more repositories.

=== Pull Request

You can configure Updatecli to create a single pull request that includes all
autodiscovered changes by adding the `actionid` key to the `autodiscovery`
section of your manifest. This key should reference a pull request action
defined in your manifest's `actions` section.

Here's an example configuration for a GitHub pull request action:

++++
<details><summary>Example</summary>

  <pre>
autodiscovery:
  groupby: all
  scmid: github
  actionid: pr

actions:
  pr:
    kind: github/pullrequest
    scmid: github
    spec:
      title: Pull request title

scms:
  github:
    kind: "github"
    spec:
      user: "user"
      email: "updatecli@example.org"
      owner: "my-org"
      repository: "my-repo"
      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
      username: '{{ requiredEnv "GITHUB_AUTHOR" }}'

  </pre>
</details>
++++

==== One Pull request or many

The attribute `autodiscovery.groupby` can have the values:
- `all` (default) to create one pull request with all changes
- `individual` to create one pull request per change


=== Crawlers

Crawlers implement common update scenarios.

You can read more about the different crawlers by browsing the Plugins ->
Autodiscovery section of the documentation.

==== Type

The purpose of a crawler is to generate a manifest that updatecli can use.
We identify two kinds of crawler, "standard", and "custom".

**standard**

A "standard" crawler is enabled by default but can be disabled on a case by case basis.

**custom**

A "custom" crawler is context specific, such as tailored to a company or a OSS project.
By default it isn't enabled.