diff --git a/README.md b/README.md index b0f6224..6c6aa15 100644 --- a/README.md +++ b/README.md @@ -1,319 +1,146 @@ -[![Build and Test](https://github.com/actions/checkout/actions/workflows/test.yml/badge.svg)](https://github.com/actions/checkout/actions/workflows/test.yml) - -# Checkout V4 - -This action checks-out your repository under `$GITHUB_WORKSPACE`, so your workflow can access it. - -Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set `fetch-depth: 0` to fetch all history for all branches and tags. Refer [here](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) to learn which commit `$GITHUB_SHA` points to for different events. - -The auth token is persisted in the local git config. This enables your scripts to run authenticated git commands. The token is removed during post-job cleanup. Set `persist-credentials: false` to opt-out. - -When Git 2.18 or higher is not in your PATH, falls back to the REST API to download the files. - -# What's new - -Please refer to the [release page](https://github.com/actions/checkout/releases/latest) for the latest release notes. - -# Usage - - -```yaml -- uses: actions/checkout@v4 - with: - # Repository name with owner. For example, actions/checkout - # Default: ${{ github.repository }} - repository: '' - - # 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, uses the default branch. - ref: '' - - # 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: '' - - # 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: '' - - # The user to use when connecting to the remote SSH host. By default 'git' is - # used. - # Default: git - ssh-user: '' - - # Whether to configure the token or SSH key with the local git config - # Default: true - persist-credentials: '' - - # Relative path under $GITHUB_WORKSPACE to place the repository - path: '' - - # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching - # Default: true - clean: '' - - # Partially clone against a given filter. Overrides sparse-checkout if set. - # Default: null - filter: '' - - # Do a sparse checkout on given patterns. Each pattern should be separated with - # new lines. - # Default: null - sparse-checkout: '' - - # Specifies whether to use cone-mode when doing a sparse checkout. - # Default: true - sparse-checkout-cone-mode: '' - - # Number of commits to fetch. 0 indicates all history for all branches and tags. - # Default: 1 - fetch-depth: '' - - # Whether to fetch tags, even if fetch-depth > 0. - # Default: false - fetch-tags: '' - - # Whether to show progress status output when fetching. - # Default: true - show-progress: '' - - # 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: '' - - # Add repository path as safe.directory for Git global config by running `git - # config --global --add safe.directory ` - # Default: true - set-safe-directory: '' - - # The base URL for the GitHub instance that you are trying to clone from, will use - # environment defaults to fetch from the same instance that the workflow is - # running from unless specified. Example URLs are https://github.com or - # https://my-ghes-server.example.com - github-server-url: '' -``` - - -# Scenarios - -- [Fetch only the root files](#Fetch-only-the-root-files) -- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder) -- [Fetch only a single file](#Fetch-only-a-single-file) -- [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches) -- [Checkout a different branch](#Checkout-a-different-branch) -- [Checkout HEAD^](#Checkout-HEAD) -- [Checkout multiple repos (side by side)](#Checkout-multiple-repos-side-by-side) -- [Checkout multiple repos (nested)](#Checkout-multiple-repos-nested) -- [Checkout multiple repos (private)](#Checkout-multiple-repos-private) -- [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 - -```yaml -- uses: actions/checkout@v4 - with: - sparse-checkout: . -``` - -## Fetch only the root files and `.github` and `src` folder - -```yaml -- uses: actions/checkout@v4 - with: - sparse-checkout: | - .github - src -``` - -## Fetch only a single file - -```yaml -- uses: actions/checkout@v4 - with: - sparse-checkout: | - README.md - sparse-checkout-cone-mode: false -``` - -## Fetch all history for all tags and branches - -```yaml -- uses: actions/checkout@v4 - with: - fetch-depth: 0 -``` - -## Checkout a different branch - -```yaml -- uses: actions/checkout@v4 - with: - ref: my-branch -``` - -## Checkout HEAD^ - -```yaml -- uses: actions/checkout@v4 - with: - fetch-depth: 2 -- run: git checkout HEAD^ -``` - -## Checkout multiple repos (side by side) - -```yaml -- name: Checkout - uses: actions/checkout@v4 - with: - path: main - -- name: Checkout tools repo - uses: actions/checkout@v4 - with: - repository: my-org/my-tools - path: my-tools -``` -> - 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) - -```yaml -- name: Checkout - uses: actions/checkout@v4 - -- name: Checkout tools repo - uses: actions/checkout@v4 - with: - repository: my-org/my-tools - path: my-tools -``` -> - 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) - -```yaml -- name: Checkout - uses: actions/checkout@v4 - with: - path: main - -- name: Checkout private tools - uses: actions/checkout@v4 - with: - repository: my-org/my-private-tools - token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT - path: my-tools -``` - -> - `${{ github.token }}` is scoped to the current repository, so if you want to checkout a different repository that is private you will need to provide your own [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). - - -## Checkout pull request HEAD commit instead of merge commit - -```yaml -- uses: actions/checkout@v4 - with: - ref: ${{ github.event.pull_request.head.sha }} -``` - -## Checkout pull request on closed event - -```yaml -on: - pull_request: - branches: [main] - types: [opened, synchronize, closed] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 -``` - -## Push a commit using the built-in token - -```yaml -on: push -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - 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 - -## 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 - - -# License - -The scripts and documentation in this project are released under the [MIT License](LICENSE) +# Git Credential Manager + +[![Build Status][build-status-badge]][workflow-status] + +--- + +[Git Credential Manager][gcm] (GCM) is a secure +[Git credential helper][git-credential-helper] built on [.NET][dotnet] that runs +on Windows, macOS, and Linux. It aims to provide a consistent and secure +authentication experience, including multi-factor auth, to every major source +control hosting service and platform. + +GCM supports (in alphabetical order) [Azure DevOps][azure-devops], Azure DevOps +Server (formerly Team Foundation Server), Bitbucket, GitHub, and GitLab. +Compare to Git's [built-in credential helpers][git-tools-credential-storage] +(Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret), which +provide single-factor authentication support for username/password only. + +GCM replaces both the .NET Framework-based +[Git Credential Manager for Windows][gcm-for-windows] and the Java-based +[Git Credential Manager for Mac and Linux][gcm-for-mac-and-linux]. + +## Install + +See the [installation instructions][install] for the current version of GCM for +install options for your operating system. + +## Current status + +Git Credential Manager is currently available for Windows, macOS, and Linux\*. +GCM only works with HTTP(S) remotes; you can still use Git with SSH: + +- [Azure DevOps SSH][azure-devops-ssh] +- [GitHub SSH][github-ssh] +- [Bitbucket SSH][bitbucket-ssh] + +Feature|Windows|macOS|Linux\* +-|:-:|:-:|:-: +Installer/uninstaller|✓|✓|✓ +Secure platform credential storage [(see more)][gcm-credstores]|✓|✓|✓ +Multi-factor authentication support for Azure DevOps|✓|✓|✓ +Two-factor authentication support for GitHub|✓|✓|✓ +Two-factor authentication support for Bitbucket|✓|✓|✓ +Two-factor authentication support for GitLab|✓|✓|✓ +Windows Integrated Authentication (NTLM/Kerberos) support|✓|_N/A_|_N/A_ +Basic HTTP authentication support|✓|✓|✓ +Proxy support|✓|✓|✓ +`amd64` support|✓|✓|✓ +`x86` support|✓|_N/A_|✗ +`arm64` support|best effort|✓|✓ +`armhf` support|_N/A_|_N/A_|✓ + +(\*) GCM guarantees support only for [the Linux distributions that are officially +supported by dotnet][dotnet-distributions]. + +## Supported Git versions + +Git Credential Manager tries to be compatible with the broadest set of Git +versions (within reason). However there are some know problematic releases of +Git that are not compatible. + +- Git 1.x + + The initial major version of Git is not supported or tested with GCM. + +- Git 2.26.2 + + This version of Git introduced a breaking change with parsing credential + configuration that GCM relies on. This issue was fixed in commit + [`12294990`][gcm-commit-12294990] of the Git project, and released in Git + 2.27.0. + +## How to use + +Once it's installed and configured, Git Credential Manager is called implicitly +by Git. You don't have to do anything special, and GCM isn't intended to be +called directly by the user. For example, when pushing (`git push`) to +[Azure DevOps][azure-devops], [Bitbucket][bitbucket], or [GitHub][github], a +window will automatically open and walk you through the sign-in process. (This +process will look slightly different for each Git host, and even in some cases, +whether you've connected to an on-premises or cloud-hosted Git host.) Later Git +commands in the same repository will re-use existing credentials or tokens that +GCM has stored for as long as they're valid. + +Read full command line usage [here][gcm-usage]. + +### Configuring a proxy + +See detailed information [here][gcm-http-proxy]. + +## Additional Resources + +See the [documentation index][docs-index] for links to additional resources. + +## Experimental Features + +- [Windows broker (experimental)][gcm-windows-broker] + +## Future features + +Curious about what's coming next in the GCM project? Take a look at the [project +roadmap][roadmap]! You can find more details about the construction of the +roadmap and how to interpret it [here][roadmap-announcement]. + +## Contributing + +This project welcomes contributions and suggestions. +See the [contributing guide][gcm-contributing] to get started. + +This project follows [GitHub's Open Source Code of Conduct][gcm-coc]. + +## License + +We're [MIT][gcm-license] licensed. +When using GitHub logos, please be sure to follow the +[GitHub logo guidelines][github-logos]. + +[azure-devops]: https://azure.microsoft.com/en-us/products/devops +[azure-devops-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops +[bitbucket]: https://bitbucket.org +[bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html +[build-status-badge]: https://github.com/git-ecosystem/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg +[docs-index]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/README.md +[dotnet]: https://dotnet.microsoft.com +[dotnet-distributions]: https://learn.microsoft.com/en-us/dotnet/core/install/linux +[git-credential-helper]: https://git-scm.com/docs/gitcredentials +[gcm]: https://github.com/git-ecosystem/git-credential-manager +[gcm-coc]: CODE_OF_CONDUCT.md +[gcm-commit-12294990]: https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340 +[gcm-contributing]: CONTRIBUTING.md +[gcm-credstores]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/credstores.md +[gcm-for-mac-and-linux]: https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux +[gcm-for-windows]: https://github.com/microsoft/Git-Credential-Manager-for-Windows +[gcm-http-proxy]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/netconfig.md#http-proxy +[gcm-license]: LICENSE +[gcm-usage]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/usage.md +[gcm-windows-broker]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/windows-broker.md +[git-tools-credential-storage]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage +[github]: https://github.com +[github-ssh]: https://help.github.com/en/articles/connecting-to-github-with-ssh +[github-logos]: https://github.com/logos +[install]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/install.md +[ms-package-repos]: https://packages.microsoft.com/repos/ +[roadmap]: https://github.com/git-ecosystem/git-credential-manager/milestones?direction=desc&sort=due_date&state=open +[roadmap-announcement]: https://github.com/git-ecosystem/git-credential-manager/discussions/1203 +[workflow-status]: https://github.com/git-ecosystem/git-credential-manager/actions/workflows/continuous-integration.yml