Merge 7618b1f401 into 85e6279cec

* Update README.md

* Update README.md

Co-authored-by: Josh Gross <joshmgross@github.com>

---------

Co-authored-by: Josh Gross <joshmgross@github.com>

.github/workflows/test.yml

@@ -154,6 +154,17 @@ jobs:
           submodules: true
       - name: Verify submodules true
         run: __test__/verify-submodules-true.sh
+  
+      # Submodules limited
+      - name: Checkout submodules limited
+        uses: ./
+        with:
+          ref: test-data/v2/submodule-ssh-url
+          path: submodules-true
+          submodules: true
+          submodule-directories: submodule-level-1
+      - name: Verify submodules true
+        run: __test__/verify-submodules-true.sh
 
       # Submodules recursive
       - name: Checkout submodules recursive

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v4.2.2
+* `url-helper.ts` now leverages well-known environment variables by @jww3 in https://github.com/actions/checkout/pull/1941
+* Expand unit test coverage for `isGhes` by @jww3 in https://github.com/actions/checkout/pull/1946
+
 ## v4.2.1
 * Check out other refs/* by commit if provided, fall back to ref by @orhantoy in https://github.com/actions/checkout/pull/1924
 

README.md

@@ -116,6 +116,10 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Default: false
     submodules: ''
 
+    # A list of submodules to checkout.
+    # Default: null
+    submodule-directories: ''
+
     # Add repository path as safe.directory for Git global config by running `git
     # config --global --add safe.directory <path>`
     # Default: true
@@ -143,6 +147,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 - [Checkout pull request HEAD commit instead of merge commit](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
 - [Checkout pull request on closed event](#Checkout-pull-request-on-closed-event)
 - [Push a commit using the built-in token](#Push-a-commit-using-the-built-in-token)
+- [Push a commit to a PR using the built-in token](#Push-a-commit-to-a-PR-using-the-built-in-token)
 
 ## Fetch only the root files
 
@@ -211,7 +216,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (nested)
 
@@ -225,7 +230,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (private)
 
@@ -288,6 +293,40 @@ jobs:
 ```
 *NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
 
+## Push a commit to a PR using the built-in token
+
+In a pull request trigger, `ref` is required as GitHub Actions checks out in detached HEAD mode, meaning it doesn’t check out your branch by default.
+
+```yaml
+on: pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - run: |
+          date > generated.txt
+          # Note: the following account information will not work on GHES
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "generated"
+          git push
+```
+
+*NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
+
+# Recommended permissions
+
+When using the `checkout` action in your GitHub Actions workflow, it is recommended to set the following `GITHUB_TOKEN` permissions to ensure proper functionality, unless alternative auth is provided via the `token` or `ssh-key` inputs:
+
+```yaml
+permissions:
+  contents: read
+```
+
 # License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE)

__test__/git-auth-helper.test.ts

@@ -813,6 +813,7 @@ async function setup(testName: string): Promise<void> {
     lfs: false,
     submodules: false,
     nestedSubmodules: false,
+    submoduleDirectories: [],
     persistCredentials: true,
     ref: 'refs/heads/main',
     repositoryName: 'my-repo',

__test__/input-helper.test.ts

@@ -21,6 +21,13 @@ describe('input-helper tests', () => {
     jest.spyOn(core, 'getInput').mockImplementation((name: string) => {
       return inputs[name]
     })
+    // Mock getMultilineInput
+    jest.spyOn(core, 'getMultilineInput').mockImplementation((name: string) => {
+      const input: string[] = (inputs[name] || '')
+        .split('\n')
+        .filter(x => x !== '')
+      return input.map(inp => inp.trim())
+    })
 
     // Mock error/warning/info/debug
     jest.spyOn(core, 'error').mockImplementation(jest.fn())
@@ -87,6 +94,7 @@ describe('input-helper tests', () => {
     expect(settings.showProgress).toBe(true)
     expect(settings.lfs).toBe(false)
     expect(settings.ref).toBe('refs/heads/some-ref')
+    expect(settings.submoduleDirectories).toStrictEqual([])
     expect(settings.repositoryName).toBe('some-repo')
     expect(settings.repositoryOwner).toBe('some-owner')
     expect(settings.repositoryPath).toBe(gitHubWorkspace)
@@ -144,4 +152,13 @@ describe('input-helper tests', () => {
     const settings: IGitSourceSettings = await inputHelper.getInputs()
     expect(settings.workflowOrganizationId).toBe(123456)
   })
+  it('sets submoduleDirectories', async () => {
+    inputs['submodule-directories'] = 'submodule1\nsubmodule2'
+    const settings: IGitSourceSettings = await inputHelper.getInputs()
+    expect(settings.submoduleDirectories).toStrictEqual([
+      'submodule1',
+      'submodule2'
+    ])
+    expect(settings.submodules).toBe(true)
+  })
 })

__test__/url-helper.test.ts

@@ -0,0 +1,92 @@
+import * as urlHelper from '../src/url-helper'
+
+describe('getServerUrl tests', () => {
+  it('basics', async () => {
+    // Note that URL::toString will append a trailing / when passed just a domain name ...
+    expect(urlHelper.getServerUrl().toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl(' ').toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl('   ').toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl('http://contoso.com').toString()).toBe(
+      'http://contoso.com/'
+    )
+    expect(urlHelper.getServerUrl('https://contoso.com').toString()).toBe(
+      'https://contoso.com/'
+    )
+    expect(urlHelper.getServerUrl('https://contoso.com/').toString()).toBe(
+      'https://contoso.com/'
+    )
+
+    // ... but can't make that same assumption when passed an URL that includes some deeper path.
+    expect(urlHelper.getServerUrl('https://contoso.com/a/b').toString()).toBe(
+      'https://contoso.com/a/b'
+    )
+  })
+})
+
+describe('isGhes tests', () => {
+  const pristineEnv = process.env
+
+  beforeEach(() => {
+    jest.resetModules()
+    process.env = {...pristineEnv}
+  })
+
+  afterAll(() => {
+    process.env = pristineEnv
+  })
+
+  it('basics', async () => {
+    delete process.env['GITHUB_SERVER_URL']
+    expect(urlHelper.isGhes()).toBeFalsy()
+    expect(urlHelper.isGhes('https://github.com')).toBeFalsy()
+    expect(urlHelper.isGhes('https://contoso.ghe.com')).toBeFalsy()
+    expect(urlHelper.isGhes('https://test.github.localhost')).toBeFalsy()
+    expect(urlHelper.isGhes('https://src.onpremise.fabrikam.com')).toBeTruthy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is not defined', async () => {
+    delete process.env['GITHUB_SERVER_URL']
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is set to github.com', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://github.com'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is set to a GitHub Enterprise Cloud-style URL', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://contoso.ghe.com'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable has a .localhost suffix', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://mock-github.localhost'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns true when the GITHUB_SERVER_URL environment variable is set to some other URL', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://src.onpremise.fabrikam.com'
+    expect(urlHelper.isGhes()).toBeTruthy()
+  })
+})
+
+describe('getServerApiUrl tests', () => {
+  it('basics', async () => {
+    expect(urlHelper.getServerApiUrl()).toBe('https://api.github.com')
+    expect(urlHelper.getServerApiUrl('https://github.com')).toBe(
+      'https://api.github.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://GitHub.com')).toBe(
+      'https://api.github.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://contoso.ghe.com')).toBe(
+      'https://api.contoso.ghe.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://fabrikam.GHE.COM')).toBe(
+      'https://api.fabrikam.ghe.com'
+    )
+    expect(
+      urlHelper.getServerApiUrl('https://src.onpremise.fabrikam.com')
+    ).toBe('https://src.onpremise.fabrikam.com/api/v3')
+  })
+})

action.yml

@@ -92,6 +92,10 @@ inputs:
       When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.com:` are
       converted to HTTPS.
     default: false
+  submodule-directories:
+    description: >
+      A list of submodules to checkout.
+    default: null
   set-safe-directory:
     description: Add repository path as safe.directory for Git global config by running `git config --global --add safe.directory <path>`
     default: true

dist/index.js

@@ -793,10 +793,10 @@ class GitCommandManager {
             yield this.execGit(args);
         });
     }
-    submoduleUpdate(fetchDepth, recursive) {
+    submoduleUpdate(fetchDepth, recursive, submoduleDirectories) {
         return __awaiter(this, void 0, void 0, function* () {
             const args = ['-c', 'protocol.version=2'];
-            args.push('submodule', 'update', '--init', '--force');
+            args.push('submodule', 'update', '--init', '--force', ...submoduleDirectories);
             if (fetchDepth > 0) {
                 args.push(`--depth=${fetchDepth}`);
             }
@@ -1340,7 +1340,7 @@ function getSource(settings) {
                 // Checkout submodules
                 core.startGroup('Fetching submodules');
                 yield git.submoduleSync(settings.nestedSubmodules);
-                yield git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules);
+                yield git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules, settings.submoduleDirectories);
                 yield git.submoduleForeach('git config --local gc.auto 0', settings.nestedSubmodules);
                 core.endGroup();
                 // Persist credentials
@@ -1801,6 +1801,7 @@ function getInputs() {
         // Submodules
         result.submodules = false;
         result.nestedSubmodules = false;
+        result.submoduleDirectories = [];
         const submodulesString = (core.getInput('submodules') || '').toUpperCase();
         if (submodulesString == 'RECURSIVE') {
             result.submodules = true;
@@ -1809,8 +1810,15 @@ function getInputs() {
         else if (submodulesString == 'TRUE') {
             result.submodules = true;
         }
+        const submoduleDirectories = core.getMultilineInput('submodule-directories');
+        if (submoduleDirectories.length > 0) {
+            result.submoduleDirectories = submoduleDirectories;
+            if (!result.submodules)
+                result.submodules = true;
+        }
         core.debug(`submodules = ${result.submodules}`);
         core.debug(`recursive submodules = ${result.nestedSubmodules}`);
+        core.debug(`submodule directories = ${result.submoduleDirectories}`);
         // Auth token
         result.authToken = core.getInput('token', { required: true });
         // SSH
@@ -2454,22 +2462,50 @@ function getFetchUrl(settings) {
     return `${serviceUrl.origin}/${encodedOwner}/${encodedName}`;
 }
 function getServerUrl(url) {
-    let urlValue = url && url.trim().length > 0
-        ? url
-        : process.env['GITHUB_SERVER_URL'] || 'https://github.com';
-    return new url_1.URL(urlValue);
+    let resolvedUrl = process.env['GITHUB_SERVER_URL'] || 'https://github.com';
+    if (hasContent(url, WhitespaceMode.Trim)) {
+        resolvedUrl = url;
+    }
+    return new url_1.URL(resolvedUrl);
 }
 function getServerApiUrl(url) {
-    let apiUrl = 'https://api.github.com';
-    if (isGhes(url)) {
-        const serverUrl = getServerUrl(url);
-        apiUrl = new url_1.URL(`${serverUrl.origin}/api/v3`).toString();
+    if (hasContent(url, WhitespaceMode.Trim)) {
+        let serverUrl = getServerUrl(url);
+        if (isGhes(url)) {
+            serverUrl.pathname = 'api/v3';
+        }
+        else {
+            serverUrl.hostname = 'api.' + serverUrl.hostname;
+        }
+        return pruneSuffix(serverUrl.toString(), '/');
     }
-    return apiUrl;
+    return process.env['GITHUB_API_URL'] || 'https://api.github.com';
 }
 function isGhes(url) {
-    const ghUrl = getServerUrl(url);
-    return ghUrl.hostname.toUpperCase() !== 'GITHUB.COM';
+    const ghUrl = new url_1.URL(url || process.env['GITHUB_SERVER_URL'] || 'https://github.com');
+    const hostname = ghUrl.hostname.trimEnd().toUpperCase();
+    const isGitHubHost = hostname === 'GITHUB.COM';
+    const isGitHubEnterpriseCloudHost = hostname.endsWith('.GHE.COM');
+    const isLocalHost = hostname.endsWith('.LOCALHOST');
+    return !isGitHubHost && !isGitHubEnterpriseCloudHost && !isLocalHost;
+}
+function pruneSuffix(text, suffix) {
+    if (hasContent(suffix, WhitespaceMode.Preserve) && (text === null || text === void 0 ? void 0 : text.endsWith(suffix))) {
+        return text.substring(0, text.length - suffix.length);
+    }
+    return text;
+}
+var WhitespaceMode;
+(function (WhitespaceMode) {
+    WhitespaceMode[WhitespaceMode["Trim"] = 0] = "Trim";
+    WhitespaceMode[WhitespaceMode["Preserve"] = 1] = "Preserve";
+})(WhitespaceMode || (WhitespaceMode = {}));
+function hasContent(text, whitespaceMode) {
+    let refinedText = text !== null && text !== void 0 ? text : '';
+    if (whitespaceMode == WhitespaceMode.Trim) {
+        refinedText = refinedText.trim();
+    }
+    return refinedText.length > 0;
 }
 
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "checkout",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "checkout",
-      "version": "4.2.1",
+      "version": "4.2.2",
       "license": "MIT",
       "dependencies": {
         "@actions/core": "^1.10.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkout",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "description": "checkout action",
   "main": "lib/main.js",
   "scripts": {

src/git-command-manager.ts

@@ -54,7 +54,11 @@ export interface IGitCommandManager {
   shaExists(sha: string): Promise<boolean>
   submoduleForeach(command: string, recursive: boolean): Promise<string>
   submoduleSync(recursive: boolean): Promise<void>
-  submoduleUpdate(fetchDepth: number, recursive: boolean): Promise<void>
+  submoduleUpdate(
+    fetchDepth: number,
+    recursive: boolean,
+    submoduleDirectories: string[]
+  ): Promise<void>
   submoduleStatus(): Promise<boolean>
   tagExists(pattern: string): Promise<boolean>
   tryClean(): Promise<boolean>
@@ -409,9 +413,19 @@ class GitCommandManager {
     await this.execGit(args)
   }
 
-  async submoduleUpdate(fetchDepth: number, recursive: boolean): Promise<void> {
+  async submoduleUpdate(
+    fetchDepth: number,
+    recursive: boolean,
+    submoduleDirectories: string[]
+  ): Promise<void> {
     const args = ['-c', 'protocol.version=2']
-    args.push('submodule', 'update', '--init', '--force')
+    args.push(
+      'submodule',
+      'update',
+      '--init',
+      '--force',
+      ...submoduleDirectories
+    )
     if (fetchDepth > 0) {
       args.push(`--depth=${fetchDepth}`)
     }

src/git-source-provider.ts

@@ -242,7 +242,11 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       // Checkout submodules
       core.startGroup('Fetching submodules')
       await git.submoduleSync(settings.nestedSubmodules)
-      await git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules)
+      await git.submoduleUpdate(
+        settings.fetchDepth,
+        settings.nestedSubmodules,
+        settings.submoduleDirectories
+      )
       await git.submoduleForeach(
         'git config --local gc.auto 0',
         settings.nestedSubmodules

src/git-source-settings.ts

@@ -74,6 +74,11 @@ export interface IGitSourceSettings {
    */
   nestedSubmodules: boolean
 
