Read-only mirror — the public repositories of the Forgejo instance, refreshed every 10 minutes. The live instance (fg.dieschoenewolke.de) is reachable only over the VPN; clone here with https://git.dieschoenewolke.de/git/<owner>/<repo>.git.
summaryrefslogtreecommitdiff
path: root/adrs/0153-checkout-v2.md
blob: 981b1142276098f6e2d910b808b7c0411cf47267 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
# ADR 0153: Checkout v2

**Date**: 2019-10-21

**Status**: Accepted

## Context

This ADR details the behavior for `actions/checkout@v2`.

The new action will be written in typescript. We are moving away from runner-plugin actions.

We want to take this opportunity to make behavioral changes, from v1. This document is scoped to those differences.

## Decision

### Inputs

```yaml
  repository:
    description: 'Repository name with owner. For example, actions/checkout'
    default: ${{ github.repository }}
  ref:
    description: >
      The branch, tag or SHA to checkout. When checking out the repository that
      triggered a workflow, this defaults to the reference or SHA for that
      event.  Otherwise, defaults to `master`.
  token:
    description: >
      Auth token used to fetch the repository. The token is stored in the local
      git config, which enables your scripts to run authenticated git commands.
      The post-job step removes the token from the git config. [Learn more about
      creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    default: ${{ github.token }}
  persist-credentials:
    description: 'Whether to persist the token in the git config'
    default: true
  path:
    description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
  clean:
    description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
    default: true
  fetch-depth:
    description: 'Number of commits to fetch. 0 indicates all history.'
    default: 1
  fetch-refs:
    description: >
      Additional refs to fetch: `branches`, `tags`, `pr-base`, or `all`.
      Combinations are also accepted. For example: `branches, tags`
    default: ''
  lfs:
    description: 'Whether to download Git-LFS files'
    default: false
```

