fail when submodules or ssh-key and fallback to REST API

* Handle submodules with SSH URLs

This is just a documentation change, explaining how to fix submodules
that are configured to use SSH URLs instead of HTTPS URLs. Spent a while
banging my head on the wall and hope this saves someone else the pain.

This is helpful for teams that use the SSH protocol for local
development so don't want to change the mechanism that pulls in the
submodules. Using `insteadOf` seems a bit nicer than than setting up a
deploy keypair.

* SSH submodules

Co-authored-by: Chris Patterson <chrispat@github.com>

.github/workflows/test.yml

@@ -11,13 +11,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
       - uses: actions/checkout@v2
       - run: npm ci
       - run: npm run build
       - run: npm run format-check
       - run: npm run lint
-      - run: npm run pack
-      - run: npm run gendocs
       - run: npm test
       - name: Verify no unstaged changes
         run: __test__/verify-no-unstaged-changes.sh
@@ -34,7 +35,7 @@ jobs:
         uses: actions/checkout@v2
 
       # Basic checkout
-      - name: Basic checkout
+      - name: Checkout basic
         uses: ./
         with:
           ref: test-data/v2/basic
@@ -47,7 +48,7 @@ jobs:
       - name: Modify work tree
         shell: bash
         run: __test__/modify-work-tree.sh
-      - name: Clean checkout
+      - name: Checkout clean
         uses: ./
         with:
           ref: test-data/v2/basic
@@ -57,12 +58,12 @@ jobs:
         run: __test__/verify-clean.sh
 
       # Side by side
-      - name: Side by side checkout 1
+      - name: Checkout side by side 1
         uses: ./
         with:
           ref: test-data/v2/side-by-side-1
           path: side-by-side-1
-      - name: Side by side checkout 2
+      - name: Checkout side by side 2
         uses: ./
         with:
           ref: test-data/v2/side-by-side-2
@@ -72,7 +73,7 @@ jobs:
         run: __test__/verify-side-by-side.sh
 
       # LFS
-      - name: LFS checkout
+      - name: Checkout LFS
         uses: ./
         with:
           repository: actions/checkout # hardcoded, otherwise doesn't work from a fork
@@ -83,16 +84,121 @@ jobs:
         shell: bash
         run: __test__/verify-lfs.sh
 
-  test-job-container:
-    runs-on: ubuntu-latest
-    container: alpine:latest
-    steps:
-      # Clone this repo
-      - name: Checkout
-        uses: actions/checkout@v2
+      # Submodules false
+      - name: Checkout submodules false
+        uses: ./
+        with:
+          ref: test-data/v2/submodule-ssh-url
+          path: submodules-false
+      - name: Verify submodules false
+        run: __test__/verify-submodules-false.sh
 
-      # Basic checkout
-      - name: Basic checkout
+      # Submodules one level
+      - name: Checkout submodules true
+        uses: ./
+        with:
+          ref: test-data/v2/submodule-ssh-url
+          path: submodules-true
+          submodules: true
+      - name: Verify submodules true
+        run: __test__/verify-submodules-true.sh
+
+      # Submodules recursive
+      - name: Checkout submodules recursive
+        uses: ./
+        with:
+          ref: test-data/v2/submodule-ssh-url
+          path: submodules-recursive
+          submodules: recursive
+      - name: Verify submodules recursive
+        run: __test__/verify-submodules-recursive.sh
+
+      # Basic checkout using REST API
+      - name: Remove basic
+        if: runner.os != 'windows'
+        run: rm -rf basic
+      - name: Remove basic (Windows)
+        if: runner.os == 'windows'
+        shell: cmd
+        run: rmdir /s /q basic
+      - name: Override git version
+        if: runner.os != 'windows'
+        run: __test__/override-git-version.sh
+      - name: Override git version (Windows)
+        if: runner.os == 'windows'
+        run: __test__\\override-git-version.cmd
+      - name: Checkout basic using REST API
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: basic
+      - name: Verify basic
+        run: __test__/verify-basic.sh --archive
+
+  test-proxy:
+    runs-on: ubuntu-latest
+    container:
+      image: alpine/git:latest
+      options: --dns 127.0.0.1
+    services:
+      squid-proxy:
+        image: datadog/squid:latest
+        ports:
+          - 3128:3128
+    env:
+      https_proxy: http://squid-proxy:3128
+    steps:
+      # Clone this repo
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      # Basic checkout using git
+      - name: Checkout basic
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: basic
+      - name: Verify basic
+        run: __test__/verify-basic.sh
+
+      # Basic checkout using REST API
+      - name: Remove basic
+        run: rm -rf basic
+      - name: Override git version
+        run: __test__/override-git-version.sh
+      - name: Basic checkout using REST API
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: basic
+      - name: Verify basic
+        run: __test__/verify-basic.sh --archive
+
+  test-bypass-proxy:
+    runs-on: ubuntu-latest
+    env:
+      https_proxy: http://no-such-proxy:3128
+      no_proxy: api.github.com,github.com
+    steps:
+      # Clone this repo
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      # Basic checkout using git
+      - name: Checkout basic
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: basic
+      - name: Verify basic
+        run: __test__/verify-basic.sh
+      - name: Remove basic
+        run: rm -rf basic
+
+      # Basic checkout using REST API
+      - name: Override git version
+        run: __test__/override-git-version.sh
+      - name: Checkout basic using REST API
         uses: ./
         with:
           ref: test-data/v2/basic

.gitignore

@@ -1,2 +1,3 @@
+__test__/_temp
 lib/
 node_modules/

README.md

