= CloudBees action: Configure Git global credentials

Use this action to set up a Git global configuration for use in CloudBees workflows. This action authenticates the current user, by default scoped to repositories in the same organization as the workflow repository. After this step is run, all steps using the Git CLI in the same job authenticate with these credentials.

TIP: You can use this action to avoid failures due to lack of pre-authentication of private repositories. For example, if you are building a Go module that depends on other private modules, private repository authentication must be already in place for go mod download to run successfully.

[NOTE]

This action may set up authentication for different types of Git global configurations, including:

• link:https://git-scm.com/docs/gitcredentials#_custom_helpers[Git credentials helpers].
• link:https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtinsteadOf[`+url..insteadOf+` rules].
• link:https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresshCommand[`core.sshCommand` rule] to override the default user link:https://man7.org/linux/man-pages/man5/ssh_config.5.html[`+~/.ssh/config+`] configuration file, and specify per-host SSH private keys.

CloudBees recommends that if you are using a Git client other than the official Git CLI, make sure that your Git client supports the authentication configuration applied by this action.

== Inputs

[cols="2a,1a,3a,3a",options="header"] .Input details |===

| Input name | Data type | Required? | Description

| token | String | Yes | The token to configure.

| repositories | String | Required if provider is specified. | The repositories accessible via the token. For listing multiple repositories, CloudBees recommends using a line break separator, although the repositories parameter is a whitespace and/or comma-separated list. Wildcard syntax supports only a trailing /* on a repository name, or the match-all value (+*/*+).

| provider | String | CloudBees recommends specifying provider when specifying the provider server url, even for github-server-url, a case where it is technically considered redundant. | The source code management (SCM) provider.

| github-server-url | String | No | The GitHub server URL.

| bitbucket-server-url | String | No | The Bitbucket server URL.

| gitlab-server-url | String | No | The GitLab server URL.

|===

== Usage examples

Use this action to configure a Git token from a secret. This action does not currently work with configuring an SSH private key from a secret, or using CloudBees platform authentication.

=== Configure a token for all repositories in the same organization

Use a token for all repositories in the same organization as the workflow repository. For example, the action is run from +https://github.com/example/myjob+ repository, then the personal access token is configured for all repositories in the +https://github.com/example+ organization.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_TOKEN }}

---

=== Configure a token for specific repositories in the same SCM provider

Use a token for only the named repositories in the same SCM provider as the workflow repository.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_TOKEN }}
      repositories: |
        example/foo
        example/bar

---

=== Configure a token for all repositories in a different SCM provider

Use a token for all repositories in a named organization in a different SCM provider from that of the workflow repository.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_GITLAB_TOKEN }}
      provider: gitlab
      repositories: example/*

---

=== Configure a token for a GitHub Enterprise Server

Use a token for a GitHub Enterprise Server.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_GHE_TOKEN }}
      provider: github
      github-server-url: https://my-ghes-server.example.com
      repositories: "*/*"

---

=== Configure a token for GitHub SaaS, Bitbucket, or GitLab SCM provider instances

Use a token for GitHub SaaS, Bitbucket, or GitLab SCM provider instances.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_SCM_TOKEN }}
      provider: bitbucket
      bitbucket-server-url: https://my-bbdc-server.example.com
      repositories: "*/*"

---

=== Configure a token when a step is repeated multiple times in a job

Use a token when a step is repeated multiple times in the same job, resulting in layered authentication. In the case of multiple steps matching the same authentication, the last one takes precedence.

In your YAML file, add:

[source,yaml]

  - name: Git global credentials for GitHub
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_GITHUB_TOKEN }}
      repositories: |
        example/foo
        example/bar
  - name: Git global credentials for GHE
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_GHE_TOKEN }}
      provider: github
      github-server-url: https://my-ghes-server.example.com
      repositories: "*/*"
  - name: Git global credentials for GitLab
    uses: cloudbees-io/configure-git-global-credentials@v1
    with:
      token: ${{ secrets.MY_GITLAB_TOKEN }}
      provider: gitlab
      repositories: example/*

---

== License

This code is made available under the link:https://opensource.org/license/mit/[MIT license].

== References

• Learn more about link:https://docs.cloudbees.com/docs/cloudbees-saas-platform-actions/latest/[using actions in CloudBees workflows].
• Learn about link:https://docs.cloudbees.com/docs/cloudbees-saas-platform/latest/[the CloudBees platform].