Note:
- `fetch-refs` is new
- `persist-credentials` is new
- `path` behavior is different (refer [below](#path) for details)
- `submodules` was removed (error if specified; add later if needed)

### Fallback to GitHub API

When a sufficient version of git is not in the PATH, fallback to the [web API](https://developer.github.com/v3/repos/contents/#get-archive-link) to download a tarball/zipball.

Note:
- LFS files are not included in the archive. Therefore fail if LFS is set to true.
- Submodules are also not included in the archive. However submodules are not supported by checkout v2 anyway.

### Persist credentials

Persist the token in the git config (http.extraheader). This will allow users to script authenticated git commands, like `git fetch`.

A post script will remove the credentials from the git config (cleanup for self-hosted).

Users may opt-out by specifying `persist-credentials: false`

Note:
- Users scripting `git commit` may need to set the username and email. The service does not provide any reasonable default value. Users can add `git config user.name <NAME>` and `git config user.email <EMAIL>`. We will document this guidance.
- The auth header (stored in the repo's git config), is scoped to all of github `http.https://github.com/.extraheader`
  - Additional public remotes also just work.
  - If users want to authenticate to an additional private remote, they should provide the `token` input.
  - Lines up if we add submodule support in the future. Don't need to worry about calculating relative URLs. Just works, although needs to be persisted in each submodule git config.
  - Users opt out of persisted credentials (`persist-credentials: false`), or can script the removal themselves (`git config --unset-all http.https://github.com/.extraheader`).

### Fetch behavior

Fetch only the SHA being built and set depth=1. This significantly reduces the fetch time for large repos.

If a SHA isn't available (e.g. multi repo), then fetch only the specified ref with depth=1.

The input `fetch-depth` can be used to control the depth.

The input `fetch-refs` can be used to fetch additional refs.

Note:
- Fetching a single commit is supported by Git wire protocol version 2. The git client uses protocol version 0 by default. The desired protocol version can be overridden in the git config or on the fetch command line invocation (`-c protocol.version=2`). We will override on the fetch command line, for transparency.
- Git client version 2.18+ (released June 2018) is required for wire protocol version 2.

### Checkout behavior

For CI, checkout will create a local ref with the upstream set. This allows users to script git as they normally would.

For PR, continue to checkout detached head. The PR branch is special - the branch and merge commit are created by the server. It doesn't match a users' local workflow.

Note:
- Consider deleting all local refs during cleanup if that helps avoid collisions. More testing required.

### Path

For the mainline scenario, the disk-layout behavior remains the same.

Remember, given the repo `johndoe/foo`, the mainline disk layout looks like:

```
GITHUB_WORKSPACE=/home/runner/work/foo/foo
RUNNER_WORKSPACE=/home/runner/work/foo
```

V2 introduces a new contraint on the checkout path. The location must now be under `github.workspace`. Whereas the checkout@v1 constraint was one level up, under `runner.workspace`.

V2 no longer changes `github.workspace` to follow wherever the self repo is checked-out.

These behavioral changes align better with container actions. The [documented filesystem contract](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#docker-container-filesystem) is:

- `/github/home`
- `/github/workspace` - Note: GitHub Actions must be run by the default Docker user (root). Ensure your Dockerfile does not set the USER instruction, otherwise you will not be able to access `GITHUB_WORKSPACE`.
- `/github/workflow`

Note:
- The tracking config will not be updated to reflect the path of the workflow repo.
- Any existing workflow repo will not be moved when the checkout path changes. In fact some customers want to checkout the workflow repo twice, side by side against different branches.
- Actions that need to operate only against the root of the self repo, should expose a `path` input.

#### Default value for `path` input

The `path` input will default to `./` which is rooted against `github.workspace`.

This default fits the mainline scenario well: single checkout

For multi-checkout, users must specify the `path` input for at least one of the repositories.

Note:
- An alternative is for the self repo to default to `./` and other repos default to `<REPO_NAME>`. However nested layout is an atypical git layout and therefore is not a good default. Users should supply the path info.

#### Example - Nested layout

The following example checks-out two repositories and creates a nested layout.

```yaml
# Self repo - Checkout to $GITHUB_WORKSPACE
- uses: checkout@v2

# Other repo - Checkout to $GITHUB_WORKSPACE/myscripts
- uses: checkout@v2
  with:
    repository: myorg/myscripts
    path: myscripts
```

#### Example - Side by side layout

The following example checks-out two repositories and creates a side-by-side layout.

```yaml
# Self repo - Checkout to $GITHUB_WORKSPACE/foo
- uses: checkout@v2
  with:
    path: foo

# Other repo - Checkout to $GITHUB_WORKSPACE/myscripts
- uses: checkout@v2
  with:
    repository: myorg/myscripts
    path: myscripts
```

#### Path impact to problem matchers

Problem matchers associate the source files with annotations.

Today the runner verifies the source file is under the `github.workspace`. Otherwise the source file property is dropped.

Multi-checkout complicates the matter. However even today submodules may cause this heuristic to be inaccurate.

A better solution is:

Given a source file path, walk up the directories until the first `.git/config` is found. Check if it matches the self repo (`url = https://github.com/OWNER/REPO`). If not, drop the source file path.

### Port to typescript

The checkout action should be a typescript action on the GitHub graph, for the following reasons:
- Enables customers to fork the checkout repo and modify
- Serves as an example for customers
- Demystifies the checkout action manifest
- Simplifies the runner
- Reduce the amount of runner code to port (if we ever do)

Note:
- This means job-container images will need git in the PATH, for checkout.

### Branching strategy and release tags

- Create a servicing branch for V1: `releases/v1`
- Merge the changes into `master`
- Release using a new tag `preview`
- When stable, release using a new tag `v2`

## Consequences

- Update the checkout action and readme
- Update samples to consume `actions/checkout@v2`
- Job containers now require git in the PATH for checkout, otherwise fallback to REST API
- Minimum git version 2.18
- Update problem matcher logic regarding source file verification (runner)