Name
GitHub::Crud - Create, Read, Update, Delete files, commits, issues, and web hooks on GitHub.
Synopsis
Create, Read, Update, Delete files, commits, issues, and web hooks on GitHub as described at:
https://developer.github.com/v3/repos/contents/#update-a-fileUpload a file from an action
Upload a file created during a github action to the repository for that action:
GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
perl -M"GitHub::Crud" -e"GitHub::Crud::writeFileFromFileFromCurrentRun q(output.txt);"Upload a folder
Commit a folder to GitHub then read and check some of the uploaded content:
use GitHub::Crud;
use Data::Table::Text qw(:all);
my $f = temporaryFolder; # Folder in which we will create some files to upload in the commit
my $c = dateTimeStamp; # Create some content
my $if = q(/home/phil/.face); # Image file
writeFile(fpe($f, q(data), $_, qw(txt)), $c) for 1..3; # Place content in files in a sub folder
copyBinaryFile $if, my $If = fpe $f, qw(face jpg); # Add an image
my $g = GitHub::Crud::new # Create GitHub
(userid => q(philiprbrenan),
repository => q(aaa),
branch => q(test),
confessOnFailure => 1);
$g->loadPersonalAccessToken; # Load a personal access token
$g->writeCommit($f); # Upload commit - confess to any errors
my $C = $g->read(q(data/1.txt)); # Read data written in commit
my $I = $g->read(q(face.jpg));
my $i = readBinaryFile $if;
confess "Date stamp failed" unless $C eq $c; # Check text
confess "Image failed" unless $i eq $I; # Check image
confess "Write commit succeeded";Prerequisites
Please install curl if it is not already present on your computer.
sudo apt-get install curlPersonal Access Token
You will need to create a personal access token if you wish to gain write access to your respositories : https://github.com/settings/tokens. Depending on your security requirements you can either install this token at the well known location:
/etc/GitHubCrudPersonalAccessToken/<github userid>or at a location of your choice. If you use a well known location then the personal access token will be loaded automatically for you, else you will need to supply it to each call via the "personalAccessToken" attribute.
The following code will install a personal access token for github userid uuuuuu in the default location:
use GitHub::Crud qw(:all);
my $g = GitHub::Crud::gitHub
(userid => q(uuuuuu),
personalAccessToken => q(........................................),
);
$g->savePersonalAccessToken;Description
Create, Read, Update, Delete files, commits, issues, and web hooks on GitHub.
Version 20240624.
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Constructor
Create a GitHub object with the specified attributes describing the interface with GitHub.
new (%attributes)
Create a new GitHub object with attributes as described at: "GitHub::Crud Definition".
Parameter Description
1 %attributes Attribute valuesExample:
my $f = temporaryFolder; # Folder in which we will create some files to upload in the commit
my $c = dateTimeStamp; # Create some content
my $if = q(/home/phil/.face); # Image file
writeFile(fpe($f, q(data), $_, qw(txt)), $c) for 1..3; # Place content in files in a sub folder
copyBinaryFile $if, my $If = fpe $f, qw(face jpg); # Add an image
my $g = GitHub::Crud::new # Create GitHub # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
(userid => q(philiprbrenan),
repository => q(aaa),
branch => q(test),
confessOnFailure => 1);
$g->loadPersonalAccessToken; # Load a personal access token
$g->writeCommit($f); # Upload commit - confess to any errors
my $C = $g->read(q(data/1.txt)); # Read data written in commit
my $I = $g->read(q(face.jpg));
my $i = readBinaryFile $if;
confess "Date stamp failed" unless $C eq $c; # Check text
confess "Image failed" unless $i eq $I; # Check image
success "Write commit succeeded";Files
File actions on the contents of GitHub repositories.
list($gitHub)
List all the files contained in a GitHub repository or all the files below a specified folder in the repository.
Required attributes: userid, repository.
Optional attributes: gitFolder, refOrBranch, nonRecursive, patKey.
Use the gitFolder parameter to specify the folder to start the list from, by default, the listing will start at the root folder of your repository.
Use the nonRecursive option if you require only the files in the start folder as otherwise all the folders in the start folder will be listed as well which might take some time.
If the list operation is successful, failed is set to false and fileList is set to refer to an array of the file names found.
If the list operation fails then failed is set to true and fileList is set to refer to an empty array.
Returns the list of file names found or empty list if no files were found.
Parameter Description
1 $gitHub GitHubExample:
success "list:", gitHub->list; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
# list: alpha.data .github/workflows/test.yaml images/aaa.txt images/aaa/bbb.txt # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲read($gitHub, $File)
Read data from a file on GitHub.
Required attributes: userid, repository.
Optional attributes: gitFile = the file to read, refOrBranch, patKey.
If the read operation is successful, failed is set to false and readData is set to the data read from the file.
If the read operation fails then failed is set to true and readData is set to undef.
Returns the data read or undef if no file was found.
Parameter Description
1 $gitHub GitHub
2 $File File to read if not specified in gitFileExample:
my $g = gitHub;
$g->gitFile = my $f = q(z'2 'z"z.data);
my $d = q(𝝰𝝱𝝲);
$g->write($d);
confess "read FAILED" unless $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Read passed";write ($gitHub, $data, $File)
Write the specified data into a file on GitHub.
Required attributes: userid, repository, patKey. Either specify the target file on: GitHub using the gitFile attribute or supply it as the third parameter. Returns true on success else undef.
Parameter Description
1 $gitHub GitHub object
2 $data Data to be written
3 $File Optionally the name of the file on githubExample:
my $g = gitHub;
$g->gitFile = "zzz.data";
my $d = dateTimeStamp.q( 𝝰𝝱𝝲);
if (1)
{my $t = time();
$g->write($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "First write time: ", time() - $t; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
}
my $r = $g->read;
lll "Write bbb: $r";
if (1)
{my $t = time();
$g->write($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "Second write time: ", time() - $t; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
}
confess "write FAILED" unless $g->exists; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Write passed";readBlob($gitHub, $sha)
Required attributes: userid, repository, patKey. Returns the content of the blob identified by the specified SHA.
Parameter Description
1 $gitHub GitHub object
2 $sha Data to be writtenExample:
my $g = gitHub;
$g->gitFile = "face.jpg";
my $d = readBinaryFile(q(/home/phil/.face));
my $s = $g->writeBlob($d);
my $S = q(4a2df549febb701ba651aae46e041923e9550cb8);
confess q(Write blob FAILED) unless $s eq $S;
my $D = $g->readBlob($s); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess q(Write/Read blob FAILED) unless $d eq $D;
success q(Write/Read blob passed);writeBlob ($gitHub, $data)
Write data into a GitHub as a blob that can be referenced by future commits.
Required attributes: userid, repository, patKey. Returns the SHA of the created blob or undef in a failure occurred.
Parameter Description
1 $gitHub GitHub object
2 $data Data to be writtenExample:
my $g = gitHub;
$g->gitFile = "face.jpg";
my $d = readBinaryFile(q(/home/phil/.face));
my $s = $g->writeBlob($d); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my $S = q(4a2df549febb701ba651aae46e041923e9550cb8);
confess q(Write blob FAILED) unless $s eq $S;
my $D = $g->readBlob($s);
confess q(Write/Read blob FAILED) unless $d eq $D;
success q(Write/Read blob passed);copy($gitHub, $target)
Copy a source file from one location to another target location in your GitHub repository, overwriting the target file if it already exists.
Required attributes: userid, repository, patKey, gitFile = the file to be copied.
Optional attributes: refOrBranch.
If the write operation is successful, failed is set to false otherwise it is set to true.
Returns updated if the write updated the file, created if the write created the file else undef if the write failed.
Parameter Description
1 $gitHub GitHub object
2 $target The name of the file to be createdExample:
my ($f1, $f2) = ("zzz.data", "zzz2.data");
my $g = gitHub;
$g->gitFile = $f2; $g->delete;
$g->gitFile = $f1;
my $d = dateTimeStamp;
my $w = $g->write($d);
my $r = $g->copy($f2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "Copy created: $r";
$g->gitFile = $f2;
my $D = $g->read;
lll "Read ccc: $D";
confess "copy FAILED" unless $d eq $D; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Copy passed"exists ($gitHub)
Test whether a file exists on GitHub or not and returns an object including the sha and size fields if it does else undef.
Required attributes: userid, repository, gitFile file to test.
Optional attributes: refOrBranch, patKey.
Parameter Description
1 $gitHub GitHub objectExample:
my $g = gitHub;
$g->gitFile = "test4.html";
my $d = dateTimeStamp;
$g->write($d);
confess "exists FAILED" unless $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$g->delete;
confess "exists FAILED" if $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Exists passed";rename ($gitHub, $target)
Rename a source file on GitHub if the target file name is not already in use.
Required attributes: userid, repository, patKey, gitFile = the file to be renamed.
Optional attributes: refOrBranch.
Returns the new name of the file renamed if the rename was successful else undef if the rename failed.
Parameter Description
1 $gitHub GitHub object
2 $target The new name of the fileExample:
my ($f1, $f2) = qw(zzz.data zzz2.data);
my $g = gitHub;
$g->gitFile = $f2; $g->delete;
my $d = dateTimeStamp;
$g->gitFile = $f1;
$g->write($d);
confess "rename FAILED" unless $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$g->rename($f2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess "rename FAILED" if $g->exists; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$g->gitFile = $f2;
confess "rename FAILED" if $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Rename passed";delete ($gitHub)
Delete a file from GitHub.
Required attributes: userid, repository, patKey, gitFile = the file to be deleted.
Optional attributes: refOrBranch.
If the delete operation is successful, failed is set to false otherwise it is set to true.
Returns true if the delete was successful else false.
Parameter Description
1 $gitHub GitHub objectExample:
my $g = gitHub;
my $d = dateTimeStamp;
$g->gitFile = "zzz.data";
$g->write($d);
confess "delete FAILED" unless $g->read eq $d; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
if (1)
{my $t = time();
my $d = $g->delete; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "Delete 1: ", $d;
lll "First delete: ", time() - $t; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess "delete FAILED" if $g->exists; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
}
if (1)
{my $t = time();
my $d = $g->delete; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "Delete 1: ", $d;
lll "Second delete: ", time() - $t; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess "delete FAILED" if $g->exists; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
}
success "Delete passed";Repositories
Perform actions on GitHub repositories.
getRepository ($gitHub)
Get the overall details of a repository
Parameter Description
1 $gitHub GitHub objectExample:
my $r = gitHub(repository => q(C))->getRepository; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Get repository succeeded";listCommits ($gitHub)
List all the commits in a GitHub repository.
Required attributes: userid, repository.
Parameter Description
1 $gitHub GitHub objectExample:
my $c = gitHub->listCommits; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my %s = listCommitShas $c;
lll "Commits
", dump $c;
lll "Commit shas
", dump \%s;
success "ListCommits passed";listCommitShas ($commits)
Create {commit name => sha} from the results of "listCommits".
Parameter Description
1 $commits Commits from L</listCommits>Example:
my $c = gitHub->listCommits;
my %s = listCommitShas $c; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
lll "Commits
", dump $c;
lll "Commit shas
", dump \%s;
success "ListCommits passed";writeCommit ($gitHub, $folder, @files)
Write all the files in a $folder (or just the the named files) into a GitHub repository in parallel as a commit on the specified branch.
Required attributes: userid, repository, refOrBranch.
Parameter Description
1 $gitHub GitHub object
2 $folder File prefix to remove
3 @files Files to writeExample:
my $f = temporaryFolder; # Folder in which we will create some files to upload in the commit
my $c = dateTimeStamp; # Create some content
my $if = q(/home/phil/.face); # Image file
writeFile(fpe($f, q(data), $_, qw(txt)), $c) for 1..3; # Place content in files in a sub folder
copyBinaryFile $if, my $If = fpe $f, qw(face jpg); # Add an image
my $g = GitHub::Crud::new # Create GitHub
(userid => q(philiprbrenan),
repository => q(aaa),
branch => q(test),
confessOnFailure => 1);
$g->loadPersonalAccessToken; # Load a personal access token
$g->writeCommit($f); # Upload commit - confess to any errors # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my $C = $g->read(q(data/1.txt)); # Read data written in commit
my $I = $g->read(q(face.jpg));
my $i = readBinaryFile $if;
confess "Date stamp failed" unless $C eq $c; # Check text
confess "Image failed" unless $i eq $I; # Check image
success "Write commit succeeded";listWebHooks($gitHub)
List web hooks associated with your GitHub repository.
Required: userid, repository, patKey.
If the list operation is successful, failed is set to false otherwise it is set to true.
Returns true if the list operation was successful else false.
Parameter Description
1 $gitHub GitHub objectExample:
success join ' ', q(Webhooks:), dump(gitHub->listWebHooks); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲createPushWebHook ($gitHub)
Create a web hook for your GitHub userid.
Required: userid, repository, url, patKey.
Optional: secret.
If the create operation is successful, failed is set to false otherwise it is set to true.
Returns true if the web hook was created successfully else false.
Parameter Description
1 $gitHub GitHub objectExample:
my $g = gitHub;
my $d = $g->createPushWebHook; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success join ' ', "Create web hook:", dump($d);listRepositories($gitHub)
List the repositories accessible to a user on GitHub.
Required: userid.
Returns details of the repositories.
Parameter Description
1 $gitHub GitHub objectExample:
success "List repositories: ", dump(gitHub()->listRepositories); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲createRepository($gitHub)
Create a repository on GitHub.
Required: userid, repository.
Returns true if the issue was created successfully else false.
Parameter Description
1 $gitHub GitHub objectExample:
gitHub(repository => q(ccc))->createRepository; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Create repository succeeded";createRepositoryFromSavedToken ($userid, $repository, $private, $accessFolderOrToken)
Create a repository on GitHub using an access token either as supplied or saved in a file using savePersonalAccessToken.
Returns true if the issue was created successfully else false.
Parameter Description
1 $userid Userid on GitHub
2 $repository The repository name
3 $private True if the repo is private
4 $accessFolderOrToken Location of access token.Example:
createRepositoryFromSavedToken(q(philiprbrenan), q(ddd)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Create repository succeeded";Issues
Create issues on GitHub.
createIssue ($gitHub)
Create an issue on GitHub.
Required: userid, repository, body, title.
If the operation is successful, failed is set to false otherwise it is set to true.
Returns true if the issue was created successfully else false.
Parameter Description
1 $gitHub GitHub objectExample:
gitHub(title=>q(Hello), body=>q(World))->createIssue; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Create issue succeeded";Using saved access tokens
Call methods directly using a saved access token rather than first creating a GitHub description object and then calling methods using it. This is often more convenient if you just want to perform one or two actions using a Perl one liner. See: https://github.com/philiprbrenan/GitHubCrud/blob/main/.github/workflows/main.yml for examples in action.
createIssueFromSavedToken ($userid, $repository, $title, $body, $accessFolderOrToken)
Create an issue on GitHub using an access token as supplied or saved in a file using savePersonalAccessToken.
Returns true if the issue was created successfully else false.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $title Issue title
4 $body Issue body
5 $accessFolderOrToken Location of access token.Example:
&createIssueFromSavedToken(qw(philiprbrenan ddd hello World)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Create issue succeeded";writeFileUsingSavedToken($userid, $repository, $file, $content, $accessFolderOrToken)
Write to a file on GitHub using a personal access token as supplied or saved in a file. Return 1 on success or confess to any failure.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $file File name on github
4 $content File content
5 $accessFolderOrToken Location of access token.Example:
my $s = q(HelloWorld);
&writeFileUsingSavedToken(qw(philiprbrenan ddd hello.txt), $s); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my $S = gitHub(repository=>q(ddd), gitFile=>q(hello.txt))->read;
confess "Write file using saved token FAILED" unless $s eq $S;
success "Write file using saved token succeeded";writeFileFromFileUsingSavedToken($userid, $repository, $file, $localFile, $accessFolderOrToken)
Copy a file to GitHub using a personal access token as supplied or saved in a file. Return 1 on success or confess to any failure.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $file File name on github
4 $localFile File content
5 $accessFolderOrToken Location of access token.Example:
my $f = writeFile(undef, my $s = "World
");
&writeFileFromFileUsingSavedToken(qw(philiprbrenan ddd hello.txt), $f); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my $S = gitHub(repository=>q(ddd), gitFile=>q(hello.txt))->read;
confess "Write file from file using saved token FAILED" unless $s eq $S;
success "Write file from file using saved token succeeded"readFileUsingSavedToken ($userid, $repository, $file, $accessFolderOrToken)
Read from a file on GitHub using a personal access token as supplied or saved in a file. Return the content of the file on success or confess to any failure.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $file File name on GitHub
4 $accessFolderOrToken Location of access token.Example:
my $s = q(Hello to the World);
&writeFileUsingSavedToken(qw(philiprbrenan ddd hello.txt), $s);
my $S = &readFileUsingSavedToken (qw(philiprbrenan ddd hello.txt)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess "Read file using saved token FAILED" unless $s eq $S;
success "Read file using saved token succeeded"writeFolderUsingSavedToken ($userid, $repository, $targetFolder, $localFolder, $accessFolderOrToken)
Write all the files in a local folder to a target folder on a named GitHub repository using a personal access token as supplied or saved in a file.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $targetFolder Target folder on GitHub
4 $localFolder Local folder name
5 $accessFolderOrToken Location of access token.Example:
writeCommitUsingSavedToken("philiprbrenan", "test", "/home/phil/files/");
writeFolderUsingSavedToken("philiprbrenan", "test", "files", "/home/phil/files/"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲writeCommitUsingSavedToken ($userid, $repository, $source, $accessFolderOrToken)
Write all the files in a local folder to a named GitHub repository using a personal access token as supplied or saved in a file.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $source Local folder on GitHub
4 $accessFolderOrToken Optionally: location of access token.Example:
writeCommitUsingSavedToken("philiprbrenan", "test", "/home/phil/files/"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
writeFolderUsingSavedToken("philiprbrenan", "test", "files", "/home/phil/files/");deleteFileUsingSavedToken ($userid, $repository, $target, $accessFolderOrToken)
Delete a file on GitHub using a saved token
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $target File on GitHub
4 $accessFolderOrToken Optional: the folder containing saved access tokens.Example:
deleteFileUsingSavedToken("philiprbrenan", "test", "aaa.data"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲getRepositoryUsingSavedToken($userid, $repository, $accessFolderOrToken)
Get repository details from GitHub using a saved token
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $accessFolderOrToken Optionally: location of access token.Example:
my $r = getRepositoryUsingSavedToken(q(philiprbrenan), q(aaa)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Get repository using saved access token succeeded";listRepositoryUsingSavedToken ($userid, $repository, $accessFolderOrToken)
List the files in a repository using a saved token
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $accessFolderOrToken Optionally: location of access token.Example:
listRepositoryUsingSavedToken("philiprbrenan", "test", "/home/phil/files/"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲getRepositoryUpdatedAtUsingSavedToken ($userid, $repository, $accessFolderOrToken)
Get the last time a repository was updated via the 'updated_at' field using a saved token and return the time in number of seconds since the Unix epoch.
Parameter Description
1 $userid Userid on GitHub
2 $repository Repository name
3 $accessFolderOrToken Optionally: location of access token.Example:
my $u = getRepositoryUpdatedAtUsingSavedToken(q(philiprbrenan), q(aaa)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
success "Get repository updated_at field succeeded";Actions
Perform an action against the current repository while running as a GitHub action. If such an action requires a security token please supply the token as shown in at the end of: https://github.com/philiprbrenan/maze/blob/main/.github/workflows/main.yml.
createIssueInCurrentRepo($title, $body)
Create an issue in the current GitHub repository if we are running on GitHub.
Parameter Description
1 $title Title of issue
2 $body Body of issueExample:
createIssueInCurrentRepo("Hello World", "Need to run Hello World"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
writeFileFromCurrentRun("output.text", "Hello World");
writeFileFromFileFromCurrentRun("output.txt");
writeBinaryFileFromFileInCurrentRun("image.jpg", "out/image.jpg");writeFileFromCurrentRun ($target, $text)
Write text into a file in the current GitHub repository if we are running on GitHub.
Parameter Description
1 $target The target file name in the repo
2 $text The text to write into this fileExample:
createIssueInCurrentRepo("Hello World", "Need to run Hello World");
writeFileFromCurrentRun("output.text", "Hello World"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
writeFileFromFileFromCurrentRun("output.txt");
writeBinaryFileFromFileInCurrentRun("image.jpg", "out/image.jpg");writeFileFromFileFromCurrentRun ($target)
Write to a file in the current GitHub repository by copying a local file if we are running on GitHub.
Parameter Description
1 $target File name both locally and in the repoExample:
createIssueInCurrentRepo("Hello World", "Need to run Hello World");
writeFileFromCurrentRun("output.text", "Hello World");
writeFileFromFileFromCurrentRun("output.txt"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
writeBinaryFileFromFileInCurrentRun("image.jpg", "out/image.jpg");writeBinaryFileFromFileInCurrentRun ($target, $source)
Write to a file in the current GitHub repository by copying a local binary file if we are running on GitHub.
Parameter Description
1 $target The target file name in the repo
2 $source The current file name in the runExample:
createIssueInCurrentRepo("Hello World", "Need to run Hello World");
writeFileFromCurrentRun("output.text", "Hello World");
writeFileFromFileFromCurrentRun("output.txt");
writeBinaryFileFromFileInCurrentRun("image.jpg", "out/image.jpg"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲Access tokens
Load and save access tokens. Some GitHub requests must be signed with an Oauth access token. These methods help you store and reuse such tokens. Access tokens can be created at: https://github.com/settings/tokens.
savePersonalAccessToken ($gitHub)
Save a GitHub personal access token by userid in folder personalAccessTokenFolder.
Parameter Description
1 $gitHub GitHub objectExample:
my $d = temporaryFolder;
my $t = join '', 1..20;
my $g = gitHub
(userid => q(philiprbrenan),
personalAccessToken => $t,
personalAccessTokenFolder => $d,
);
$g->savePersonalAccessToken; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my $T = $g->loadPersonalAccessToken;
confess "Load/Save token FAILED" unless $t eq $T;
success "Load/Save token succeeded"loadPersonalAccessToken ($gitHub)
Load a personal access token by userid from folder personalAccessTokenFolder.
Parameter Description
1 $gitHub GitHub objectExample:
my $d = temporaryFolder;
my $t = join '', 1..20;
my $g = gitHub
(userid => q(philiprbrenan),
personalAccessToken => $t,
personalAccessTokenFolder => $d,
);
$g->savePersonalAccessToken;
my $T = $g->loadPersonalAccessToken; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
confess "Load/Save token FAILED" unless $t eq $T;
success "Load/Save token succeeded"Hash Definitions
GitHub::Crud Definition
Attributes describing the interface with GitHub.
Input fields
body
The body of an issue.
branch
Branch name (you should create this branch first) or omit it for the default branch which is usually 'master'.
confessOnFailure
Confess to any failures
gitFile
File name on GitHub - this name can contain '/'. This is the file to be read from, written to, copied from, checked for existence or deleted.
gitFolder
Folder name on GitHub - this name can contain '/'.
message
Optional commit message
nonRecursive
Fetch only one level of files with list.
personalAccessToken
A personal access token with scope "public_repo" as generated on page: https://github.com/settings/tokens.
personalAccessTokenFolder
The folder into which to save personal access tokens. Set to /etc/GitHubCrudPersonalAccessToken by default.
private
Whether the repository being created should be private or not.
repository
The name of the repository to be worked on minus the userid - you should create this repository first manually.
secret
The secret for a web hook - this is created by the creator of the web hook and remembered by GitHub,
title
The title of an issue.
userid
Userid on GitHub of the repository to be worked on.
webHookUrl
The url for a web hook.
Output fields
failed
Defined if the last request to GitHub failed else undef.
fileList
Reference to an array of files produced by list.
readData
Data produced by read.
response
A reference to GitHub's response to the latest request.
GitHub::Crud::Response Definition
Attributes describing a response from GitHub.
Output fields
content
The actual content of the file from GitHub.
data
The data received from GitHub, normally in Json format.
status
Our version of Status.
Private Methods
currentRepo ()
Create a GitHub object for the current repo if we are on GitHub actions
Index
1 copy - Copy a source file from one location to another target location in your GitHub repository, overwriting the target file if it already exists.
2 createIssue - Create an issue on GitHub.
3 createIssueFromSavedToken - Create an issue on GitHub using an access token as supplied or saved in a file using savePersonalAccessToken.
4 createIssueInCurrentRepo - Create an issue in the current GitHub repository if we are running on GitHub.
5 createPushWebHook - Create a web hook for your GitHub userid.
6 createRepository - Create a repository on GitHub.
7 createRepositoryFromSavedToken - Create a repository on GitHub using an access token either as supplied or saved in a file using savePersonalAccessToken.
8 currentRepo - Create a GitHub object for the current repo if we are on GitHub actions
9 delete - Delete a file from GitHub.
10 deleteFileUsingSavedToken - Delete a file on GitHub using a saved token
11 exists - Test whether a file exists on GitHub or not and returns an object including the sha and size fields if it does else undef.
12 getRepository - Get the overall details of a repository
13 getRepositoryUpdatedAtUsingSavedToken - Get the last time a repository was updated via the 'updated_at' field using a saved token and return the time in number of seconds since the Unix epoch.
14 getRepositoryUsingSavedToken - Get repository details from GitHub using a saved token
15 list - List all the files contained in a GitHub repository or all the files below a specified folder in the repository.
16 listCommits - List all the commits in a GitHub repository.
17 listCommitShas - Create {commit name => sha} from the results of "listCommits".
18 listRepositories - List the repositories accessible to a user on GitHub.
19 listRepositoryUsingSavedToken - List the files in a repository using a saved token
20 listWebHooks - List web hooks associated with your GitHub repository.
21 loadPersonalAccessToken - Load a personal access token by userid from folder personalAccessTokenFolder.
22 new - Create a new GitHub object with attributes as described at: "GitHub::Crud Definition".
23 read - Read data from a file on GitHub.
24 readBlob - Read a blob from GitHub.
25 readFileUsingSavedToken - Read from a file on GitHub using a personal access token as supplied or saved in a file.
26 rename - Rename a source file on GitHub if the target file name is not already in use.
27 savePersonalAccessToken - Save a GitHub personal access token by userid in folder personalAccessTokenFolder.
28 write - Write the specified data into a file on GitHub.
29 writeBinaryFileFromFileInCurrentRun - Write to a file in the current GitHub repository by copying a local binary file if we are running on GitHub.
30 writeBlob - Write data into a GitHub as a blob that can be referenced by future commits.
31 writeCommit - Write all the files in a $folder (or just the the named files) into a GitHub repository in parallel as a commit on the specified branch.
32 writeCommitUsingSavedToken - Write all the files in a local folder to a named GitHub repository using a personal access token as supplied or saved in a file.
33 writeFileFromCurrentRun - Write text into a file in the current GitHub repository if we are running on GitHub.
34 writeFileFromFileFromCurrentRun - Write to a file in the current GitHub repository by copying a local file if we are running on GitHub.
35 writeFileFromFileUsingSavedToken - Copy a file to GitHub using a personal access token as supplied or saved in a file.
36 writeFileUsingSavedToken - Write to a file on GitHub using a personal access token as supplied or saved in a file.
37 writeFolderUsingSavedToken - Write all the files in a local folder to a target folder on a named GitHub repository using a personal access token as supplied or saved in a file.
Installation
This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:
sudo cpan install GitHub::CrudAuthor
Copyright
Copyright (c) 2016-2023 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.