GitHub Actions Runner
Description
gar
(GitHub Actions Runner) is a command-line utility written in Rust for working with GitHub Actions. It allows you to run GitHub Actions workflows directly from the command line.
Installation
You can download a precompiled binary from the Releases page on GitHub. Choose the version that matches your operating system and architecture.
If you want to compile the project from source, follow these steps:
git clone https://github.com/s00d/github-action-runner.git
cd gar
cargo build --release
This will create an executable gar
file in the target/release
directory.
crates.io
Before installing the github-action-runner
package, you need to install Rust. Rust is a programming language that the package is built with. Here are the steps to install Rust:
-
Open a terminal or command prompt.
-
Visit the official Rust website at https://www.rust-lang.org/.
-
Follow the instructions on the website to download and install Rust for your operating system.
-
After the installation is complete, verify that Rust is installed correctly by running the following command in your terminal:
rustc --version
You can install the github-action-runner
package using the cargo
utility. Make sure you have Rust compiler and cargo
tool installed.
-
Open a terminal or command prompt.
-
Run the following command to install the package:
cargo install github-action-runner
Usage
Preparation
Before using the gar
utility, you need to obtain a GitHub token. This can be done in the settings of your account on GitHub. The token should have the following permissions:
- Read
code
andmetadata
- Read and write
actions
,administration
, andworkflows
Save the token in a .github_token
file in the root directory of the project or set it as an environment variable GAR_TOKEN
.
The utility will first look for the GAR_TOKEN
environment variable. If it is not found, it will then look for the .github_token
file. If neither is found, it will prompt you to enter the token manually.
Running Workflows
To run a workflow, simply execute the gar
file. The utility will automatically determine the owner and repository name based on the origin
remote repository in your local Git repository. It will then prompt you to select a workflow to run from a list of available workflows in your repository.
Global Usage
To make the gar
executable globally available, you can move it to a directory that is in your PATH
.
On Linux:
sudo mv gar /usr/local/bin/
chmod +x /usr/local/bin/gar
On macOS:
sudo mv gar /usr/local/bin/
chmod +x /usr/local/bin/gar
xattr -cr /usr/local/bin/gar
On Windows:
- Open "System" in Control Panel.
- Click on "Advanced system settings".
- "Advanced" tab > "Environment Variables".
- In the "System variables" section, select "Path" > "Edit".
- "New" > Enter the path to the directory where the gar executable is located.
- Now you can run gar from anywhere in the command line.
Now you can run gar
from anywhere in the command line.
Args
Argument | Short | Description | Default Value |
---|---|---|---|
--ref |
-r |
The name of the repository branch on which the action will be run. | The name of the current Git branch |
--owner |
-o |
The owner of the repository where the action is located. | The owner of the current Git repository |
--repo |
-p |
The name of the repository where the action is located. | The name of the current Git repository |
--token |
-t |
The token used for authentication. If not provided, the GAR_TOKEN environment variable will be used. | None |
--inputs |
-i |
The name of the event that triggers the action. | An empty string |
Please note that all the parameters are optional, and if not provided, default values will be used.
gar --ref <branch-name>
gar --owner <owner-name> --repo <repository-name>
gar --token <personal-access-token>
gar --inputs <input-name1>=<value1>,<input-name2>=<value2>
History
Command: The gar history
command provides a historical record of the runs of a selected workflow. Here's an example of how you might use it:
$ gar history
When you run this command, it will first prompt you to select a workflow from your repository. After you select a workflow, it will fetch and display the last 10 runs of the selected workflow in a table format.
Here's an example of what the output might look like:
ID Branch Status Conclusion Created At Updated At Url
123456789 main completed success 2023-04-12T23:05:34Z 2023-04-12T23:06:00Z https://github.com/owner/repo/actions/runs/123456789
987654321 feature completed failure 2023-04-12T22:05:34Z 2023-04-12T22:06:00Z https://github.com/owner/repo/actions/runs/987654321
...
Each row in the table represents a single run of the workflow. The columns provide the following information:
ID
: The unique identifier of the run.Branch
: The branch where the run was triggered.Status
: The status of the run (e.g.,completed
,in_progress
,queued
).Conclusion
: The outcome of the run if it has completed (e.g.,success
,failure
). If the run is not yet completed, this field will showN/A
.Created At
: The time when the run was created.Updated At
: The time when the run was last updated.Url
: The URL where you can view the run on GitHub.
details
Command: The details
command displays the details of a GitHub Actions workflow run.
Syntax
gar details
Description
The details
command allows you to view the details of a GitHub Actions workflow run, including information such as the run ID, name, display title, URL, status, conclusion, branch, creation timestamp, and update timestamp. Additionally, it retrieves and displays the logs associated with the run.
This command provides a comprehensive overview of a specific workflow run, allowing you to analyze its execution and troubleshoot any issues that may have occurred.
Example
gar details
Help
For more information about the available commands and options, you can refer to the package documentation or run github-action-runner --help in your terminal.
Action example
https://github.com/s00d/github-action-runner/blob/main/.github/workflows/runner.yml
Linux Dependensis
gcc-multilib g++-multilib pkg-config libssl-dev libasound2-dev
License
gar
is distributed under the MIT license. See the LICENSE
file for details.