@@ -45,14 +45,40 @@ Refer [here](https://github.com/actions/checkout/blob/v1/README.md) for previous
     # Otherwise, defaults to `master`.
     ref: ''
 
-    # 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)
+    # Personal access token (PAT) used to fetch the repository. The PAT is configured
+    # with the local git config, which enables your scripts to run authenticated git
+    # commands. The post-job step removes the PAT.
+    #
+    # We recommend using a service account with the least permissions necessary. Also
+    # when generating a new PAT, select the least scopes necessary.
+    #
+    # [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 }}
     token: ''
 
-    # Whether to persist the token in the git config
+    # SSH key used to fetch the repository. The SSH key is configured with the local
+    # git config, which enables your scripts to run authenticated git commands. The
+    # post-job step removes the SSH key.
+    #
+    # We recommend using a service account with the least permissions necessary.
+    #
+    # [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)
+    ssh-key: ''
+
+    # Known hosts in addition to the user and global host key database. The public SSH
+    # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+    # `ssh-keyscan github.com`. The public key for github.com is always implicitly
+    # added.
+    ssh-known-hosts: ''
+
+    # Whether to perform strict host key checking. When true, adds the options
+    # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
+    # the input `ssh-known-hosts` to configure additional hosts.
+    # Default: true
+    ssh-strict: ''
+
+    # Whether to configure the token or SSH key with the local git config
     # Default: true
     persist-credentials: ''
 
@@ -70,6 +96,15 @@ Refer [here](https://github.com/actions/checkout/blob/v1/README.md) for previous
     # Whether to download Git-LFS files
     # Default: false
     lfs: ''
+
+    # Whether to checkout submodules: `true` to checkout submodules or `recursive` to
+    # recursively checkout submodules.
+    #
+    # When the `ssh-key` input is not provided, SSH URLs beginning with
+    # `git@github.com:` are converted to HTTPS.
+    #
+    # Default: false
+    submodules: ''
 ```
 <!-- end usage -->
 
@@ -180,6 +215,8 @@ jobs:
 - name: Checkout submodules
   shell: bash
   run: |
+    # If your submodules are configured to use SSH instead of HTTPS please uncomment the following line
+    # git config --global url."https://github.com/".insteadOf "git@github.com:"
     auth_header="$(git config --local --get http.https://github.com/.extraheader)"
     git submodule sync --recursive
     git -c "http.extraheader=$auth_header" -c protocol.version=2 submodule update --init --force --recursive --depth=1

__test__/git-auth-helper.test.ts

@@ -0,0 +1,799 @@
+import * as core from '@actions/core'
+import * as fs from 'fs'
+import * as gitAuthHelper from '../lib/git-auth-helper'
+import * as io from '@actions/io'
+import * as os from 'os'
+import * as path from 'path'
+import * as stateHelper from '../lib/state-helper'
+import {IGitCommandManager} from '../lib/git-command-manager'
+import {IGitSourceSettings} from '../lib/git-source-settings'
+
+const isWindows = process.platform === 'win32'
+const testWorkspace = path.join(__dirname, '_temp', 'git-auth-helper')
+const originalRunnerTemp = process.env['RUNNER_TEMP']
+const originalHome = process.env['HOME']
+let workspace: string
+let localGitConfigPath: string
+let globalGitConfigPath: string
+let runnerTemp: string
+let tempHomedir: string
+let git: IGitCommandManager & {env: {[key: string]: string}}
+let settings: IGitSourceSettings
+let sshPath: string
+
+describe('git-auth-helper tests', () => {
+  beforeAll(async () => {
+    // SSH
+    sshPath = await io.which('ssh')
+
+    // Clear test workspace
+    await io.rmRF(testWorkspace)
+  })
+
+  beforeEach(() => {
+    // Mock setSecret
+    jest.spyOn(core, 'setSecret').mockImplementation((secret: string) => {})
+
+    // Mock error/warning/info/debug
+    jest.spyOn(core, 'error').mockImplementation(jest.fn())
+    jest.spyOn(core, 'warning').mockImplementation(jest.fn())
+    jest.spyOn(core, 'info').mockImplementation(jest.fn())
+    jest.spyOn(core, 'debug').mockImplementation(jest.fn())
+
+    // Mock state helper
+    jest.spyOn(stateHelper, 'setSshKeyPath').mockImplementation(jest.fn())
+    jest
+      .spyOn(stateHelper, 'setSshKnownHostsPath')
+      .mockImplementation(jest.fn())
+  })
+
+  afterEach(() => {
+    // Unregister mocks
+    jest.restoreAllMocks()
+
+    // Restore HOME
+    if (originalHome) {
+      process.env['HOME'] = originalHome
+    } else {
+      delete process.env['HOME']
+    }
+  })
+
+  afterAll(() => {
+    // Restore RUNNER_TEMP
+    delete process.env['RUNNER_TEMP']
+    if (originalRunnerTemp) {
+      process.env['RUNNER_TEMP'] = originalRunnerTemp
+    }
+  })
+
+  const configureAuth_configuresAuthHeader =
+    'configureAuth configures auth header'
+  it(configureAuth_configuresAuthHeader, async () => {
+    // Arrange
+    await setup(configureAuth_configuresAuthHeader)
+    expect(settings.authToken).toBeTruthy() // sanity check
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert config
+    const configContent = (
+      await fs.promises.readFile(localGitConfigPath)
+    ).toString()
+    const basicCredential = Buffer.from(
+      `x-access-token:${settings.authToken}`,
+      'utf8'
+    ).toString('base64')
+    expect(
+      configContent.indexOf(
+        `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
+      )
+    ).toBeGreaterThanOrEqual(0)
+  })
+
+  const configureAuth_configuresAuthHeaderEvenWhenPersistCredentialsFalse =
+    'configureAuth configures auth header even when persist credentials false'
+  it(
+    configureAuth_configuresAuthHeaderEvenWhenPersistCredentialsFalse,
+    async () => {
+      // Arrange
+      await setup(
+        configureAuth_configuresAuthHeaderEvenWhenPersistCredentialsFalse
+      )
+      expect(settings.authToken).toBeTruthy() // sanity check
+      settings.persistCredentials = false
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+      // Act
+      await authHelper.configureAuth()
+
+      // Assert config
+      const configContent = (
+        await fs.promises.readFile(localGitConfigPath)
+      ).toString()
+      expect(
+        configContent.indexOf(
+          `http.https://github.com/.extraheader AUTHORIZATION`
+        )
+      ).toBeGreaterThanOrEqual(0)
+    }
+  )
+
+  const configureAuth_copiesUserKnownHosts =
+    'configureAuth copies user known hosts'
+  it(configureAuth_copiesUserKnownHosts, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${configureAuth_copiesUserKnownHosts}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arange
+    await setup(configureAuth_copiesUserKnownHosts)
+    expect(settings.sshKey).toBeTruthy() // sanity check
+
+    // Mock fs.promises.readFile
+    const realReadFile = fs.promises.readFile
+    jest.spyOn(fs.promises, 'readFile').mockImplementation(
+      async (file: any, options: any): Promise<Buffer> => {
+        const userKnownHostsPath = path.join(
+          os.homedir(),
+          '.ssh',
+          'known_hosts'
+        )
+        if (file === userKnownHostsPath) {
+          return Buffer.from('some-domain.com ssh-rsa ABCDEF')
+        }
+
+        return await realReadFile(file, options)
+      }
+    )
+
+    // Act
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    await authHelper.configureAuth()
+
+    // Assert known hosts
+    const actualSshKnownHostsPath = await getActualSshKnownHostsPath()
+    const actualSshKnownHostsContent = (
+      await fs.promises.readFile(actualSshKnownHostsPath)
+    ).toString()
+    expect(actualSshKnownHostsContent).toMatch(
+      /some-domain\.com ssh-rsa ABCDEF/
+    )
+    expect(actualSshKnownHostsContent).toMatch(/github\.com ssh-rsa AAAAB3N/)
+  })
+
+  const configureAuth_registersBasicCredentialAsSecret =
+    'configureAuth registers basic credential as secret'
+  it(configureAuth_registersBasicCredentialAsSecret, async () => {
+    // Arrange
+    await setup(configureAuth_registersBasicCredentialAsSecret)
+    expect(settings.authToken).toBeTruthy() // sanity check
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert secret
+    const setSecretSpy = core.setSecret as jest.Mock<any, any>
+    expect(setSecretSpy).toHaveBeenCalledTimes(1)
+    const expectedSecret = Buffer.from(
+      `x-access-token:${settings.authToken}`,
+      'utf8'
+    ).toString('base64')
+    expect(setSecretSpy).toHaveBeenCalledWith(expectedSecret)
+  })
+
+  const setsSshCommandEnvVarWhenPersistCredentialsFalse =
+    'sets SSH command env var when persist-credentials false'
+  it(setsSshCommandEnvVarWhenPersistCredentialsFalse, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${setsSshCommandEnvVarWhenPersistCredentialsFalse}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arrange
+    await setup(setsSshCommandEnvVarWhenPersistCredentialsFalse)
+    settings.persistCredentials = false
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert git env var
+    const actualKeyPath = await getActualSshKeyPath()
+    const actualKnownHostsPath = await getActualSshKnownHostsPath()
+    const expectedSshCommand = `"${sshPath}" -i "$RUNNER_TEMP/${path.basename(
+      actualKeyPath
+    )}" -o StrictHostKeyChecking=yes -o CheckHostIP=no -o "UserKnownHostsFile=$RUNNER_TEMP/${path.basename(
+      actualKnownHostsPath
+    )}"`
+    expect(git.setEnvironmentVariable).toHaveBeenCalledWith(
+      'GIT_SSH_COMMAND',
+      expectedSshCommand
+    )
+
+    // Asserty git config
+    const gitConfigLines = (await fs.promises.readFile(localGitConfigPath))
+      .toString()
+      .split('\n')
+      .filter(x => x)
+    expect(gitConfigLines).toHaveLength(1)
+    expect(gitConfigLines[0]).toMatch(/^http\./)
+  })
+
+  const configureAuth_setsSshCommandWhenPersistCredentialsTrue =
+    'sets SSH command when persist-credentials true'
+  it(configureAuth_setsSshCommandWhenPersistCredentialsTrue, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${configureAuth_setsSshCommandWhenPersistCredentialsTrue}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arrange
+    await setup(configureAuth_setsSshCommandWhenPersistCredentialsTrue)
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert git env var
+    const actualKeyPath = await getActualSshKeyPath()
+    const actualKnownHostsPath = await getActualSshKnownHostsPath()
+    const expectedSshCommand = `"${sshPath}" -i "$RUNNER_TEMP/${path.basename(
+      actualKeyPath
+    )}" -o StrictHostKeyChecking=yes -o CheckHostIP=no -o "UserKnownHostsFile=$RUNNER_TEMP/${path.basename(
+      actualKnownHostsPath
+    )}"`
+    expect(git.setEnvironmentVariable).toHaveBeenCalledWith(
+      'GIT_SSH_COMMAND',
+      expectedSshCommand
+    )
+
+    // Asserty git config
+    expect(git.config).toHaveBeenCalledWith(
+      'core.sshCommand',
+      expectedSshCommand
+    )
+  })
+
+  const configureAuth_writesExplicitKnownHosts = 'writes explicit known hosts'
+  it(configureAuth_writesExplicitKnownHosts, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${configureAuth_writesExplicitKnownHosts}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arrange
+    await setup(configureAuth_writesExplicitKnownHosts)
+    expect(settings.sshKey).toBeTruthy() // sanity check
+    settings.sshKnownHosts = 'my-custom-host.com ssh-rsa ABC123'
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert known hosts
+    const actualSshKnownHostsPath = await getActualSshKnownHostsPath()
+    const actualSshKnownHostsContent = (
+      await fs.promises.readFile(actualSshKnownHostsPath)
+    ).toString()
+    expect(actualSshKnownHostsContent).toMatch(
+      /my-custom-host\.com ssh-rsa ABC123/
+    )
+    expect(actualSshKnownHostsContent).toMatch(/github\.com ssh-rsa AAAAB3N/)
+  })
+
+  const configureAuth_writesSshKeyAndImplicitKnownHosts =
+    'writes SSH key and implicit known hosts'
+  it(configureAuth_writesSshKeyAndImplicitKnownHosts, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${configureAuth_writesSshKeyAndImplicitKnownHosts}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arrange
+    await setup(configureAuth_writesSshKeyAndImplicitKnownHosts)
+    expect(settings.sshKey).toBeTruthy() // sanity check
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+
+    // Assert SSH key
+    const actualSshKeyPath = await getActualSshKeyPath()
+    expect(actualSshKeyPath).toBeTruthy()
+    const actualSshKeyContent = (
+      await fs.promises.readFile(actualSshKeyPath)
+    ).toString()
+    expect(actualSshKeyContent).toBe(settings.sshKey + '\n')
+    if (!isWindows) {
+      // Assert read/write for user, not group or others.
+      // Otherwise SSH client will error.
+      expect((await fs.promises.stat(actualSshKeyPath)).mode & 0o777).toBe(
+        0o600
+      )
+    }
+
+    // Assert known hosts
+    const actualSshKnownHostsPath = await getActualSshKnownHostsPath()
+    const actualSshKnownHostsContent = (
+      await fs.promises.readFile(actualSshKnownHostsPath)
+    ).toString()
+    expect(actualSshKnownHostsContent).toMatch(/github\.com ssh-rsa AAAAB3N/)
+  })
+
+  const configureGlobalAuth_configuresUrlInsteadOfWhenSshKeyNotSet =
+    'configureGlobalAuth configures URL insteadOf when SSH key not set'
+  it(configureGlobalAuth_configuresUrlInsteadOfWhenSshKeyNotSet, async () => {
+    // Arrange
+    await setup(configureGlobalAuth_configuresUrlInsteadOfWhenSshKeyNotSet)
+    settings.sshKey = ''
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+    await authHelper.configureGlobalAuth()
+
+    // Assert temporary global config
+    expect(git.env['HOME']).toBeTruthy()
+    const configContent = (
+      await fs.promises.readFile(path.join(git.env['HOME'], '.gitconfig'))
+    ).toString()
+    expect(
+      configContent.indexOf(`url.https://github.com/.insteadOf git@github.com`)
+    ).toBeGreaterThanOrEqual(0)
+  })
+
+  const configureGlobalAuth_copiesGlobalGitConfig =
+    'configureGlobalAuth copies global git config'
+  it(configureGlobalAuth_copiesGlobalGitConfig, async () => {
+    // Arrange
+    await setup(configureGlobalAuth_copiesGlobalGitConfig)
+    await fs.promises.writeFile(globalGitConfigPath, 'value-from-global-config')
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Act
+    await authHelper.configureAuth()
+    await authHelper.configureGlobalAuth()
+
+    // Assert original global config not altered
+    let configContent = (
+      await fs.promises.readFile(globalGitConfigPath)
+    ).toString()
+    expect(configContent).toBe('value-from-global-config')
+
+    // Assert temporary global config
+    expect(git.env['HOME']).toBeTruthy()
+    const basicCredential = Buffer.from(
+      `x-access-token:${settings.authToken}`,
+      'utf8'
+    ).toString('base64')
+    configContent = (
+      await fs.promises.readFile(path.join(git.env['HOME'], '.gitconfig'))
+    ).toString()
+    expect(
+      configContent.indexOf('value-from-global-config')
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      configContent.indexOf(
+        `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
+      )
+    ).toBeGreaterThanOrEqual(0)
+  })
+
+  const configureGlobalAuth_createsNewGlobalGitConfigWhenGlobalDoesNotExist =
+    'configureGlobalAuth creates new git config when global does not exist'
+  it(
+    configureGlobalAuth_createsNewGlobalGitConfigWhenGlobalDoesNotExist,
+    async () => {
+      // Arrange
+      await setup(
+        configureGlobalAuth_createsNewGlobalGitConfigWhenGlobalDoesNotExist
+      )
+      await io.rmRF(globalGitConfigPath)
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+      // Act
+      await authHelper.configureAuth()
+      await authHelper.configureGlobalAuth()
+
+      // Assert original global config not recreated
+      try {
+        await fs.promises.stat(globalGitConfigPath)
+        throw new Error(
+          `Did not expect file to exist: '${globalGitConfigPath}'`
+        )
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          throw err
+        }
+      }
+
+      // Assert temporary global config
+      expect(git.env['HOME']).toBeTruthy()
+      const basicCredential = Buffer.from(
+        `x-access-token:${settings.authToken}`,
+        'utf8'
+      ).toString('base64')
+      const configContent = (
+        await fs.promises.readFile(path.join(git.env['HOME'], '.gitconfig'))
+      ).toString()
+      expect(
+        configContent.indexOf(
+          `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
+        )
+      ).toBeGreaterThanOrEqual(0)
+    }
+  )
+
+  const configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeyNotSet =
+    'configureSubmoduleAuth configures submodules when persist credentials false and SSH key not set'
+  it(
+    configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeyNotSet,
+    async () => {
+      // Arrange
+      await setup(
+        configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeyNotSet
+      )
+      settings.persistCredentials = false
+      settings.sshKey = ''
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+      await authHelper.configureAuth()
+      const mockSubmoduleForeach = git.submoduleForeach as jest.Mock<any, any>
+      mockSubmoduleForeach.mockClear() // reset calls
+
+      // Act
+      await authHelper.configureSubmoduleAuth()
+
+      // Assert
+      expect(mockSubmoduleForeach).toBeCalledTimes(1)
+      expect(mockSubmoduleForeach.mock.calls[0][0] as string).toMatch(
+        /unset-all.*insteadOf/
+      )
+    }
+  )
+
+  const configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeySet =
+    'configureSubmoduleAuth configures submodules when persist credentials false and SSH key set'
+  it(
+    configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeySet,
+    async () => {
+      if (!sshPath) {
+        process.stdout.write(
+          `Skipped test "${configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeySet}". Executable 'ssh' not found in the PATH.\n`
+        )
+        return
+      }
+
+      // Arrange
+      await setup(
+        configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsFalseAndSshKeySet
+      )
+      settings.persistCredentials = false
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+      await authHelper.configureAuth()
+      const mockSubmoduleForeach = git.submoduleForeach as jest.Mock<any, any>
+      mockSubmoduleForeach.mockClear() // reset calls
+
+      // Act
+      await authHelper.configureSubmoduleAuth()
+
+      // Assert
+      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(1)
+      expect(mockSubmoduleForeach.mock.calls[0][0]).toMatch(
+        /unset-all.*insteadOf/
+      )
+    }
+  )
+
+  const configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeyNotSet =
+    'configureSubmoduleAuth configures submodules when persist credentials true and SSH key not set'
+  it(
+    configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeyNotSet,
+    async () => {
+      // Arrange
+      await setup(
+        configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeyNotSet
+      )
+      settings.sshKey = ''
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+      await authHelper.configureAuth()
+      const mockSubmoduleForeach = git.submoduleForeach as jest.Mock<any, any>
+      mockSubmoduleForeach.mockClear() // reset calls
+
+      // Act
+      await authHelper.configureSubmoduleAuth()
+
+      // Assert
+      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(3)
+      expect(mockSubmoduleForeach.mock.calls[0][0]).toMatch(
+        /unset-all.*insteadOf/
+      )
+      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(/http.*extraheader/)
+      expect(mockSubmoduleForeach.mock.calls[2][0]).toMatch(/url.*insteadOf/)
+    }
+  )
+
+  const configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeySet =
+    'configureSubmoduleAuth configures submodules when persist credentials true and SSH key set'
+  it(
+    configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeySet,
+    async () => {
+      if (!sshPath) {
+        process.stdout.write(
+          `Skipped test "${configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeySet}". Executable 'ssh' not found in the PATH.\n`
+        )
+        return
+      }
+
+      // Arrange
+      await setup(
+        configureSubmoduleAuth_configuresSubmodulesWhenPersistCredentialsTrueAndSshKeySet
+      )
+      const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+      await authHelper.configureAuth()
+      const mockSubmoduleForeach = git.submoduleForeach as jest.Mock<any, any>
+      mockSubmoduleForeach.mockClear() // reset calls
+
+      // Act
+      await authHelper.configureSubmoduleAuth()
+
+      // Assert
+      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(3)
+      expect(mockSubmoduleForeach.mock.calls[0][0]).toMatch(
+        /unset-all.*insteadOf/
+      )
+      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(/http.*extraheader/)
+      expect(mockSubmoduleForeach.mock.calls[2][0]).toMatch(/core\.sshCommand/)
+    }
+  )
+
+  const removeAuth_removesSshCommand = 'removeAuth removes SSH command'
+  it(removeAuth_removesSshCommand, async () => {
+    if (!sshPath) {
+      process.stdout.write(
+        `Skipped test "${removeAuth_removesSshCommand}". Executable 'ssh' not found in the PATH.\n`
+      )
+      return
+    }
+
+    // Arrange
+    await setup(removeAuth_removesSshCommand)
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    await authHelper.configureAuth()
+    let gitConfigContent = (
+      await fs.promises.readFile(localGitConfigPath)
+    ).toString()
+    expect(gitConfigContent.indexOf('core.sshCommand')).toBeGreaterThanOrEqual(
+      0
+    ) // sanity check
+    const actualKeyPath = await getActualSshKeyPath()
+    expect(actualKeyPath).toBeTruthy()
+    await fs.promises.stat(actualKeyPath)
+    const actualKnownHostsPath = await getActualSshKnownHostsPath()
+    expect(actualKnownHostsPath).toBeTruthy()
+    await fs.promises.stat(actualKnownHostsPath)
+
+    // Act
+    await authHelper.removeAuth()
+
+    // Assert git config
+    gitConfigContent = (
+      await fs.promises.readFile(localGitConfigPath)
+    ).toString()
+    expect(gitConfigContent.indexOf('core.sshCommand')).toBeLessThan(0)
+
+    // Assert SSH key file
+    try {
+      await fs.promises.stat(actualKeyPath)
+      throw new Error('SSH key should have been deleted')
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+    }
+
+    // Assert known hosts file
+    try {
+      await fs.promises.stat(actualKnownHostsPath)
+      throw new Error('SSH known hosts should have been deleted')
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+    }
+  })
+
+  const removeAuth_removesToken = 'removeAuth removes token'
+  it(removeAuth_removesToken, async () => {
+    // Arrange
+    await setup(removeAuth_removesToken)
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    await authHelper.configureAuth()
+    let gitConfigContent = (
+      await fs.promises.readFile(localGitConfigPath)
+    ).toString()
+    expect(gitConfigContent.indexOf('http.')).toBeGreaterThanOrEqual(0) // sanity check
+
+    // Act
+    await authHelper.removeAuth()
+
+    // Assert git config
+    gitConfigContent = (
+      await fs.promises.readFile(localGitConfigPath)
+    ).toString()
+    expect(gitConfigContent.indexOf('http.')).toBeLessThan(0)
+  })
+
+  const removeGlobalAuth_removesOverride = 'removeGlobalAuth removes override'
+  it(removeGlobalAuth_removesOverride, async () => {
+    // Arrange
+    await setup(removeGlobalAuth_removesOverride)
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    await authHelper.configureAuth()
+    await authHelper.configureGlobalAuth()
+    const homeOverride = git.env['HOME'] // Sanity check
+    expect(homeOverride).toBeTruthy()
+    await fs.promises.stat(path.join(git.env['HOME'], '.gitconfig'))
+
+    // Act
+    await authHelper.removeGlobalAuth()
+
+    // Assert
+    expect(git.env['HOME']).toBeUndefined()
+    try {
+      await fs.promises.stat(homeOverride)
+      throw new Error(`Should have been deleted '${homeOverride}'`)
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+    }
+  })
+})
+
+async function setup(testName: string): Promise<void> {
+  testName = testName.replace(/[^a-zA-Z0-9_]+/g, '-')
+
+  // Directories
+  workspace = path.join(testWorkspace, testName, 'workspace')
+  runnerTemp = path.join(testWorkspace, testName, 'runner-temp')
+  tempHomedir = path.join(testWorkspace, testName, 'home-dir')
+  await fs.promises.mkdir(workspace, {recursive: true})
+  await fs.promises.mkdir(runnerTemp, {recursive: true})
+  await fs.promises.mkdir(tempHomedir, {recursive: true})
+  process.env['RUNNER_TEMP'] = runnerTemp
+  process.env['HOME'] = tempHomedir
+
+  // Create git config
+  globalGitConfigPath = path.join(tempHomedir, '.gitconfig')
+  await fs.promises.writeFile(globalGitConfigPath, '')
+  localGitConfigPath = path.join(workspace, '.git', 'config')
+  await fs.promises.mkdir(path.dirname(localGitConfigPath), {recursive: true})
+  await fs.promises.writeFile(localGitConfigPath, '')
+
+  git = {
+    branchDelete: jest.fn(),
+    branchExists: jest.fn(),
+    branchList: jest.fn(),
+    checkout: jest.fn(),
+    checkoutDetach: jest.fn(),
+    config: jest.fn(
+      async (key: string, value: string, globalConfig?: boolean) => {
+        const configPath = globalConfig
+          ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+          : localGitConfigPath
+        await fs.promises.appendFile(configPath, `\n${key} ${value}`)
+      }
+    ),
+    configExists: jest.fn(
+      async (key: string, globalConfig?: boolean): Promise<boolean> => {
+        const configPath = globalConfig
+          ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+          : localGitConfigPath
+        const content = await fs.promises.readFile(configPath)
+        const lines = content
+          .toString()
+          .split('\n')
+          .filter(x => x)
+        return lines.some(x => x.startsWith(key))
+      }
+    ),
+    env: {},
+    fetch: jest.fn(),
+    getWorkingDirectory: jest.fn(() => workspace),
+    init: jest.fn(),
+    isDetached: jest.fn(),
+    lfsFetch: jest.fn(),
+    lfsInstall: jest.fn(),
+    log1: jest.fn(),
+    remoteAdd: jest.fn(),
+    removeEnvironmentVariable: jest.fn((name: string) => delete git.env[name]),
+    setEnvironmentVariable: jest.fn((name: string, value: string) => {
+      git.env[name] = value
+    }),
+    submoduleForeach: jest.fn(async () => {
+      return ''
+    }),
+    submoduleSync: jest.fn(),
+    submoduleUpdate: jest.fn(),
+    tagExists: jest.fn(),
+    tryClean: jest.fn(),
+    tryConfigUnset: jest.fn(
+      async (key: string, globalConfig?: boolean): Promise<boolean> => {
+        const configPath = globalConfig
+          ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+          : localGitConfigPath
+        let content = await fs.promises.readFile(configPath)
+        let lines = content
+          .toString()
+          .split('\n')
+          .filter(x => x)
+          .filter(x => !x.startsWith(key))
+        await fs.promises.writeFile(configPath, lines.join('\n'))
+        return true
+      }
+    ),
+    tryDisableAutomaticGarbageCollection: jest.fn(),
+    tryGetFetchUrl: jest.fn(),
+    tryReset: jest.fn()
+  }
+
+  settings = {
+    authToken: 'some auth token',
+    clean: true,
+    commit: '',
+    fetchDepth: 1,
+    lfs: false,
+    submodules: false,
+    nestedSubmodules: false,
+    persistCredentials: true,
+    ref: 'refs/heads/master',
+    repositoryName: 'my-repo',
+    repositoryOwner: 'my-org',
+    repositoryPath: '',
+    sshKey: sshPath ? 'some ssh private key' : '',
+    sshKnownHosts: '',
+    sshStrict: true
+  }
+}
+
+async function getActualSshKeyPath(): Promise<string> {
+  let actualTempFiles = (await fs.promises.readdir(runnerTemp))
+    .sort()
+    .map(x => path.join(runnerTemp, x))
+  if (actualTempFiles.length === 0) {
+    return ''
+  }
+
+  expect(actualTempFiles).toHaveLength(2)
+  expect(actualTempFiles[0].endsWith('_known_hosts')).toBeFalsy()
+  return actualTempFiles[0]
+}
+
+async function getActualSshKnownHostsPath(): Promise<string> {
+  let actualTempFiles = (await fs.promises.readdir(runnerTemp))
+    .sort()
+    .map(x => path.join(runnerTemp, x))
+  if (actualTempFiles.length === 0) {
+    return ''
+  }
+
+  expect(actualTempFiles).toHaveLength(2)
+  expect(actualTempFiles[1].endsWith('_known_hosts')).toBeTruthy()
+  expect(actualTempFiles[1].startsWith(actualTempFiles[0])).toBeTruthy()
+  return actualTempFiles[1]
+}

