Skip to content

Commit 11f7154

Browse files
committed
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.
1 parent 53e21c6 commit 11f7154

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

Diff for: docs/FAQ.md

+50
Original file line numberDiff line numberDiff line change
@@ -58,3 +58,53 @@ In order to be certain your installation of a package dependency will be availab
5858
```
5959

6060
---
61+
62+
## How can I install a platform or library dependency from an external private repository?
63+
64+
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.
65+
66+
With a public repository, the dependency definition will look something like this:
67+
68+
```yaml
69+
libraries: |
70+
- source-url: https://github.com/arduino-libraries/Servo.git
71+
```
72+
73+
However, if `arduino-libraries/Servo` was a private repository the installation of this library by the action would fail:
74+
75+
```text
76+
fatal: could not read Username for 'https://github.com': No such device or address
77+
```
78+
79+
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:
80+
81+
```text
82+
https://<token>@github.com/<repo slug>.git
83+
```
84+
85+
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.
86+
87+
---
88+
89+
**ⓘ** 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).
90+
91+
---
92+
93+
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.
94+
95+
---
96+
97+
**Example:**
98+
99+
```yaml
100+
- uses: arduino/compile-sketches@v1
101+
with:
102+
libraries: |
103+
- source-url: https://${{ secrets.REPO_SCOPE_TOKEN }}@github.com/octocat/SomePrivateLib.git
104+
```
105+
106+
---
107+
108+
**ⓘ** 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.
109+
110+
---

0 commit comments

Comments
 (0)