+  /**
+   * Indicates which submodule paths to checkout
+   */
+  submoduleDirectories: string[]
+
   /**
    * The auth token to use when fetching the repository
    */

src/input-helper.ts

@@ -125,6 +125,7 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   // Submodules
   result.submodules = false
   result.nestedSubmodules = false
+  result.submoduleDirectories = []
   const submodulesString = (core.getInput('submodules') || '').toUpperCase()
   if (submodulesString == 'RECURSIVE') {
     result.submodules = true
@@ -132,9 +133,16 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   } else if (submodulesString == 'TRUE') {
     result.submodules = true
   }
+
+  const submoduleDirectories = core.getMultilineInput('submodule-directories')
+  if (submoduleDirectories.length > 0) {
+    result.submoduleDirectories = submoduleDirectories
+    if (!result.submodules) result.submodules = true
+  }
+
   core.debug(`submodules = ${result.submodules}`)
   core.debug(`recursive submodules = ${result.nestedSubmodules}`)
-
+  core.debug(`submodule directories = ${result.submoduleDirectories}`)
   // Auth token
   result.authToken = core.getInput('token', {required: true})
 

src/url-helper.ts

@@ -21,26 +21,61 @@ export function getFetchUrl(settings: IGitSourceSettings): string {
 }
 
 export function getServerUrl(url?: string): URL {
-  let urlValue =
-    url && url.trim().length > 0
-      ? url
-      : process.env['GITHUB_SERVER_URL'] || 'https://github.com'
-  return new URL(urlValue)
+  let resolvedUrl = process.env['GITHUB_SERVER_URL'] || 'https://github.com'
+  if (hasContent(url, WhitespaceMode.Trim)) {
+    resolvedUrl = url!
+  }
+
+  return new URL(resolvedUrl)
 }
 
 export function getServerApiUrl(url?: string): string {
-  let apiUrl = 'https://api.github.com'
+  if (hasContent(url, WhitespaceMode.Trim)) {
+    let serverUrl = getServerUrl(url)
+    if (isGhes(url)) {
+      serverUrl.pathname = 'api/v3'
+    } else {
+      serverUrl.hostname = 'api.' + serverUrl.hostname
+    }
 
-  if (isGhes(url)) {
-    const serverUrl = getServerUrl(url)
-    apiUrl = new URL(`${serverUrl.origin}/api/v3`).toString()
+    return pruneSuffix(serverUrl.toString(), '/')
   }
 
-  return apiUrl
+  return process.env['GITHUB_API_URL'] || 'https://api.github.com'
 }
 
 export function isGhes(url?: string): boolean {
-  const ghUrl = getServerUrl(url)
+  const ghUrl = new URL(
+    url || process.env['GITHUB_SERVER_URL'] || 'https://github.com'
+  )
 
-  return ghUrl.hostname.toUpperCase() !== 'GITHUB.COM'
+  const hostname = ghUrl.hostname.trimEnd().toUpperCase()
+  const isGitHubHost = hostname === 'GITHUB.COM'
+  const isGitHubEnterpriseCloudHost = hostname.endsWith('.GHE.COM')
+  const isLocalHost = hostname.endsWith('.LOCALHOST')
+
+  return !isGitHubHost && !isGitHubEnterpriseCloudHost && !isLocalHost
+}
+
+function pruneSuffix(text: string, suffix: string) {
+  if (hasContent(suffix, WhitespaceMode.Preserve) && text?.endsWith(suffix)) {
+    return text.substring(0, text.length - suffix.length)
+  }
+  return text
+}
+
+enum WhitespaceMode {
+  Trim,
+  Preserve
+}
+
+function hasContent(
+  text: string | undefined,
+  whitespaceMode: WhitespaceMode
+): boolean {
+  let refinedText = text ?? ''
+  if (whitespaceMode == WhitespaceMode.Trim) {
+    refinedText = refinedText.trim()
+  }
+  return refinedText.length > 0
 }