From 11f7154487b4ca7622e9952126868588c8b92507 Mon Sep 17 00:00:00 2001
From: per1234 <accounts@perglass.com>
Date: Tue, 5 Sep 2023 13:19:06 -0700
Subject: [PATCH] Document how to source platform/library dependencies from
 private repo

The action supports installing platform and library dependencies of the sketches by cloning the repository specified via
the source-url field of the platforms or libraries inputs.

The information provided in the relevant documentation in the readme should be sufficient for the action user to
accomplish this when the dependency is in a public repository. Although that information is also applicable for private
repositories, it is more complex to make the necessary configuration of the workflow, repository, and user account. So
the users might appreciate some additional guidance for this use case.

Since this configuration is general to using Git, GitHub, and GitHub Actions workflows rather than something specific to
the action itself, it is out of scope for the primary documentation in the readme. An item in the supplemental FAQ will
be the most appropriate place for this information.
---
 docs/FAQ.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 29b31f9..88d2198 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -58,3 +58,53 @@ In order to be certain your installation of a package dependency will be availab
 ```
 
 ---
+
+## How can I install a platform or library dependency from an external private repository?
+
+The **arduino/compile-sketches** action supports installing platform and library dependencies of the sketches by cloning the repository specified via the `source-url` field of the [`platforms`](../README.md#platforms) or [`libraries`](../README.md#libraries) inputs.
+
+With a public repository, the dependency definition will look something like this:
+
+```yaml
+libraries: |
+  - source-url: https://github.com/arduino-libraries/Servo.git
+```
+
+However, if `arduino-libraries/Servo` was a private repository the installation of this library by the action would fail:
+
+```text
+fatal: could not read Username for 'https://github.com': No such device or address
+```
+
+In this case is necessary to configure the repository URL to provide the authentication required for **Git** to clone the repository, as documented [**here**](https://git-scm.com/docs/git-clone#_git_urls). For private GitHub repositories, the following URL format can be used:
+
+```text
+https://<token>@github.com/<repo slug>.git
+```
+
+where `<token>` is a "[personal access token](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-personal-access-tokens)" with `repo` scope from the account of a user with access to the private repository.
+
+---
+
+**ⓘ** You might find it convenient to create the token under a ["machine user" account](https://docs.github.com/authentication/connecting-to-github-with-ssh/managing-deploy-keys#machine-users).
+
+---
+
+In order to avoid leaking the token, it must be stored in a [secret](https://docs.github.com/actions/security-guides/using-secrets-in-github-actions), and that secret [referenced](https://docs.github.com/actions/security-guides/using-secrets-in-github-actions#using-secrets-in-a-workflow) in the URL.
+
+---
+
+**Example:**
+
+```yaml
+- uses: arduino/compile-sketches@v1
+  with:
+    libraries: |
+      - source-url: https://${{ secrets.REPO_SCOPE_TOKEN }}@github.com/octocat/SomePrivateLib.git
+```
+
+---
+
+**ⓘ** The automatically generated [`GITHUB_TOKEN` secret](https://docs.github.com/actions/security-guides/automatic-token-authentication#about-the-github_token-secret) can not be used for this purpose as it lacks the necessary permissions.
+
+---