/ 
Git-Native-0.005
/ Git::Native::Credential

NAME

Git::Native::Credential - A libgit2 credential (passed back from acquire callbacks)

VERSION

version 0.005

SYNOPSIS

use Git::Native::Credential;

my $cred = Git::Native::Credential->userpass(
  username => 'git',
  password => $ENV{GITHUB_TOKEN},
);

# ssh-agent (matches CLI default for git+ssh remotes)
my $cred = Git::Native::Credential->ssh_agent(username => 'git');

# explicit key file
my $cred = Git::Native::Credential->ssh_key(
  username    => 'git',
  public_key  => "$ENV{HOME}/.ssh/id_ed25519.pub",
  private_key => "$ENV{HOME}/.ssh/id_ed25519",
  passphrase  => '',
);

DESCRIPTION

Returned from the credentials callback you pass to Git::Native::Remote's fetch/push. libgit2 takes ownership of the credential once the callback returns successfully — the Perl wrapper is disowned automatically so it won't double-free.

If you construct one without passing it to libgit2, DEMOLISH calls git_credential_free for you.

Every constructor is a class method, and every one of them croaks on a missing required argument before it reaches the FFI layer, so a typo in an argument name fails at the call site instead of somewhere inside libgit2.

userpass

Git::Native::Credential->userpass(
  username => 'git',
  password => $ENV{GITHUB_TOKEN},
);

Username and password (git_credential_userpass_plaintext_new). Both arguments are required. This is also the constructor for HTTPS token auth: the token goes in password, and which username the host expects varies (git and oauth2 are the usual answers).

ssh_key

Git::Native::Credential->ssh_key(
  username    => 'git',
  private_key => "$ENV{HOME}/.ssh/id_ed25519",
  public_key  => "$ENV{HOME}/.ssh/id_ed25519.pub",   # optional
  passphrase  => 'hunter2',                          # optional
);

An on-disk key pair (git_credential_ssh_key_new). username and private_key are required; public_key may be left out, in which case libgit2 derives it from the private key, and passphrase defaults to the empty string. The key files are not touched at construction time — libgit2 reads them when the transport uses the credential, so a wrong path surfaces as an auth failure during fetch / push, not here.

ssh_agent

Git::Native::Credential->ssh_agent( username => 'git' );

Take a key from the running ssh-agent (git_credential_ssh_key_from_agent). username is required; for the common hosting providers it is git, which is also what username_from_url yields for a git@host:path URL. This is the closest equivalent to what OpenSSH does for an ssh remote when an agent is running.

Note that libgit2 can be built without SSH support; on such a build this constructor and ssh_key already fail at allocation time with a Git::Native::Error, long before any connection is attempted.

default

Git::Native::Credential->default;

The "use the ambient identity" credential (git_credential_default_new), for Negotiate mechanisms such as NTLM or Kerberos. Takes no arguments, and only means anything on a transport that has such an identity to offer.

username

Git::Native::Credential->username( username => 'git' );

A username with no secret attached (git_credential_username_new). SSH needs this when the URL carries no user part: libgit2 then runs a pre-authentication round asking only for a username (allowed_types has GIT_CREDENTIAL_USERNAME, 32, set), and calls the credentials callback a second time for the actual key once it has one.

SEE ALSO

Git::Native::Remote

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-git-native/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.