configure-git-global-credentials

README

= 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.<base>.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].