__test__/git-directory-helper.test.ts

@@ -0,0 +1,386 @@
+import * as core from '@actions/core'
+import * as fs from 'fs'
+import * as gitDirectoryHelper from '../lib/git-directory-helper'
+import * as io from '@actions/io'
+import * as path from 'path'
+import {IGitCommandManager} from '../lib/git-command-manager'
+
+const testWorkspace = path.join(__dirname, '_temp', 'git-directory-helper')
+let repositoryPath: string
+let repositoryUrl: string
+let clean: boolean
+let git: IGitCommandManager
+
+describe('git-directory-helper tests', () => {
+  beforeAll(async () => {
+    // Clear test workspace
+    await io.rmRF(testWorkspace)
+  })
+
+  beforeEach(() => {
+    // Mock error/warning/info/debug
+    jest.spyOn(core, 'error').mockImplementation(jest.fn())
+    jest.spyOn(core, 'warning').mockImplementation(jest.fn())
+    jest.spyOn(core, 'info').mockImplementation(jest.fn())
+    jest.spyOn(core, 'debug').mockImplementation(jest.fn())
+  })
+
+  afterEach(() => {
+    // Unregister mocks
+    jest.restoreAllMocks()
+  })
+
+  const cleansWhenCleanTrue = 'cleans when clean true'
+  it(cleansWhenCleanTrue, async () => {
+    // Arrange
+    await setup(cleansWhenCleanTrue)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.tryClean).toHaveBeenCalled()
+    expect(git.tryReset).toHaveBeenCalled()
+    expect(core.warning).not.toHaveBeenCalled()
+  })
+
+  const checkoutDetachWhenNotDetached = 'checkout detach when not detached'
+  it(checkoutDetachWhenNotDetached, async () => {
+    // Arrange
+    await setup(checkoutDetachWhenNotDetached)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.checkoutDetach).toHaveBeenCalled()
+  })
+
+  const doesNotCheckoutDetachWhenNotAlreadyDetached =
+    'does not checkout detach when already detached'
+  it(doesNotCheckoutDetachWhenNotAlreadyDetached, async () => {
+    // Arrange
+    await setup(doesNotCheckoutDetachWhenNotAlreadyDetached)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    const mockIsDetached = git.isDetached as jest.Mock<any, any>
+    mockIsDetached.mockImplementation(async () => {
+      return true
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.checkoutDetach).not.toHaveBeenCalled()
+  })
+
+  const doesNotCleanWhenCleanFalse = 'does not clean when clean false'
+  it(doesNotCleanWhenCleanFalse, async () => {
+    // Arrange
+    await setup(doesNotCleanWhenCleanFalse)
+    clean = false
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.isDetached).toHaveBeenCalled()
+    expect(git.branchList).toHaveBeenCalled()
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(git.tryClean).not.toHaveBeenCalled()
+    expect(git.tryReset).not.toHaveBeenCalled()
+  })
+
+  const removesContentsWhenCleanFails = 'removes contents when clean fails'
+  it(removesContentsWhenCleanFails, async () => {
+    // Arrange
+    await setup(removesContentsWhenCleanFails)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    let mockTryClean = git.tryClean as jest.Mock<any, any>
+    mockTryClean.mockImplementation(async () => {
+      return false
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(git.tryClean).toHaveBeenCalled()
+    expect(core.warning).toHaveBeenCalled()
+    expect(git.tryReset).not.toHaveBeenCalled()
+  })
+
+  const removesContentsWhenDifferentRepositoryUrl =
+    'removes contents when different repository url'
+  it(removesContentsWhenDifferentRepositoryUrl, async () => {
+    // Arrange
+    await setup(removesContentsWhenDifferentRepositoryUrl)
+    clean = false
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    const differentRepositoryUrl =
+      'https://github.com/my-different-org/my-different-repo'
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      differentRepositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(git.isDetached).not.toHaveBeenCalled()
+  })
+
+  const removesContentsWhenNoGitDirectory =
+    'removes contents when no git directory'
+  it(removesContentsWhenNoGitDirectory, async () => {
+    // Arrange
+    await setup(removesContentsWhenNoGitDirectory)
+    clean = false
+    await io.rmRF(path.join(repositoryPath, '.git'))
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(git.isDetached).not.toHaveBeenCalled()
+  })
+
+  const removesContentsWhenResetFails = 'removes contents when reset fails'
+  it(removesContentsWhenResetFails, async () => {
+    // Arrange
+    await setup(removesContentsWhenResetFails)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    let mockTryReset = git.tryReset as jest.Mock<any, any>
+    mockTryReset.mockImplementation(async () => {
+      return false
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(git.tryClean).toHaveBeenCalled()
+    expect(git.tryReset).toHaveBeenCalled()
+    expect(core.warning).toHaveBeenCalled()
+  })
+
+  const removesContentsWhenUndefinedGitCommandManager =
+    'removes contents when undefined git command manager'
+  it(removesContentsWhenUndefinedGitCommandManager, async () => {
+    // Arrange
+    await setup(removesContentsWhenUndefinedGitCommandManager)
+    clean = false
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      undefined,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(core.warning).not.toHaveBeenCalled()
+  })
+
+  const removesLocalBranches = 'removes local branches'
+  it(removesLocalBranches, async () => {
+    // Arrange
+    await setup(removesLocalBranches)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    const mockBranchList = git.branchList as jest.Mock<any, any>
+    mockBranchList.mockImplementation(async (remote: boolean) => {
+      return remote ? [] : ['local-branch-1', 'local-branch-2']
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.branchDelete).toHaveBeenCalledWith(false, 'local-branch-1')
+    expect(git.branchDelete).toHaveBeenCalledWith(false, 'local-branch-2')
+  })
+
+  const removesLockFiles = 'removes lock files'
+  it(removesLockFiles, async () => {
+    // Arrange
+    await setup(removesLockFiles)
+    clean = false
+    await fs.promises.writeFile(
+      path.join(repositoryPath, '.git', 'index.lock'),
+      ''
+    )
+    await fs.promises.writeFile(
+      path.join(repositoryPath, '.git', 'shallow.lock'),
+      ''
+    )
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    let files = await fs.promises.readdir(path.join(repositoryPath, '.git'))
+    expect(files).toHaveLength(0)
+    files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.isDetached).toHaveBeenCalled()
+    expect(git.branchList).toHaveBeenCalled()
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(git.tryClean).not.toHaveBeenCalled()
+    expect(git.tryReset).not.toHaveBeenCalled()
+  })
+
+  const removesRemoteBranches = 'removes local branches'
+  it(removesRemoteBranches, async () => {
+    // Arrange
+    await setup(removesRemoteBranches)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    const mockBranchList = git.branchList as jest.Mock<any, any>
+    mockBranchList.mockImplementation(async (remote: boolean) => {
+      return remote ? ['remote-branch-1', 'remote-branch-2'] : []
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.branchDelete).toHaveBeenCalledWith(true, 'remote-branch-1')
+    expect(git.branchDelete).toHaveBeenCalledWith(true, 'remote-branch-2')
+  })
+})
+
+async function setup(testName: string): Promise<void> {
+  testName = testName.replace(/[^a-zA-Z0-9_]+/g, '-')
+
+  // Repository directory
+  repositoryPath = path.join(testWorkspace, testName)
+  await fs.promises.mkdir(path.join(repositoryPath, '.git'), {recursive: true})
+
+  // Repository URL
+  repositoryUrl = 'https://github.com/my-org/my-repo'
+
+  // Clean
+  clean = true
+
+  // Git command manager
+  git = {
+    branchDelete: jest.fn(),
+    branchExists: jest.fn(),
+    branchList: jest.fn(async () => {
+      return []
+    }),
+    checkout: jest.fn(),
+    checkoutDetach: jest.fn(),
+    config: jest.fn(),
+    configExists: jest.fn(),
+    fetch: jest.fn(),
+    getWorkingDirectory: jest.fn(() => repositoryPath),
+    init: jest.fn(),
+    isDetached: jest.fn(),
+    lfsFetch: jest.fn(),
+    lfsInstall: jest.fn(),
+    log1: jest.fn(),
+    remoteAdd: jest.fn(),
+    removeEnvironmentVariable: jest.fn(),
+    setEnvironmentVariable: jest.fn(),
+    submoduleForeach: jest.fn(),
+    submoduleSync: jest.fn(),
+    submoduleUpdate: jest.fn(),
+    tagExists: jest.fn(),
+    tryClean: jest.fn(async () => {
+      return true
+    }),
+    tryConfigUnset: jest.fn(),
+    tryDisableAutomaticGarbageCollection: jest.fn(),
+    tryGetFetchUrl: jest.fn(async () => {
+      // Sanity check - this function shouldn't be called when the .git directory doesn't exist
+      await fs.promises.stat(path.join(repositoryPath, '.git'))
+      return repositoryUrl
+    }),
+    tryReset: jest.fn(async () => {
+      return true
+    })
+  }
+}

__test__/input-helper.test.ts

@@ -1,47 +1,50 @@
 import * as assert from 'assert'
+import * as core from '@actions/core'
+import * as fsHelper from '../lib/fs-helper'
+import * as github from '@actions/github'
+import * as inputHelper from '../lib/input-helper'
 import * as path from 'path'
-import {ISourceSettings} from '../lib/git-source-provider'
+import {IGitSourceSettings} from '../lib/git-source-settings'
 
 const originalGitHubWorkspace = process.env['GITHUB_WORKSPACE']
 const gitHubWorkspace = path.resolve('/checkout-tests/workspace')
 
-// Late bind
-let inputHelper: any
-
-// Mock @actions/core
+// Inputs for mock @actions/core
 let inputs = {} as any
-const mockCore = jest.genMockFromModule('@actions/core') as any
-mockCore.getInput = (name: string) => {
-  return inputs[name]
-}
 
-// Mock @actions/github
-const mockGitHub = jest.genMockFromModule('@actions/github') as any
-mockGitHub.context = {
-  repo: {
-    owner: 'some-owner',
-    repo: 'some-repo'
-  },
-  ref: 'refs/heads/some-ref',
-  sha: '1234567890123456789012345678901234567890'
-}
-
-// Mock ./fs-helper
-const mockFSHelper = jest.genMockFromModule('../lib/fs-helper') as any
-mockFSHelper.directoryExistsSync = (path: string) => path == gitHubWorkspace
+// Shallow clone original @actions/github context
+let originalContext = {...github.context}
 
 describe('input-helper tests', () => {
   beforeAll(() => {
+    // Mock getInput
+    jest.spyOn(core, 'getInput').mockImplementation((name: string) => {
+      return inputs[name]
+    })
+
+    // Mock error/warning/info/debug
+    jest.spyOn(core, 'error').mockImplementation(jest.fn())
+    jest.spyOn(core, 'warning').mockImplementation(jest.fn())
+    jest.spyOn(core, 'info').mockImplementation(jest.fn())
+    jest.spyOn(core, 'debug').mockImplementation(jest.fn())
+
+    // Mock github context
+    jest.spyOn(github.context, 'repo', 'get').mockImplementation(() => {
+      return {
+        owner: 'some-owner',
+        repo: 'some-repo'
+      }
+    })
+    github.context.ref = 'refs/heads/some-ref'
+    github.context.sha = '1234567890123456789012345678901234567890'
+
+    // Mock ./fs-helper directoryExistsSync()
+    jest
+      .spyOn(fsHelper, 'directoryExistsSync')
+      .mockImplementation((path: string) => path == gitHubWorkspace)
+
     // GitHub workspace
     process.env['GITHUB_WORKSPACE'] = gitHubWorkspace
-
-    // Mocks
-    jest.setMock('@actions/core', mockCore)
-    jest.setMock('@actions/github', mockGitHub)
-    jest.setMock('../lib/fs-helper', mockFSHelper)
-
-    // Now import
-    inputHelper = require('../lib/input-helper')
   })
 
   beforeEach(() => {
@@ -50,18 +53,22 @@ describe('input-helper tests', () => {
   })
 
   afterAll(() => {
-    // Reset GitHub workspace
+    // Restore GitHub workspace
     delete process.env['GITHUB_WORKSPACE']
     if (originalGitHubWorkspace) {
       process.env['GITHUB_WORKSPACE'] = originalGitHubWorkspace
     }
 
-    // Reset modules
-    jest.resetModules()
+    // Restore @actions/github context
+    github.context.ref = originalContext.ref
+    github.context.sha = originalContext.sha
+
+    // Restore
+    jest.restoreAllMocks()
   })
 
   it('sets defaults', () => {
-    const settings: ISourceSettings = inputHelper.getInputs()
+    const settings: IGitSourceSettings = inputHelper.getInputs()
     expect(settings).toBeTruthy()
     expect(settings.authToken).toBeFalsy()
     expect(settings.clean).toBe(true)
@@ -75,6 +82,19 @@ describe('input-helper tests', () => {
     expect(settings.repositoryPath).toBe(gitHubWorkspace)
   })
 
+  it('qualifies ref', () => {
+    let originalRef = github.context.ref
+    try {
+      github.context.ref = 'some-unqualified-ref'
+      const settings: IGitSourceSettings = inputHelper.getInputs()
+      expect(settings).toBeTruthy()
+      expect(settings.commit).toBe('1234567890123456789012345678901234567890')
+      expect(settings.ref).toBe('refs/heads/some-unqualified-ref')
+    } finally {
+      github.context.ref = originalRef
+    }
+  })
+
   it('requires qualified repo', () => {
     inputs.repository = 'some-unqualified-repo'
     assert.throws(() => {
@@ -84,7 +104,7 @@ describe('input-helper tests', () => {
 
   it('roots path', () => {
     inputs.path = 'some-directory/some-subdirectory'
-    const settings: ISourceSettings = inputHelper.getInputs()
+    const settings: IGitSourceSettings = inputHelper.getInputs()
     expect(settings.repositoryPath).toBe(
       path.join(gitHubWorkspace, 'some-directory', 'some-subdirectory')
     )
@@ -92,29 +112,22 @@ describe('input-helper tests', () => {
 
   it('sets correct default ref/sha for other repo', () => {
     inputs.repository = 'some-owner/some-other-repo'
-    const settings: ISourceSettings = inputHelper.getInputs()
+    const settings: IGitSourceSettings = inputHelper.getInputs()
     expect(settings.ref).toBe('refs/heads/master')
     expect(settings.commit).toBeFalsy()
   })
 
   it('sets ref to empty when explicit sha', () => {
     inputs.ref = '1111111111222222222233333333334444444444'
-    const settings: ISourceSettings = inputHelper.getInputs()
+    const settings: IGitSourceSettings = inputHelper.getInputs()
     expect(settings.ref).toBeFalsy()
     expect(settings.commit).toBe('1111111111222222222233333333334444444444')
   })
 
   it('sets sha to empty when explicit ref', () => {
     inputs.ref = 'refs/heads/some-other-ref'
-    const settings: ISourceSettings = inputHelper.getInputs()
+    const settings: IGitSourceSettings = inputHelper.getInputs()
     expect(settings.ref).toBe('refs/heads/some-other-ref')
     expect(settings.commit).toBeFalsy()
   })
-
-  it('gives good error message for submodules input', () => {
-    inputs.submodules = 'true'
-    assert.throws(() => {
-      inputHelper.getInputs()
-    }, /The input 'submodules' is not supported/)
-  })
 })

__test__/override-git-version.cmd

@@ -0,0 +1,6 @@
+
+mkdir override-git-version
+cd override-git-version
+echo @echo override git version 1.2.3 > git.cmd
+echo ::add-path::%CD%
+cd ..

__test__/override-git-version.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+mkdir override-git-version
+cd override-git-version
+echo "#!/bin/sh" > git
+echo "echo override git version 1.2.3" >> git
+chmod +x git
+echo "::add-path::$(pwd)"
+cd ..

__test__/retry-helper.test.ts

@@ -1,18 +1,17 @@
-const mockCore = jest.genMockFromModule('@actions/core') as any
-mockCore.info = (message: string) => {
-  info.push(message)
-}
+import * as core from '@actions/core'
+import {RetryHelper} from '../lib/retry-helper'
+
 let info: string[]
 let retryHelper: any
 
 describe('retry-helper tests', () => {
   beforeAll(() => {
-    // Mocks
-    jest.setMock('@actions/core', mockCore)
+    // Mock @actions/core info()
+    jest.spyOn(core, 'info').mockImplementation((message: string) => {
+      info.push(message)
+    })
 
-    // Now import
-    const retryHelperModule = require('../lib/retry-helper')
-    retryHelper = new retryHelperModule.RetryHelper(3, 0, 0)
+    retryHelper = new RetryHelper(3, 0, 0)
   })
 
   beforeEach(() => {
@@ -21,8 +20,8 @@ describe('retry-helper tests', () => {
   })
 
   afterAll(() => {
-    // Reset modules
-    jest.resetModules()
+    // Restore
+    jest.restoreAllMocks()
   })
 
   it('first attempt succeeds', async () => {

__test__/verify-submodules-false.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+if [ ! -f "./submodules-false/regular-file.txt" ]; then
+    echo "Expected regular file does not exist"
+    exit 1
+fi
+
+if [ -f "./submodules-false/submodule-level-1/submodule-file.txt" ]; then
+    echo "Unexpected submodule file exists"
+    exit 1
+fi

__test__/verify-submodules-not-checked-out.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-if [ ! -f "./submodules-not-checked-out/regular-file.txt" ]; then
-    echo "Expected regular file does not exist"
-    exit 1
-fi
-
-if [ -f "./submodules-not-checked-out/submodule-level-1/submodule-file.txt" ]; then
-    echo "Unexpected submodule file exists"
-    exit 1
-fi

__test__/verify-submodules-recursive.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+if [ ! -f "./submodules-recursive/regular-file.txt" ]; then
+    echo "Expected regular file does not exist"
+    exit 1
+fi
+
+if [ ! -f "./submodules-recursive/submodule-level-1/submodule-file.txt" ]; then
+    echo "Expected submodule file does not exist"
+    exit 1
+fi
+
+if [ ! -f "./submodules-recursive/submodule-level-1/submodule-level-2/nested-submodule-file.txt" ]; then
+    echo "Expected nested submodule file does not exists"
+    exit 1
+fi
+
+echo "Testing persisted credential"
+pushd ./submodules-recursive/submodule-level-1/submodule-level-2
+git config --local --name-only --get-regexp http.+extraheader && git fetch
+if [ "$?" != "0" ]; then
+    echo "Failed to validate persisted credential"
+    popd
+    exit 1
+fi
+popd

__test__/verify-submodules-true.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+if [ ! -f "./submodules-true/regular-file.txt" ]; then
+    echo "Expected regular file does not exist"
+    exit 1
+fi
+
+if [ ! -f "./submodules-true/submodule-level-1/submodule-file.txt" ]; then
+    echo "Expected submodule file does not exist"
+    exit 1
+fi
+
+if [ -f "./submodules-true/submodule-level-1/submodule-level-2/nested-submodule-file.txt" ]; then
+    echo "Unexpected nested submodule file exists"
+    exit 1
+fi
+
+echo "Testing persisted credential"
+pushd ./submodules-true/submodule-level-1
+git config --local --name-only --get-regexp http.+extraheader && git fetch
+if [ "$?" != "0" ]; then
+    echo "Failed to validate persisted credential"
+    popd
+    exit 1
+fi
+popd

action.yml

@@ -1,6 +1,6 @@
 name: 'Checkout'
 description: 'Checkout a Git repository at a particular version'
-inputs: 
+inputs:
   repository:
     description: 'Repository name with owner. For example, actions/checkout'
     default: ${{ github.repository }}
@@ -11,13 +11,42 @@ inputs:
       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)
+      Personal access token (PAT) used to fetch the repository. The PAT is configured
+      with the local git config, which enables your scripts to run authenticated git
+      commands. The post-job step removes the PAT.
+
+
+      We recommend using a service account with the least permissions necessary.
+      Also when generating a new PAT, select the least scopes necessary.
+
+
+      [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 }}
+  ssh-key:
+    description: >
+      SSH key used to fetch the repository. The SSH key is configured with the local
+      git config, which enables your scripts to run authenticated git commands.
+      The post-job step removes the SSH key.
+
+
+      We recommend using a service account with the least permissions necessary.
+
+
+      [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)
+  ssh-known-hosts:
+    description: >
+      Known hosts in addition to the user and global host key database. The public
+      SSH keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+      `ssh-keyscan github.com`. The public key for github.com is always implicitly added.
+  ssh-strict:
+    description: >
+      Whether to perform strict host key checking. When true, adds the options `StrictHostKeyChecking=yes`
+      and `CheckHostIP=no` to the SSH command line. Use the input `ssh-known-hosts` to
+      configure additional hosts.
+    default: true
   persist-credentials:
-    description: 'Whether to persist the token in the git config'
+    description: 'Whether to configure the token or SSH key with the local git config'
     default: true
   path:
     description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
@@ -30,6 +59,15 @@ inputs:
   lfs:
     description: 'Whether to download Git-LFS files'
     default: false
+  submodules:
+    description: >
+      Whether to checkout submodules: `true` to checkout submodules or `recursive` to
+      recursively checkout submodules.
+
+
+      When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.com:` are
+      converted to HTTPS.
+    default: false
 runs:
   using: node12
   main: dist/index.js

adrs/0153-checkout-v2.md

@@ -0,0 +1,271 @@
+# 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: >
+      Personal access token (PAT) used to fetch the repository. The PAT is configured
+      with the local git config, which enables your scripts to run authenticated git
+      commands. The post-job step removes the PAT. [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 }}
+  ssh-key:
+    description: >
+      SSH key used to fetch the repository. SSH key is configured with the local
+      git config, which enables your scripts to run authenticated git commands.
+      The post-job step removes the SSH key. [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)
+  ssh-known-hosts:
+    description: >
+      Known hosts in addition to the user and global host key database. The public
+      SSH keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+      `ssh-keyscan github.com`. The public key for github.com is always implicitly added.
+  ssh-strict:
+    description: 'Whether to perform strict host key checking'
+    default: true
+  persist-credentials:
+    description: 'Whether to configure the token or SSH key with the local 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
+  lfs:
+    description: 'Whether to download Git-LFS files'
+    default: false
+  submodules:
+    description: >
+      Whether to checkout submodules: `true` to checkout submodules or `recursive` to
+      recursively checkout submodules.
+    default: 'false'
+```
+
+Note:
+- SSH support is new
+- `persist-credentials` is new
+- `path` behavior is different (refer [below](#path) for details)
+
+### 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.
+
+### Persist credentials
+
+The credentials will be persisted on disk. This will allow users to script authenticated git commands, like `git fetch`.
+
+A post script will remove the credentials (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.
+
+#### PAT
+
+When using the `${{github.token}}` or a PAT, the token will be persisted in the local git config. The config key `http.https://github.com/.extraheader` enables an auth header to be specified on all authenticated commands `AUTHORIZATION: basic <BASE64_U:P>`.
+
+Note:
+- The auth header 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.
+
+#### SSH key
+
+The SSH key will be written to disk under the `$RUNNER_TEMP` directory. The SSH key will
+be removed by the action's post-job hook. Additionally, RUNNER_TEMP is cleared by the
+runner between jobs.
+
+The SSH key must be written with strict file permissions. The SSH client requires the file
+to be read/write for the user, and not accessible by others.
+
+The user host key database (`~/.ssh/known_hosts`) will be copied to a unique file under
+`$RUNNER_TEMP`. And values from the input `ssh-known-hosts` will be added to the file.
+
+The SSH command will be overridden for the local git config:
+
+```sh
+git config core.sshCommand 'ssh -i "$RUNNER_TEMP/path-to-ssh-key" -o StrictHostKeyChecking=yes -o CheckHostIP=no -o "UserKnownHostsFile=$RUNNER_TEMP/path-to-known-hosts"'
+```
+
+When the input `ssh-strict` is set to `false`, the options `CheckHostIP` and `StrictHostKeyChecking` will not be overridden.
+
+Note:
+- When `ssh-strict` is set to `true` (default), the SSH option `CheckHostIP` can safely be disabled.
+  Strict host checking verifies the server's public key. Therefore, IP verification is unnecessary
+  and noisy. For example:
+  > Warning: Permanently added the RSA host key for IP address '140.82.113.4' to the list of known hosts.
+- Since GIT_SSH_COMMAND overrides core.sshCommand, temporarily set the env var when fetching the repo. When creds
+  are persisted, core.sshCommand is leveraged to avoid multiple checkout steps stomping over each other.
+- Modify actions/runner to mount RUNNER_TEMP to enable scripting authenticated git commands from a container action.
+- Refer [here](https://linux.die.net/man/5/ssh_config) for SSH config details.
+
+### 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.
+
+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.
+
+### Submodules
+
+With both PAT and SSH key support, we should be able to provide frictionless support for
+submodules scenarios: recursive, non-recursive, relative submodule paths.
+
+When fetching submodules, follow the `fetch-depth` settings.
+
+Also when fetching submodules, if the `ssh-key` input is not provided then convert SSH URLs to HTTPS: `-c url."https://github.com/".insteadOf "git@github.com:"`
+
+Credentials will be persisted in the submodules local git config too.
+
+### 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)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "checkout",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
@@ -15,14 +15,30 @@
       "integrity": "sha512-nvFkxwiicvpzNiCBF4wFBDfnBvi7xp/as7LE1hBxBxKG2L29+gkIPBiLKMVORL+Hg3JNf07AKRfl0V5djoypjQ=="
     },
     "@actions/github": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/@actions/github/-/github-2.0.0.tgz",
-      "integrity": "sha512-sNpZ5dJyJyfJIO5lNYx8r/Gha4Tlm8R0MLO2cBkGdOnAAEn3t1M/MHVcoBhY/VPfjGVe5RNAUPz+6INrViiUPA==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@actions/github/-/github-2.1.0.tgz",
+      "integrity": "sha512-G4ncMlh4pLLAvNgHUYUtpWQ1zPf/VYqmRH9oshxLabdaOOnp7i1hgSgzr2xne2YUaSND3uqemd3YYTIsm2f/KQ==",
       "requires": {
+        "@actions/http-client": "^1.0.3",
         "@octokit/graphql": "^4.3.1",
         "@octokit/rest": "^16.15.0"
       }
     },
+    "@actions/http-client": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.3.tgz",
+      "integrity": "sha512-wFwh1U4adB/Zsk4cc9kVqaBOHoknhp/pJQk+aWTocbAZWpIl4Zx/At83WFRLXvxB+5HVTWOACM6qjULMZfQSfw==",
+      "requires": {
+        "tunnel": "0.0.6"
+      },
+      "dependencies": {
+        "tunnel": {
+          "version": "0.0.6",
+          "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+          "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
+        }
+      }
+    },
     "@actions/io": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/@actions/io/-/io-1.0.1.tgz",
@@ -597,6 +613,14 @@
         "@types/yargs": "^13.0.0"
       }
     },
+    "@octokit/auth-token": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.4.0.tgz",
+      "integrity": "sha512-eoOVMjILna7FVQf96iWc3+ZtE/ZT6y8ob8ZzcqKY1ibSQCnu4O/B7pJvzMx5cyZ/RjAff6DAdEb0O0Cjcxidkg==",
+      "requires": {
+        "@octokit/types": "^2.0.0"
+      }
+    },
     "@octokit/endpoint": {
       "version": "5.5.1",
       "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-5.5.1.tgz",
@@ -643,10 +667,11 @@
       }
     },
     "@octokit/rest": {
-      "version": "16.35.0",
-      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-16.35.0.tgz",
-      "integrity": "sha512-9ShFqYWo0CLoGYhA1FdtdykJuMzS/9H6vSbbQWDX4pWr4p9v+15MsH/wpd/3fIU+tSxylaNO48+PIHqOkBRx3w==",
+      "version": "16.38.1",
+      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-16.38.1.tgz",
+      "integrity": "sha512-zyNFx+/Bd1EXt7LQjfrc6H4wryBQ/oDuZeZhGMBSFr1eMPFDmpEweFQR3R25zjKwBQpDY7L5GQO6A3XSaOfV1w==",
       "requires": {
+        "@octokit/auth-token": "^2.4.0",
         "@octokit/request": "^5.2.0",
         "@octokit/request-error": "^1.0.2",
         "atob-lite": "^2.0.0",
@@ -662,9 +687,9 @@
       }
     },
     "@octokit/types": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-2.0.2.tgz",
-      "integrity": "sha512-StASIL2lgT3TRjxv17z9pAqbnI7HGu9DrJlg3sEBFfCLaMEqp+O3IQPUF6EZtQ4xkAu2ml6kMBBCtGxjvmtmuQ==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-2.1.1.tgz",
+      "integrity": "sha512-89LOYH+d/vsbDX785NOfLxTW88GjNd0lWRz1DVPVsZgg9Yett5O+3MOvwo7iHgvUwbFz0mf/yPIjBkUbs4kxoQ==",
       "requires": {
         "@types/node": ">= 8"
       }

package.json

@@ -1,17 +1,14 @@
 {
   "name": "checkout",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "checkout action",
   "main": "lib/main.js",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && ncc build && node lib/misc/generate-docs.js",
     "format": "prettier --write **/*.ts",
     "format-check": "prettier --check **/*.ts",
     "lint": "eslint src/**/*.ts",
-    "pack": "ncc build",
-    "gendocs": "node lib/misc/generate-docs.js",
-    "test": "jest",
-    "all": "npm run build && npm run format && npm run lint && npm run pack && npm run gendocs && npm test"
+    "test": "jest"
   },
   "repository": {
     "type": "git",
@@ -31,7 +28,7 @@
   "dependencies": {
     "@actions/core": "^1.1.3",
     "@actions/exec": "^1.0.1",
-    "@actions/github": "^2.0.0",
+    "@actions/github": "^2.0.2",
     "@actions/io": "^1.0.1",
     "@actions/tool-cache": "^1.1.2",
     "uuid": "^3.3.3"

src/git-auth-helper.ts

@@ -0,0 +1,344 @@
+import * as assert from 'assert'
+import * as core from '@actions/core'
+import * as exec from '@actions/exec'
+import * as fs from 'fs'
+import * as io from '@actions/io'
+import * as os from 'os'
+import * as path from 'path'
+import * as regexpHelper from './regexp-helper'
+import * as stateHelper from './state-helper'
+import {default as uuid} from 'uuid/v4'
+import {IGitCommandManager} from './git-command-manager'
+import {IGitSourceSettings} from './git-source-settings'
+
+const IS_WINDOWS = process.platform === 'win32'
+const HOSTNAME = 'github.com'
+const SSH_COMMAND_KEY = 'core.sshCommand'
+
+export interface IGitAuthHelper {
+  configureAuth(): Promise<void>
+  configureGlobalAuth(): Promise<void>
+  configureSubmoduleAuth(): Promise<void>
+  removeAuth(): Promise<void>
+  removeGlobalAuth(): Promise<void>
+}
+
+export function createAuthHelper(
+  git: IGitCommandManager,
+  settings?: IGitSourceSettings
+): IGitAuthHelper {
+  return new GitAuthHelper(git, settings)
+}
+
+class GitAuthHelper {
+  private readonly git: IGitCommandManager
+  private readonly settings: IGitSourceSettings
+  private readonly tokenConfigKey: string = `http.https://${HOSTNAME}/.extraheader`
+  private readonly tokenPlaceholderConfigValue: string
+  private readonly insteadOfKey: string = `url.https://${HOSTNAME}/.insteadOf`
+  private readonly insteadOfValue: string = `git@${HOSTNAME}:`
+  private sshCommand = ''
+  private sshKeyPath = ''
+  private sshKnownHostsPath = ''
+  private temporaryHomePath = ''
+  private tokenConfigValue: string
+
+  constructor(
+    gitCommandManager: IGitCommandManager,
+    gitSourceSettings?: IGitSourceSettings
+  ) {
+    this.git = gitCommandManager
+    this.settings = gitSourceSettings || (({} as unknown) as IGitSourceSettings)
+
+    // Token auth header
+    const basicCredential = Buffer.from(
+      `x-access-token:${this.settings.authToken}`,
+      'utf8'
+    ).toString('base64')
+    core.setSecret(basicCredential)
+    this.tokenPlaceholderConfigValue = `AUTHORIZATION: basic ***`
+    this.tokenConfigValue = `AUTHORIZATION: basic ${basicCredential}`
+  }
+
+  async configureAuth(): Promise<void> {
+    // Remove possible previous values
+    await this.removeAuth()
+
+    // Configure new values
+    await this.configureSsh()
+    await this.configureToken()
+  }
+
+  async configureGlobalAuth(): Promise<void> {
+    // Create a temp home directory
+    const runnerTemp = process.env['RUNNER_TEMP'] || ''
+    assert.ok(runnerTemp, 'RUNNER_TEMP is not defined')
+    const uniqueId = uuid()
+    this.temporaryHomePath = path.join(runnerTemp, uniqueId)
+    await fs.promises.mkdir(this.temporaryHomePath, {recursive: true})
+
+    // Copy the global git config
+    const gitConfigPath = path.join(
+      process.env['HOME'] || os.homedir(),
+      '.gitconfig'
+    )
+    const newGitConfigPath = path.join(this.temporaryHomePath, '.gitconfig')
+    let configExists = false
+    try {
+      await fs.promises.stat(gitConfigPath)
+      configExists = true
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+    }
+    if (configExists) {
+      core.info(`Copying '${gitConfigPath}' to '${newGitConfigPath}'`)
+      await io.cp(gitConfigPath, newGitConfigPath)
+    } else {
+      await fs.promises.writeFile(newGitConfigPath, '')
+    }
+
+    try {
+      // Override HOME
+      core.info(
+        `Temporarily overriding HOME='${this.temporaryHomePath}' before making global git config changes`
+      )
+      this.git.setEnvironmentVariable('HOME', this.temporaryHomePath)
+
+      // Configure the token
+      await this.configureToken(newGitConfigPath, true)
+
+      // Configure HTTPS instead of SSH
+      await this.git.tryConfigUnset(this.insteadOfKey, true)
+      if (!this.settings.sshKey) {
+        await this.git.config(this.insteadOfKey, this.insteadOfValue, true)
+      }
+    } catch (err) {
+      // Unset in case somehow written to the real global config
+      core.info(
+        'Encountered an error when attempting to configure token. Attempting unconfigure.'
+      )
+      await this.git.tryConfigUnset(this.tokenConfigKey, true)
+      throw err
+    }
+  }
+
+  async configureSubmoduleAuth(): Promise<void> {
+    // Remove possible previous HTTPS instead of SSH
+    await this.removeGitConfig(this.insteadOfKey, true)
+
+    if (this.settings.persistCredentials) {
+      // Configure a placeholder value. This approach avoids the credential being captured
+      // by process creation audit events, which are commonly logged. For more information,
+      // refer to https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
+      const output = await this.git.submoduleForeach(
+        `git config --local '${this.tokenConfigKey}' '${this.tokenPlaceholderConfigValue}' && git config --local --show-origin --name-only --get-regexp remote.origin.url`,
+        this.settings.nestedSubmodules
+      )
+
+      // Replace the placeholder
+      const configPaths: string[] =
+        output.match(/(?<=(^|\n)file:)[^\t]+(?=\tremote\.origin\.url)/g) || []
+      for (const configPath of configPaths) {
+        core.debug(`Replacing token placeholder in '${configPath}'`)
+        this.replaceTokenPlaceholder(configPath)
+      }
+
+      if (this.settings.sshKey) {
+        // Configure core.sshCommand
+        await this.git.submoduleForeach(
+          `git config --local '${SSH_COMMAND_KEY}' '${this.sshCommand}'`,
+          this.settings.nestedSubmodules
+        )
+      } else {
+        // Configure HTTPS instead of SSH
+        await this.git.submoduleForeach(
+          `git config --local '${this.insteadOfKey}' '${this.insteadOfValue}'`,
+          this.settings.nestedSubmodules
+        )
+      }
+    }
+  }
+
+  async removeAuth(): Promise<void> {
+    await this.removeSsh()
+    await this.removeToken()
+  }
+
+  async removeGlobalAuth(): Promise<void> {
+    core.info(`Unsetting HOME override`)
+    this.git.removeEnvironmentVariable('HOME')
+    await io.rmRF(this.temporaryHomePath)
+  }
+
+  private async configureSsh(): Promise<void> {
+    if (!this.settings.sshKey) {
+      return
+    }
+
+    // Write key
+    const runnerTemp = process.env['RUNNER_TEMP'] || ''
+    assert.ok(runnerTemp, 'RUNNER_TEMP is not defined')
+    const uniqueId = uuid()
+    this.sshKeyPath = path.join(runnerTemp, uniqueId)
+    stateHelper.setSshKeyPath(this.sshKeyPath)
+    await fs.promises.mkdir(runnerTemp, {recursive: true})
+    await fs.promises.writeFile(
+      this.sshKeyPath,
+      this.settings.sshKey.trim() + '\n',
+      {mode: 0o600}
+    )
+
+    // Remove inherited permissions on Windows
+    if (IS_WINDOWS) {
+      const icacls = await io.which('icacls.exe')
+      await exec.exec(
+        `"${icacls}" "${this.sshKeyPath}" /grant:r "${process.env['USERDOMAIN']}\\${process.env['USERNAME']}:F"`
+      )
+      await exec.exec(`"${icacls}" "${this.sshKeyPath}" /inheritance:r`)
+    }
+
+    // Write known hosts
+    const userKnownHostsPath = path.join(os.homedir(), '.ssh', 'known_hosts')
+    let userKnownHosts = ''
+    try {
+      userKnownHosts = (
+        await fs.promises.readFile(userKnownHostsPath)
+      ).toString()
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+    }
+    let knownHosts = ''
+    if (userKnownHosts) {
+      knownHosts += `# Begin from ${userKnownHostsPath}\n${userKnownHosts}\n# End from ${userKnownHostsPath}\n`
+    }
+    if (this.settings.sshKnownHosts) {
+      knownHosts += `# Begin from input known hosts\n${this.settings.sshKnownHosts}\n# end from input known hosts\n`
+    }
+    knownHosts += `# Begin implicitly added github.com\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==\n# End implicitly added github.com\n`
+    this.sshKnownHostsPath = path.join(runnerTemp, `${uniqueId}_known_hosts`)
+    stateHelper.setSshKnownHostsPath(this.sshKnownHostsPath)
+    await fs.promises.writeFile(this.sshKnownHostsPath, knownHosts)
+
+    // Configure GIT_SSH_COMMAND
+    const sshPath = await io.which('ssh', true)
+    this.sshCommand = `"${sshPath}" -i "$RUNNER_TEMP/${path.basename(
+      this.sshKeyPath
+    )}"`
+    if (this.settings.sshStrict) {
+      this.sshCommand += ' -o StrictHostKeyChecking=yes -o CheckHostIP=no'
+    }
+    this.sshCommand += ` -o "UserKnownHostsFile=$RUNNER_TEMP/${path.basename(
+      this.sshKnownHostsPath
+    )}"`
+    core.info(`Temporarily overriding GIT_SSH_COMMAND=${this.sshCommand}`)
+    this.git.setEnvironmentVariable('GIT_SSH_COMMAND', this.sshCommand)
+
+    // Configure core.sshCommand
+    if (this.settings.persistCredentials) {
+      await this.git.config(SSH_COMMAND_KEY, this.sshCommand)
+    }
+  }
+
+  private async configureToken(
+    configPath?: string,
+    globalConfig?: boolean
+  ): Promise<void> {
+    // Validate args
+    assert.ok(
+      (configPath && globalConfig) || (!configPath && !globalConfig),
+      'Unexpected configureToken parameter combinations'
+    )
+
+    // Default config path
+    if (!configPath && !globalConfig) {
+      configPath = path.join(this.git.getWorkingDirectory(), '.git', 'config')
+    }
+
+    // Configure a placeholder value. This approach avoids the credential being captured
+    // by process creation audit events, which are commonly logged. For more information,
+    // refer to https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
+    await this.git.config(
+      this.tokenConfigKey,
+      this.tokenPlaceholderConfigValue,
+      globalConfig
+    )
+
+    // Replace the placeholder
+    await this.replaceTokenPlaceholder(configPath || '')
+  }
+
+  private async replaceTokenPlaceholder(configPath: string): Promise<void> {
+    assert.ok(configPath, 'configPath is not defined')
+    let content = (await fs.promises.readFile(configPath)).toString()
+    const placeholderIndex = content.indexOf(this.tokenPlaceholderConfigValue)
+    if (
+      placeholderIndex < 0 ||
+      placeholderIndex != content.lastIndexOf(this.tokenPlaceholderConfigValue)
+    ) {
+      throw new Error(`Unable to replace auth placeholder in ${configPath}`)
+    }
+    assert.ok(this.tokenConfigValue, 'tokenConfigValue is not defined')
+    content = content.replace(
+      this.tokenPlaceholderConfigValue,
+      this.tokenConfigValue
+    )
+    await fs.promises.writeFile(configPath, content)
+  }
+
+  private async removeSsh(): Promise<void> {
+    // SSH key
+    const keyPath = this.sshKeyPath || stateHelper.SshKeyPath
+    if (keyPath) {
+      try {
+        await io.rmRF(keyPath)
+      } catch (err) {
+        core.debug(err.message)
+        core.warning(`Failed to remove SSH key '${keyPath}'`)
+      }
+    }
+
+    // SSH known hosts
+    const knownHostsPath =
+      this.sshKnownHostsPath || stateHelper.SshKnownHostsPath
+    if (knownHostsPath) {
+      try {
+        await io.rmRF(knownHostsPath)
+      } catch {
+        // Intentionally empty
+      }
+    }
+
+    // SSH command
+    await this.removeGitConfig(SSH_COMMAND_KEY)
+  }
+
+  private async removeToken(): Promise<void> {
+    // HTTP extra header
+    await this.removeGitConfig(this.tokenConfigKey)
+  }
+
+  private async removeGitConfig(
+    configKey: string,
+    submoduleOnly: boolean = false
+  ): Promise<void> {
+    if (!submoduleOnly) {
+      if (
+        (await this.git.configExists(configKey)) &&
+        !(await this.git.tryConfigUnset(configKey))
+      ) {
+        // Load the config contents
+        core.warning(`Failed to remove '${configKey}' from the git config`)
+      }
+    }
+
+    const pattern = regexpHelper.escape(configKey)
+    await this.git.submoduleForeach(
+      `git config --local --name-only --get-regexp '${pattern}' && git config --local --unset-all '${configKey}' || :`,
+      true
+    )
+  }
+}

src/git-command-manager.ts

@@ -3,6 +3,7 @@ import * as exec from '@actions/exec'
 import * as fshelper from './fs-helper'
 import * as io from '@actions/io'
 import * as path from 'path'
+import * as regexpHelper from './regexp-helper'
 import * as retryHelper from './retry-helper'
 import {GitVersion} from './git-version'
 
@@ -16,8 +17,12 @@ export interface IGitCommandManager {
   branchList(remote: boolean): Promise<string[]>
   checkout(ref: string, startPoint: string): Promise<void>
   checkoutDetach(): Promise<void>
-  config(configKey: string, configValue: string): Promise<void>
-  configExists(configKey: string): Promise<boolean>
+  config(
+    configKey: string,
+    configValue: string,
+    globalConfig?: boolean
+  ): Promise<void>
+  configExists(configKey: string, globalConfig?: boolean): Promise<boolean>
   fetch(fetchDepth: number, refSpec: string[]): Promise<void>
   getWorkingDirectory(): string
   init(): Promise<void>
@@ -26,15 +31,20 @@ export interface IGitCommandManager {
   lfsInstall(): Promise<void>
   log1(): Promise<void>
   remoteAdd(remoteName: string, remoteUrl: string): Promise<void>
+  removeEnvironmentVariable(name: string): void
+  setEnvironmentVariable(name: string, value: string): void
+  submoduleForeach(command: string, recursive: boolean): Promise<string>
+  submoduleSync(recursive: boolean): Promise<void>
+  submoduleUpdate(fetchDepth: number, recursive: boolean): Promise<void>
   tagExists(pattern: string): Promise<boolean>
   tryClean(): Promise<boolean>
-  tryConfigUnset(configKey: string): Promise<boolean>
+  tryConfigUnset(configKey: string, globalConfig?: boolean): Promise<boolean>
   tryDisableAutomaticGarbageCollection(): Promise<boolean>
   tryGetFetchUrl(): Promise<string>
   tryReset(): Promise<boolean>
 }
 
-export async function CreateCommandManager(
+export async function createCommandManager(
   workingDirectory: string,
   lfs: boolean
 ): Promise<IGitCommandManager> {
@@ -123,16 +133,32 @@ class GitCommandManager {
     await this.execGit(args)
   }
 
-  async config(configKey: string, configValue: string): Promise<void> {
-    await this.execGit(['config', '--local', configKey, configValue])
+  async config(
+    configKey: string,
+    configValue: string,
+    globalConfig?: boolean
+  ): Promise<void> {
+    await this.execGit([
+      'config',
+      globalConfig ? '--global' : '--local',
+      configKey,
+      configValue
+    ])
   }
 
-  async configExists(configKey: string): Promise<boolean> {
-    const pattern = configKey.replace(/[^a-zA-Z0-9_]/g, x => {
-      return `\\${x}`
-    })
+  async configExists(
+    configKey: string,
+    globalConfig?: boolean
+  ): Promise<boolean> {
+    const pattern = regexpHelper.escape(configKey)
     const output = await this.execGit(
-      ['config', '--local', '--name-only', '--get-regexp', pattern],
+      [
+        'config',
+        globalConfig ? '--global' : '--local',
+        '--name-only',
+        '--get-regexp',
+        pattern
+      ],
       true
     )
     return output.exitCode === 0
@@ -207,6 +233,48 @@ class GitCommandManager {
     await this.execGit(['remote', 'add', remoteName, remoteUrl])
   }
 
+  removeEnvironmentVariable(name: string): void {
+    delete this.gitEnv[name]
+  }
+
+  setEnvironmentVariable(name: string, value: string): void {
+    this.gitEnv[name] = value
+  }
+
+  async submoduleForeach(command: string, recursive: boolean): Promise<string> {
+    const args = ['submodule', 'foreach']
+    if (recursive) {
+      args.push('--recursive')
+    }
+    args.push(command)
+
+    const output = await this.execGit(args)
+    return output.stdout
+  }
+
+  async submoduleSync(recursive: boolean): Promise<void> {
+    const args = ['submodule', 'sync']
+    if (recursive) {
+      args.push('--recursive')
+    }
+
+    await this.execGit(args)
+  }
+
+  async submoduleUpdate(fetchDepth: number, recursive: boolean): Promise<void> {
+    const args = ['-c', 'protocol.version=2']
+    args.push('submodule', 'update', '--init', '--force')
+    if (fetchDepth > 0) {
+      args.push(`--depth=${fetchDepth}`)
+    }
+
+    if (recursive) {
+      args.push('--recursive')
+    }
+
+    await this.execGit(args)
+  }
+
   async tagExists(pattern: string): Promise<boolean> {
     const output = await this.execGit(['tag', '--list', pattern])
     return !!output.stdout.trim()
@@ -217,9 +285,17 @@ class GitCommandManager {
     return output.exitCode === 0
   }
 
-  async tryConfigUnset(configKey: string): Promise<boolean> {
+  async tryConfigUnset(
+    configKey: string,
+    globalConfig?: boolean
+  ): Promise<boolean> {
     const output = await this.execGit(
-      ['config', '--local', '--unset-all', configKey],
+      [
+        'config',
+        globalConfig ? '--global' : '--local',
+        '--unset-all',
+        configKey
+      ],
       true
     )
     return output.exitCode === 0

src/git-directory-helper.ts

@@ -0,0 +1,91 @@
+import * as core from '@actions/core'
+import * as fs from 'fs'
+import * as fsHelper from './fs-helper'
+import * as io from '@actions/io'
+import * as path from 'path'
+import {IGitCommandManager} from './git-command-manager'
+
+export async function prepareExistingDirectory(
+  git: IGitCommandManager | undefined,
+  repositoryPath: string,
+  repositoryUrl: string,
+  clean: boolean
+): Promise<void> {
+  let remove = false
+
+  // Check whether using git or REST API
+  if (!git) {
+    remove = true
+  }
+  // Fetch URL does not match
+  else if (
+    !fsHelper.directoryExistsSync(path.join(repositoryPath, '.git')) ||
+    repositoryUrl !== (await git.tryGetFetchUrl())
+  ) {
+    remove = true
+  } else {
+    // Delete any index.lock and shallow.lock left by a previously canceled run or crashed git process
+    const lockPaths = [
+      path.join(repositoryPath, '.git', 'index.lock'),
+      path.join(repositoryPath, '.git', 'shallow.lock')
+    ]
+    for (const lockPath of lockPaths) {
+      try {
+        await io.rmRF(lockPath)
+      } catch (error) {
+        core.debug(`Unable to delete '${lockPath}'. ${error.message}`)
+      }
+    }
+
+    try {
+      // Checkout detached HEAD
+      if (!(await git.isDetached())) {
+        await git.checkoutDetach()
+      }
+
+      // Remove all refs/heads/*
+      let branches = await git.branchList(false)
+      for (const branch of branches) {
+        await git.branchDelete(false, branch)
+      }
+
+      // Remove all refs/remotes/origin/* to avoid conflicts
+      branches = await git.branchList(true)
+      for (const branch of branches) {
+        await git.branchDelete(true, branch)
+      }
+
+      // Clean
+      if (clean) {
+        if (!(await git.tryClean())) {
+          core.debug(
+            `The clean command failed. This might be caused by: 1) path too long, 2) permission issue, or 3) file in use. For futher investigation, manually run 'git clean -ffdx' on the directory '${repositoryPath}'.`
+          )
+          remove = true
+        } else if (!(await git.tryReset())) {
+          remove = true
+        }
+
+        if (remove) {
+          core.warning(
+            `Unable to clean or reset the repository. The repository will be recreated instead.`
+          )
+        }
+      }
+    } catch (error) {
+      core.warning(
+        `Unable to prepare the existing repository. The repository will be recreated instead.`
+      )
+      remove = true
+    }
+  }
+
+  if (remove) {
+    // Delete the contents of the directory. Don't delete the directory itself
+    // since it might be the current working directory.
+    core.info(`Deleting the contents of '${repositoryPath}'`)
+    for (const file of await fs.promises.readdir(repositoryPath)) {
+      await io.rmRF(path.join(repositoryPath, file))
+    }
+  }
+}

src/git-source-provider.ts

@@ -1,37 +1,30 @@
 import * as core from '@actions/core'
-import * as fs from 'fs'
 import * as fsHelper from './fs-helper'
+import * as gitAuthHelper from './git-auth-helper'
 import * as gitCommandManager from './git-command-manager'
+import * as gitDirectoryHelper from './git-directory-helper'
 import * as githubApiHelper from './github-api-helper'
 import * as io from '@actions/io'
 import * as path from 'path'
 import * as refHelper from './ref-helper'
 import * as stateHelper from './state-helper'
 import {IGitCommandManager} from './git-command-manager'
+import {IGitSourceSettings} from './git-source-settings'
 
-const authConfigKey = `http.https://github.com/.extraheader`
+const hostname = 'github.com'
 
-export interface ISourceSettings {
-  repositoryPath: string
-  repositoryOwner: string
-  repositoryName: string
-  ref: string
-  commit: string
-  clean: boolean
-  fetchDepth: number
-  lfs: boolean
-  authToken: string
-  persistCredentials: boolean
-}
-
-export async function getSource(settings: ISourceSettings): Promise<void> {
+export async function getSource(settings: IGitSourceSettings): Promise<void> {
   // Repository URL
   core.info(
     `Syncing repository: ${settings.repositoryOwner}/${settings.repositoryName}`
   )
-  const repositoryUrl = `https://github.com/${encodeURIComponent(
-    settings.repositoryOwner
-  )}/${encodeURIComponent(settings.repositoryName)}`
+  const repositoryUrl = settings.sshKey
+    ? `git@${hostname}:${encodeURIComponent(
+        settings.repositoryOwner
+      )}/${encodeURIComponent(settings.repositoryName)}.git`
+    : `https://${hostname}/${encodeURIComponent(
+        settings.repositoryOwner
+      )}/${encodeURIComponent(settings.repositoryName)}`
 
   // Remove conflicting file path
   if (fsHelper.fileExistsSync(settings.repositoryPath)) {
@@ -50,7 +43,7 @@ export async function getSource(settings: ISourceSettings): Promise<void> {
 
   // Prepare existing directory, otherwise recreate
   if (isExisting) {
-    await prepareExistingDirectory(
+    await gitDirectoryHelper.prepareExistingDirectory(
       git,
       settings.repositoryPath,
       repositoryUrl,
@@ -64,6 +57,16 @@ export async function getSource(settings: ISourceSettings): Promise<void> {
     core.info(
       `To create a local Git repository instead, add Git ${gitCommandManager.MinimumGitVersion} or higher to the PATH`
     )
+    if (settings.submodules) {
+      throw new Error(
+        `Input 'submodules' not supported when falling back to download using the GitHub REST API. To create a local Git repository instead, add Git ${gitCommandManager.MinimumGitVersion} or higher to the PATH.`
+      )
+    } else if (settings.sshKey) {
+      throw new Error(
+        `Input 'ssh-key' not supported when falling back to download using the GitHub REST API. To create a local Git repository instead, add Git ${gitCommandManager.MinimumGitVersion} or higher to the PATH.`
+      )
+    }
+
     await githubApiHelper.downloadRepository(
       settings.authToken,
       settings.repositoryOwner,
@@ -72,90 +75,122 @@ export async function getSource(settings: ISourceSettings): Promise<void> {
       settings.commit,
       settings.repositoryPath
     )
-  } else {
-    // Save state for POST action
-    stateHelper.setRepositoryPath(settings.repositoryPath)
+    return
+  }
 
-    // Initialize the repository
-    if (
-      !fsHelper.directoryExistsSync(path.join(settings.repositoryPath, '.git'))
-    ) {
-      await git.init()
-      await git.remoteAdd('origin', repositoryUrl)
+  // Save state for POST action
+  stateHelper.setRepositoryPath(settings.repositoryPath)
+
+  // Initialize the repository
+  if (
+    !fsHelper.directoryExistsSync(path.join(settings.repositoryPath, '.git'))
+  ) {
+    await git.init()
+    await git.remoteAdd('origin', repositoryUrl)
+  }
+
+  // Disable automatic garbage collection
+  if (!(await git.tryDisableAutomaticGarbageCollection())) {
+    core.warning(
+      `Unable to turn off git automatic garbage collection. The git fetch operation may trigger garbage collection and cause a delay.`
+    )
+  }
+
+  const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+  try {
+    // Configure auth
+    await authHelper.configureAuth()
+
+    // LFS install
+    if (settings.lfs) {
+      await git.lfsInstall()
     }
 
-    // Disable automatic garbage collection
-    if (!(await git.tryDisableAutomaticGarbageCollection())) {
-      core.warning(
-        `Unable to turn off git automatic garbage collection. The git fetch operation may trigger garbage collection and cause a delay.`
-      )
+    // Fetch
+    const refSpec = refHelper.getRefSpec(settings.ref, settings.commit)
+    await git.fetch(settings.fetchDepth, refSpec)
+
+    // Checkout info
+    const checkoutInfo = await refHelper.getCheckoutInfo(
+      git,
+      settings.ref,
+      settings.commit
+    )
+
+    // LFS fetch
+    // Explicit lfs-fetch to avoid slow checkout (fetches one lfs object at a time).
+    // Explicit lfs fetch will fetch lfs objects in parallel.
+    if (settings.lfs) {
+      await git.lfsFetch(checkoutInfo.startPoint || checkoutInfo.ref)
     }
 
-    // Remove possible previous extraheader
-    await removeGitConfig(git, authConfigKey)
+    // Checkout
+    await git.checkout(checkoutInfo.ref, checkoutInfo.startPoint)
 
-    try {
-      // Config auth token
-      await configureAuthToken(git, settings.authToken)
+    // Submodules
+    if (settings.submodules) {
+      try {
+        // Temporarily override global config
+        await authHelper.configureGlobalAuth()
 
-      // LFS install
-      if (settings.lfs) {
-        await git.lfsInstall()
+        // Checkout submodules
+        await git.submoduleSync(settings.nestedSubmodules)
+        await git.submoduleUpdate(
+          settings.fetchDepth,
+          settings.nestedSubmodules
+        )
+        await git.submoduleForeach(
+          'git config --local gc.auto 0',
+          settings.nestedSubmodules
+        )
+
+        // Persist credentials
+        if (settings.persistCredentials) {
+          await authHelper.configureSubmoduleAuth()
+        }
+      } finally {
+        // Remove temporary global config override
+        await authHelper.removeGlobalAuth()
       }
+    }
 
-      // Fetch
-      const refSpec = refHelper.getRefSpec(settings.ref, settings.commit)
-      await git.fetch(settings.fetchDepth, refSpec)
-
-      // Checkout info
-      const checkoutInfo = await refHelper.getCheckoutInfo(
-        git,
-        settings.ref,
-        settings.commit
-      )
-
-      // LFS fetch
-      // Explicit lfs-fetch to avoid slow checkout (fetches one lfs object at a time).
-      // Explicit lfs fetch will fetch lfs objects in parallel.
-      if (settings.lfs) {
-        await git.lfsFetch(checkoutInfo.startPoint || checkoutInfo.ref)
-      }
-
-      // Checkout
-      await git.checkout(checkoutInfo.ref, checkoutInfo.startPoint)
-
-      // Dump some info about the checked out commit
-      await git.log1()
-    } finally {
-      if (!settings.persistCredentials) {
-        await removeGitConfig(git, authConfigKey)
-      }
+    // Dump some info about the checked out commit
+    await git.log1()
+  } finally {
+    // Remove auth
+    if (!settings.persistCredentials) {
+      await authHelper.removeAuth()
     }
   }
 }
 
 export async function cleanup(repositoryPath: string): Promise<void> {
   // Repo exists?
-  if (!fsHelper.fileExistsSync(path.join(repositoryPath, '.git', 'config'))) {
+  if (
+    !repositoryPath ||
+    !fsHelper.fileExistsSync(path.join(repositoryPath, '.git', 'config'))
+  ) {
     return
   }
-  fsHelper.directoryExistsSync(repositoryPath, true)
 
-  // Remove the config key
-  const git = await gitCommandManager.CreateCommandManager(
-    repositoryPath,
-    false
-  )
-  await removeGitConfig(git, authConfigKey)
+  let git: IGitCommandManager
+  try {
+    git = await gitCommandManager.createCommandManager(repositoryPath, false)
+  } catch {
+    return
+  }
+
+  // Remove auth
+  const authHelper = gitAuthHelper.createAuthHelper(git)
+  await authHelper.removeAuth()
 }
 
 async function getGitCommandManager(
-  settings: ISourceSettings
-): Promise<IGitCommandManager> {
+  settings: IGitSourceSettings
+): Promise<IGitCommandManager | undefined> {
   core.info(`Working directory is '${settings.repositoryPath}'`)
-  let git = (null as unknown) as IGitCommandManager
   try {
-    return await gitCommandManager.CreateCommandManager(
+    return await gitCommandManager.createCommandManager(
       settings.repositoryPath,
       settings.lfs
     )
@@ -166,138 +201,6 @@ async function getGitCommandManager(
     }
 
     // Otherwise fallback to REST API
-    return (null as unknown) as IGitCommandManager
-  }
-}
-
-async function prepareExistingDirectory(
-  git: IGitCommandManager,
-  repositoryPath: string,
-  repositoryUrl: string,
-  clean: boolean
-): Promise<void> {
-  let remove = false
-
-  // Check whether using git or REST API
-  if (!git) {
-    remove = true
-  }
-  // Fetch URL does not match
-  else if (
-    !fsHelper.directoryExistsSync(path.join(repositoryPath, '.git')) ||
-    repositoryUrl !== (await git.tryGetFetchUrl())
-  ) {
-    remove = true
-  } else {
-    // Delete any index.lock and shallow.lock left by a previously canceled run or crashed git process
-    const lockPaths = [
-      path.join(repositoryPath, '.git', 'index.lock'),
-      path.join(repositoryPath, '.git', 'shallow.lock')
-    ]
-    for (const lockPath of lockPaths) {
-      try {
-        await io.rmRF(lockPath)
-      } catch (error) {
-        core.debug(`Unable to delete '${lockPath}'. ${error.message}`)
-      }
-    }
-
-    try {
-      // Checkout detached HEAD
-      if (!(await git.isDetached())) {
-        await git.checkoutDetach()
-      }
-
-      // Remove all refs/heads/*
-      let branches = await git.branchList(false)
-      for (const branch of branches) {
-        await git.branchDelete(false, branch)
-      }
-
-      // Remove all refs/remotes/origin/* to avoid conflicts
-      branches = await git.branchList(true)
-      for (const branch of branches) {
-        await git.branchDelete(true, branch)
-      }
-
-      // Clean
-      if (clean) {
-        if (!(await git.tryClean())) {
-          core.debug(
-            `The clean command failed. This might be caused by: 1) path too long, 2) permission issue, or 3) file in use. For futher investigation, manually run 'git clean -ffdx' on the directory '${repositoryPath}'.`
-          )
-          remove = true
-        } else if (!(await git.tryReset())) {
-          remove = true
-        }
-
-        if (remove) {
-          core.warning(
-            `Unable to clean or reset the repository. The repository will be recreated instead.`
-          )
-        }
-      }
-    } catch (error) {
-      core.warning(
-        `Unable to prepare the existing repository. The repository will be recreated instead.`
-      )
-      remove = true
-    }
-  }
-
-  if (remove) {
-    // Delete the contents of the directory. Don't delete the directory itself
-    // since it might be the current working directory.
-    core.info(`Deleting the contents of '${repositoryPath}'`)
-    for (const file of await fs.promises.readdir(repositoryPath)) {
-      await io.rmRF(path.join(repositoryPath, file))
-    }
-  }
-}
-
-async function configureAuthToken(
-  git: IGitCommandManager,
-  authToken: string
-): Promise<void> {
-  // Configure a placeholder value. This approach avoids the credential being captured
-  // by process creation audit events, which are commonly logged. For more information,
-  // refer to https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
-  const placeholder = `AUTHORIZATION: basic ***`
-  await git.config(authConfigKey, placeholder)
-
-  // Determine the basic credential value
-  const basicCredential = Buffer.from(
-    `x-access-token:${authToken}`,
-    'utf8'
-  ).toString('base64')
-  core.setSecret(basicCredential)
-
-  // Replace the value in the config file
-  const configPath = path.join(git.getWorkingDirectory(), '.git', 'config')
-  let content = (await fs.promises.readFile(configPath)).toString()
-  const placeholderIndex = content.indexOf(placeholder)
-  if (
-    placeholderIndex < 0 ||
-    placeholderIndex != content.lastIndexOf(placeholder)
-  ) {
-    throw new Error('Unable to replace auth placeholder in .git/config')
-  }
-  content = content.replace(
-    placeholder,
-    `AUTHORIZATION: basic ${basicCredential}`
-  )
-  await fs.promises.writeFile(configPath, content)
-}
-
-async function removeGitConfig(
-  git: IGitCommandManager,
-  configKey: string
-): Promise<void> {
-  if (
-    (await git.configExists(configKey)) &&
-    !(await git.tryConfigUnset(configKey))
-  ) {
-    // Load the config contents
-    core.warning(`Failed to remove '${configKey}' from the git config`)
+    return undefined
   }
 }

src/git-source-settings.ts

@@ -0,0 +1,17 @@
+export interface IGitSourceSettings {
+  repositoryPath: string
+  repositoryOwner: string
+  repositoryName: string
+  ref: string
+  commit: string
+  clean: boolean
+  fetchDepth: number
+  lfs: boolean
+  submodules: boolean
+  nestedSubmodules: boolean
+  authToken: string
+  sshKey: string
+  sshKnownHosts: string
+  sshStrict: boolean
+  persistCredentials: boolean
+}

src/input-helper.ts

@@ -2,10 +2,10 @@ import * as core from '@actions/core'
 import * as fsHelper from './fs-helper'
 import * as github from '@actions/github'
 import * as path from 'path'
-import {ISourceSettings} from './git-source-provider'
+import {IGitSourceSettings} from './git-source-settings'
 
-export function getInputs(): ISourceSettings {
-  const result = ({} as unknown) as ISourceSettings
+export function getInputs(): IGitSourceSettings {
+  const result = ({} as unknown) as IGitSourceSettings
 
   // GitHub workspace
   let githubWorkspacePath = process.env['GITHUB_WORKSPACE']
@@ -61,6 +61,12 @@ export function getInputs(): ISourceSettings {
     if (isWorkflowRepository) {
       result.ref = github.context.ref
       result.commit = github.context.sha
+
+      // Some events have an unqualifed ref. For example when a PR is merged (pull_request closed event),
+      // the ref is unqualifed like "master" instead of "refs/heads/master".
+      if (result.commit && result.ref && !result.ref.startsWith('refs/')) {
+        result.ref = `refs/heads/${result.ref}`
+      }
     }
 
     if (!result.ref && !result.commit) {
@@ -79,13 +85,6 @@ export function getInputs(): ISourceSettings {
   result.clean = (core.getInput('clean') || 'true').toUpperCase() === 'TRUE'
   core.debug(`clean = ${result.clean}`)
 
-  // Submodules
-  if (core.getInput('submodules')) {
-    throw new Error(
-      "The input 'submodules' is not supported in actions/checkout@v2"
-    )
-  }
-
   // Fetch depth
   result.fetchDepth = Math.floor(Number(core.getInput('fetch-depth') || '1'))
   if (isNaN(result.fetchDepth) || result.fetchDepth < 0) {
@@ -97,9 +96,28 @@ export function getInputs(): ISourceSettings {
   result.lfs = (core.getInput('lfs') || 'false').toUpperCase() === 'TRUE'
   core.debug(`lfs = ${result.lfs}`)
 
+  // Submodules
+  result.submodules = false
+  result.nestedSubmodules = false
+  const submodulesString = (core.getInput('submodules') || '').toUpperCase()
+  if (submodulesString == 'RECURSIVE') {
+    result.submodules = true
+    result.nestedSubmodules = true
+  } else if (submodulesString == 'TRUE') {
+    result.submodules = true
+  }
+  core.debug(`submodules = ${result.submodules}`)
+  core.debug(`recursive submodules = ${result.nestedSubmodules}`)
+
   // Auth token
   result.authToken = core.getInput('token')
 
+  // SSH
+  result.sshKey = core.getInput('ssh-key')
+  result.sshKnownHosts = core.getInput('ssh-known-hosts')
+  result.sshStrict =
+    (core.getInput('ssh-strict') || 'true').toUpperCase() === 'TRUE'
+
   // Persist credentials
   result.persistCredentials =
     (core.getInput('persist-credentials') || 'false').toUpperCase() === 'TRUE'

src/misc/generate-docs.ts

@@ -59,13 +59,17 @@ function updateUsage(
 
     // Constrain the width of the description
     const width = 80
-    let description = input.description as string
+    let description = (input.description as string)
+      .trimRight()
+      .replace(/\r\n/g, '\n') // Convert CR to LF
+      .replace(/ +/g, ' ') //    Squash consecutive spaces
+      .replace(/ \n/g, '\n') //  Squash space followed by newline
     while (description) {
       // Longer than width? Find a space to break apart
       let segment: string = description
       if (description.length > width) {
         segment = description.substr(0, width + 1)
-        while (!segment.endsWith(' ') && segment) {
+        while (!segment.endsWith(' ') && !segment.endsWith('\n') && segment) {
           segment = segment.substr(0, segment.length - 1)
         }
 
@@ -77,15 +81,30 @@ function updateUsage(
         segment = description
       }
 
-      description = description.substr(segment.length) // Remaining
-      segment = segment.trimRight() // Trim the trailing space
-      newReadme.push(`    # ${segment}`)
+      // Check for newline
+      const newlineIndex = segment.indexOf('\n')
+      if (newlineIndex >= 0) {
+        segment = segment.substr(0, newlineIndex + 1)
+      }
+
+      // Append segment
+      newReadme.push(`    # ${segment}`.trimRight())
+
+      // Remaining
+      description = description.substr(segment.length)
     }
 
-    // Input and default
     if (input.default !== undefined) {
+      // Append blank line if description had paragraphs
+      if ((input.description as string).trimRight().match(/\n[ ]*\r?\n/)) {
+        newReadme.push(`    #`)
+      }
+
+      // Default
       newReadme.push(`    # Default: ${input.default}`)
     }
+
+    // Input name
     newReadme.push(`    ${key}: ''`)
 
     firstInput = false

src/regexp-helper.ts

@@ -0,0 +1,5 @@
+export function escape(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_]/g, x => {
+    return `\\${x}`
+  })
+}

src/state-helper.ts

@@ -1,4 +1,3 @@
-import * as core from '@actions/core'
 import * as coreCommand from '@actions/core/lib/command'
 
 /**
@@ -12,6 +11,17 @@ export const IsPost = !!process.env['STATE_isPost']
 export const RepositoryPath =
   (process.env['STATE_repositoryPath'] as string) || ''
 
+/**
+ * The SSH key path for the POST action. The value is empty during the MAIN action.
+ */
+export const SshKeyPath = (process.env['STATE_sshKeyPath'] as string) || ''
+
+/**
+ * The SSH known hosts path for the POST action. The value is empty during the MAIN action.
+ */
+export const SshKnownHostsPath =
+  (process.env['STATE_sshKnownHostsPath'] as string) || ''
+
 /**
  * Save the repository path so the POST action can retrieve the value.
  */
@@ -23,6 +33,24 @@ export function setRepositoryPath(repositoryPath: string) {
   )
 }
 
+/**
+ * Save the SSH key path so the POST action can retrieve the value.
+ */
+export function setSshKeyPath(sshKeyPath: string) {
+  coreCommand.issueCommand('save-state', {name: 'sshKeyPath'}, sshKeyPath)
+}
+
+/**
+ * Save the SSH known hosts path so the POST action can retrieve the value.
+ */
+export function setSshKnownHostsPath(sshKnownHostsPath: string) {
+  coreCommand.issueCommand(
+    'save-state',
+    {name: 'sshKnownHostsPath'},
+    sshKnownHostsPath
+  )
+}
+
 // Publish a variable so that when the POST action runs, it can determine it should run the cleanup logic.
 // This is necessary since we don't have a separate entry point.
 if (!IsPost) {