mirror of
https://github.com/actions/checkout.git
synced 2025-04-03 02:50:11 +08:00
Add files via upload
This commit is contained in:
Abu2rkii
GitHub
parent
cbb722410c
commit
b96f34e6fa
465
README.md
465
README.md
@ -1,319 +1,146 @@
|
|||||||
[](https://github.com/actions/checkout/actions/workflows/test.yml)
|
# Git Credential Manager
|
||||||
|
|
||||||
# Checkout V4
|
[![Build Status][build-status-badge]][workflow-status]
|
||||||
|
|
||||||
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.
|
[Git Credential Manager][gcm] (GCM) is a secure
|
||||||
|
[Git credential helper][git-credential-helper] built on [.NET][dotnet] that runs
|
||||||
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.
|
on Windows, macOS, and Linux. It aims to provide a consistent and secure
|
||||||
|
authentication experience, including multi-factor auth, to every major source
|
||||||
When Git 2.18 or higher is not in your PATH, falls back to the REST API to download the files.
|
control hosting service and platform.
|
||||||
|
|
||||||
# What's new
|
GCM supports (in alphabetical order) [Azure DevOps][azure-devops], Azure DevOps
|
||||||
|
Server (formerly Team Foundation Server), Bitbucket, GitHub, and GitLab.
|
||||||
Please refer to the [release page](https://github.com/actions/checkout/releases/latest) for the latest release notes.
|
Compare to Git's [built-in credential helpers][git-tools-credential-storage]
|
||||||
|
(Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret), which
|
||||||
# Usage
|
provide single-factor authentication support for username/password only.
|
||||||
|
|
||||||
<!-- start usage -->
|
GCM replaces both the .NET Framework-based
|
||||||
```yaml
|
[Git Credential Manager for Windows][gcm-for-windows] and the Java-based
|
||||||
- uses: actions/checkout@v4
|
[Git Credential Manager for Mac and Linux][gcm-for-mac-and-linux].
|
||||||
with:
|
|
||||||
# Repository name with owner. For example, actions/checkout
|
## Install
|
||||||
# Default: ${{ github.repository }}
|
|
||||||
repository: ''
|
See the [installation instructions][install] for the current version of GCM for
|
||||||
|
install options for your operating system.
|
||||||
# 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.
|
## Current status
|
||||||
# Otherwise, uses the default branch.
|
|
||||||
ref: ''
|
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:
|
||||||
# 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
|
- [Azure DevOps SSH][azure-devops-ssh]
|
||||||
# commands. The post-job step removes the PAT.
|
- [GitHub SSH][github-ssh]
|
||||||
#
|
- [Bitbucket SSH][bitbucket-ssh]
|
||||||
# We recommend using a service account with the least permissions necessary. Also
|
|
||||||
# when generating a new PAT, select the least scopes necessary.
|
Feature|Windows|macOS|Linux\*
|
||||||
#
|
-|:-:|:-:|:-:
|
||||||
# [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)
|
Installer/uninstaller|✓|✓|✓
|
||||||
#
|
Secure platform credential storage [(see more)][gcm-credstores]|✓|✓|✓
|
||||||
# Default: ${{ github.token }}
|
Multi-factor authentication support for Azure DevOps|✓|✓|✓
|
||||||
token: ''
|
Two-factor authentication support for GitHub|✓|✓|✓
|
||||||
|
Two-factor authentication support for Bitbucket|✓|✓|✓
|
||||||
# SSH key used to fetch the repository. The SSH key is configured with the local
|
Two-factor authentication support for GitLab|✓|✓|✓
|
||||||
# git config, which enables your scripts to run authenticated git commands. The
|
Windows Integrated Authentication (NTLM/Kerberos) support|✓|_N/A_|_N/A_
|
||||||
# post-job step removes the SSH key.
|
Basic HTTP authentication support|✓|✓|✓
|
||||||
#
|
Proxy support|✓|✓|✓
|
||||||
# We recommend using a service account with the least permissions necessary.
|
`amd64` support|✓|✓|✓
|
||||||
#
|
`x86` support|✓|_N/A_|✗
|
||||||
# [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)
|
`arm64` support|best effort|✓|✓
|
||||||
ssh-key: ''
|
`armhf` support|_N/A_|_N/A_|✓
|
||||||
|
|
||||||
# Known hosts in addition to the user and global host key database. The public SSH
|
(\*) GCM guarantees support only for [the Linux distributions that are officially
|
||||||
# keys for a host may be obtained using the utility `ssh-keyscan`. For example,
|
supported by dotnet][dotnet-distributions].
|
||||||
# `ssh-keyscan github.com`. The public key for github.com is always implicitly
|
|
||||||
# added.
|
## Supported Git versions
|
||||||
ssh-known-hosts: ''
|
|
||||||
|
Git Credential Manager tries to be compatible with the broadest set of Git
|
||||||
# Whether to perform strict host key checking. When true, adds the options
|
versions (within reason). However there are some know problematic releases of
|
||||||
# `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
|
Git that are not compatible.
|
||||||
# the input `ssh-known-hosts` to configure additional hosts.
|
|
||||||
# Default: true
|
- Git 1.x
|
||||||
ssh-strict: ''
|
|
||||||
|
The initial major version of Git is not supported or tested with GCM.
|
||||||
# The user to use when connecting to the remote SSH host. By default 'git' is
|
|
||||||
# used.
|
- Git 2.26.2
|
||||||
# Default: git
|
|
||||||
ssh-user: ''
|
This version of Git introduced a breaking change with parsing credential
|
||||||
|
configuration that GCM relies on. This issue was fixed in commit
|
||||||
# Whether to configure the token or SSH key with the local git config
|
[`12294990`][gcm-commit-12294990] of the Git project, and released in Git
|
||||||
# Default: true
|
2.27.0.
|
||||||
persist-credentials: ''
|
|
||||||
|
## How to use
|
||||||
# Relative path under $GITHUB_WORKSPACE to place the repository
|
|
||||||
path: ''
|
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
|
||||||
# Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
|
called directly by the user. For example, when pushing (`git push`) to
|
||||||
# Default: true
|
[Azure DevOps][azure-devops], [Bitbucket][bitbucket], or [GitHub][github], a
|
||||||
clean: ''
|
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,
|
||||||
# Partially clone against a given filter. Overrides sparse-checkout if set.
|
whether you've connected to an on-premises or cloud-hosted Git host.) Later Git
|
||||||
# Default: null
|
commands in the same repository will re-use existing credentials or tokens that
|
||||||
filter: ''
|
GCM has stored for as long as they're valid.
|
||||||
|
|
||||||
# Do a sparse checkout on given patterns. Each pattern should be separated with
|
Read full command line usage [here][gcm-usage].
|
||||||
# new lines.
|
|
||||||
# Default: null
|
### Configuring a proxy
|
||||||
sparse-checkout: ''
|
|
||||||
|
See detailed information [here][gcm-http-proxy].
|
||||||
# Specifies whether to use cone-mode when doing a sparse checkout.
|
|
||||||
# Default: true
|
## Additional Resources
|
||||||
sparse-checkout-cone-mode: ''
|
|
||||||
|
See the [documentation index][docs-index] for links to additional resources.
|
||||||
# Number of commits to fetch. 0 indicates all history for all branches and tags.
|
|
||||||
# Default: 1
|
## Experimental Features
|
||||||
fetch-depth: ''
|
|
||||||
|
- [Windows broker (experimental)][gcm-windows-broker]
|
||||||
# Whether to fetch tags, even if fetch-depth > 0.
|
|
||||||
# Default: false
|
## Future features
|
||||||
fetch-tags: ''
|
|
||||||
|
Curious about what's coming next in the GCM project? Take a look at the [project
|
||||||
# Whether to show progress status output when fetching.
|
roadmap][roadmap]! You can find more details about the construction of the
|
||||||
# Default: true
|
roadmap and how to interpret it [here][roadmap-announcement].
|
||||||
show-progress: ''
|
|
||||||
|
## Contributing
|
||||||
# Whether to download Git-LFS files
|
|
||||||
# Default: false
|
This project welcomes contributions and suggestions.
|
||||||
lfs: ''
|
See the [contributing guide][gcm-contributing] to get started.
|
||||||
|
|
||||||
# Whether to checkout submodules: `true` to checkout submodules or `recursive` to
|
This project follows [GitHub's Open Source Code of Conduct][gcm-coc].
|
||||||
# recursively checkout submodules.
|
|
||||||
#
|
## License
|
||||||
# When the `ssh-key` input is not provided, SSH URLs beginning with
|
|
||||||
# `git@github.com:` are converted to HTTPS.
|
We're [MIT][gcm-license] licensed.
|
||||||
#
|
When using GitHub logos, please be sure to follow the
|
||||||
# Default: false
|
[GitHub logo guidelines][github-logos].
|
||||||
submodules: ''
|
|
||||||
|
[azure-devops]: https://azure.microsoft.com/en-us/products/devops
|
||||||
# Add repository path as safe.directory for Git global config by running `git
|
[azure-devops-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops
|
||||||
# config --global --add safe.directory <path>`
|
[bitbucket]: https://bitbucket.org
|
||||||
# Default: true
|
[bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html
|
||||||
set-safe-directory: ''
|
[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
|
||||||
# The base URL for the GitHub instance that you are trying to clone from, will use
|
[dotnet]: https://dotnet.microsoft.com
|
||||||
# environment defaults to fetch from the same instance that the workflow is
|
[dotnet-distributions]: https://learn.microsoft.com/en-us/dotnet/core/install/linux
|
||||||
# running from unless specified. Example URLs are https://github.com or
|
[git-credential-helper]: https://git-scm.com/docs/gitcredentials
|
||||||
# https://my-ghes-server.example.com
|
[gcm]: https://github.com/git-ecosystem/git-credential-manager
|
||||||
github-server-url: ''
|
[gcm-coc]: CODE_OF_CONDUCT.md
|
||||||
```
|
[gcm-commit-12294990]: https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340
|
||||||
<!-- end usage -->
|
[gcm-contributing]: CONTRIBUTING.md
|
||||||
|
[gcm-credstores]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/credstores.md
|
||||||
# Scenarios
|
[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
|
||||||
- [Fetch only the root files](#Fetch-only-the-root-files)
|
[gcm-http-proxy]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/netconfig.md#http-proxy
|
||||||
- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder)
|
[gcm-license]: LICENSE
|
||||||
- [Fetch only a single file](#Fetch-only-a-single-file)
|
[gcm-usage]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/usage.md
|
||||||
- [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches)
|
[gcm-windows-broker]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/windows-broker.md
|
||||||
- [Checkout a different branch](#Checkout-a-different-branch)
|
[git-tools-credential-storage]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
|
||||||
- [Checkout HEAD^](#Checkout-HEAD)
|
[github]: https://github.com
|
||||||
- [Checkout multiple repos (side by side)](#Checkout-multiple-repos-side-by-side)
|
[github-ssh]: https://help.github.com/en/articles/connecting-to-github-with-ssh
|
||||||
- [Checkout multiple repos (nested)](#Checkout-multiple-repos-nested)
|
[github-logos]: https://github.com/logos
|
||||||
- [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
|
[install]: https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/install.md
|
||||||
- [Checkout pull request HEAD commit instead of merge commit](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
|
[ms-package-repos]: https://packages.microsoft.com/repos/
|
||||||
- [Checkout pull request on closed event](#Checkout-pull-request-on-closed-event)
|
[roadmap]: https://github.com/git-ecosystem/git-credential-manager/milestones?direction=desc&sort=due_date&state=open
|
||||||
- [Push a commit using the built-in token](#Push-a-commit-using-the-built-in-token)
|
[roadmap-announcement]: https://github.com/git-ecosystem/git-credential-manager/discussions/1203
|
||||||
- [Push a commit to a PR using the built-in token](#Push-a-commit-to-a-PR-using-the-built-in-token)
|
[workflow-status]: https://github.com/git-ecosystem/git-credential-manager/actions/workflows/continuous-integration.yml
|
||||||
|
|
||||||
## 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)
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user