Documentation
¶
Overview ¶
Package forge provides utilities for interacting with source code forges and version control systems. It includes functions for retrieving repository archives from platforms like Gitea, enabling integration with source code repositories for build, deployment, or analysis purposes.
Features:
- Repository archive retrieval from Gitea instances
- Authentication support using personal access tokens
- Archive format selection (currently supports tar.gz)
Package forge provides utilities for interacting with GitLab repositories and CI/CD systems. It includes functions for managing GitLab runners, tags, jobs, and repository archives, enabling integration with GitLab for build, deployment, and monitoring purposes.
Features:
- GitLab runner registration and management
- Tag creation and management
- Job monitoring and error analysis
- Repository archive download and extraction
- Detailed job state inspection
Index ¶
- func GiteaGetRepo(url, token, owner, repo, branch string) (string, error)
- func GitlabCreateTag(url, token, projectID, tagName, ref, message string) (*gitlab.Tag, error)
- func GitlabDisplayJobState(url, token, projectID string, jobID int) error
- func GitlabDownloadRepo(url, token, owner, repo, branch, filepath string) error
- func GitlabRegisterNewRunner(url, token, version, dataInit, registerArgs, sudoPass, gitlabUser string) error
- func GitlabRunners(url, token string) error
- type JobDetails
- type JobInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GiteaGetRepo ¶
GiteaGetRepo retrieves a repository archive from a Gitea instance and saves it as a local file. This function:
- Creates a Gitea client with the provided URL and authentication token
- Requests a tar.gz archive of the specified repository and branch
- Saves the archive to a local file named "{repo}-{branch}.tar.gz"
Parameters:
- url: Base URL of the Gitea instance (e.g., "https://gitea.example.com")
- token: Personal access token for authentication
- owner: Owner/organization name of the repository
- repo: Name of the repository
- branch: Branch, tag, or commit hash to retrieve
Returns:
- string: Path to the created archive file
- error: Error if any step fails, nil on success
The resulting archive file will be saved in the current working directory with the name:
"{repo}-{branch}.tar.gz"
Example:
filename, err := GiteaGetRepo("https://gitea.example.com", "my-token", "my-org", "my-repo", "main")
if err != nil {
log.Fatal(err)
}
func GitlabCreateTag ¶ added in v0.0.4
GitlabCreateTag creates a new tag on the specified GitLab repository. This function creates a new tag with the given name, reference, and message.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- projectID: ID or path of the project (e.g., "mygroup/myproject")
- tagName: Name of the tag to create
- ref: Branch, commit SHA, or tag from which to create the new tag
- message: Tag message/description
Returns:
- *gitlab.Tag: The created tag object
- error: If tag creation fails
func GitlabDisplayJobState ¶ added in v0.0.4
GitlabDisplayJobState displays the detailed state of a job with special formatting for errors. This function retrieves job details and displays them in a readable format, with special emphasis on error information for failed jobs.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- projectID: ID or path of the project
- jobID: ID of the job to display
Returns:
- error: If job details retrieval or display fails
func GitlabDownloadRepo ¶
GitlabDownloadRepo downloads a GitLab repository as an archive and extracts it. This function downloads a repository archive, extracts it, and strips the top-level directory.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- owner: Owner of the repository
- repo: Name of the repository
- branch: Branch, tag, or commit SHA to download
- filepath: Local path to extract the repository to
Returns:
- error: If download or extraction fails
func GitlabRegisterNewRunner ¶
func GitlabRegisterNewRunner(url, token, version, dataInit, registerArgs, sudoPass, gitlabUser string) error
GitlabRegisterNewRunner registers a new GitLab runner on the specified instance. This function:
- Downloads the GitLab runner binary
- Creates a new runner using the GitLab API
- Installs and registers the runner on the system
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- version: Version of the GitLab runner to install
- dataInit: JSON string with runner registration options
- registerArgs: Additional arguments for runner registration
- sudoPass: Sudo password for installing the runner
- gitlabUser: User account to run the GitLab runner service
Returns:
- error: If any step fails during runner registration
func GitlabRunners ¶
GitlabRunners lists all available GitLab runners in the instance. This function creates a GitLab client and retrieves a list of all registered runners. It logs each runner's information to the console.
Parameters:
- url: Base URL of the GitLab instance (e.g., "https://gitlab.example.com")
- token: Personal access token for authentication
Returns:
- error: If client creation or runner listing fails
Types ¶
type JobDetails ¶ added in v0.0.4
type JobDetails struct {
ID int `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
Stage string `json:"stage"`
Ref string `json:"ref"`
PipelineID int `json:"pipeline_id"`
CreatedAt time.Time `json:"created_at"`
StartedAt *time.Time `json:"started_at"`
FinishedAt *time.Time `json:"finished_at"`
Duration float64 `json:"duration"`
QueuedDuration float64 `json:"queued_duration"`
WebURL string `json:"web_url"`
FailureReason string `json:"failure_reason"`
ErrorMessage string `json:"error_message"`
TraceLog string `json:"trace_log"`
}
JobDetails represents detailed job information including error details and trace logs. Contains comprehensive information about a GitLab CI job, including timing and error information.
func GitlabGetJobDetails ¶ added in v0.0.4
func GitlabGetJobDetails(url, token, projectID string, jobID int) (*JobDetails, error)
GitlabGetJobDetails gets detailed information about a specific job, including trace logs. This function retrieves comprehensive information about a job, including its trace log if available.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- projectID: ID or path of the project
- jobID: ID of the job to query
Returns:
- *JobDetails: Detailed job information
- error: If job details retrieval fails
type JobInfo ¶ added in v0.0.4
type JobInfo struct {
ID int `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
Stage string `json:"stage"`
Ref string `json:"ref"`
Pipeline int `json:"pipeline_id"`
}
JobInfo represents simplified job information for display and processing. Contains basic information about a GitLab CI job.
func GitlabListJobsForTag ¶ added in v0.0.4
GitlabListJobsForTag lists all jobs for pipelines associated with a specific tag. This function finds all pipelines for the given tag and retrieves their jobs.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- projectID: ID or path of the project
- tagName: Name of the tag to query
Returns:
- []JobInfo: List of jobs for the tag
- error: If job retrieval fails
func GitlabListRunningJobsForTag ¶ added in v0.0.4
GitlabListRunningJobsForTag lists only the currently running or pending jobs for a specific tag. This function filters the jobs returned by GitlabListJobsForTag to only include running/pending jobs.
Parameters:
- url: Base URL of the GitLab instance
- token: Personal access token for authentication
- projectID: ID or path of the project
- tagName: Name of the tag to query
Returns:
- []JobInfo: List of running/pending jobs for the tag
- error: If job retrieval fails
Source Files