GitHub Actions Integration
General
The GitHubActionsIntegration is designed to connect your GitHub organization with Puzl.
One integration scopes one team or department within your organization and enables its owner or maintainer to set up and manage runners for executing their jobs.
Puzl account owner (administrator) creates integrations in their Puzl root namespace, which can be found in Puzl dashboard after account creation.
metadata section
The metadata section is used to uniquely identify objects and to provide other information that is not directly tied to a resource's configuration.
Namespace defines the space within which each GitHubActionsIntegration name must be unique.
Each GitHubActionsIntegration name must be unique, within a namespace. The name must contain only lower-case letters, digits and dashes.
More Details
In this section, we've described only two fields that are necessary and sufficient for users on Puzl.
For a more in-depth explanation of metadata and its various fields, refer to the official Kubernetes documentation.
spec section
The section defines the desired state of the object. It describes the characteristics you want the resource to have: its configuration, settings, and data.
| Path: | spec.ownerIds |
Specifies the ids of the GitHub organizations or users where the Puzl application is installed and from which GitHub Actions are served.
If no owner ids are specified, the Integration will serve GitHub Action jobs from all owners where this Puzl user has installed the application.
| Default: | https://github.com |
| Path: | spec.githubUrl |
Designates the URL of your GitHub instance. Set this to your GitHub Enterprise host if applicable.
spec.resources
Defines the settings for managing resources of jobs.
spec.resources.persistentStorage
Configuration of job persistent data storage and cache.
| Default: | 30 |
| Path: | spec.resources.persistentStorage.cacheRetentionTime |
Specifies the duration in days for retaining cached data in the job's storage. The value is applied for each GitHub Runner within this integration.
This value determines how many days items in /cache directory remain available in the bucket before being automatically purged to free up space.
spec.serviceAccountPermissions
Contains capabilities of the Integration Service Account, which may be utilized for managing GitHub runners.
Access to the Integration Service Account may be granted to maintainer or owner of a specific GitHub group or project, allowing them to register and manage runners. The best practice of using Integration Service Account is to manage GitHub runners via CI/CD, following the typical GitOps approach. By default, Integration Service Account has limited permissions, allowing access to GitHubRunnerClaim and GitHubRunner resources only.
| Path: | spec.serviceAccountPermissions.readJobNamespaceSecrets |
If true, the Service Account is granted read permissions to all Secret resources in the Job Namespace.
These Secrets contain credentials, such as those for remote data storage access over S3 protocol, and the environment variables of the jobs.
| Path: | spec.serviceAccountPermissions.manageClaimNamespaceSecrets |
If true, the Service Account receives full access to manage all the credentials, stored as Secret resources within the Claim Namespace.
These Secrets might contain GitHub access tokens and the access tokens of the Integration Service Account itself. This setting carries significant security implications. Typically, while maintainers or owners of a specific GitHub group or project can manage GitHub runners using GitHubRunnerClaim resource, they might be restricted from using their own GitHub access tokens for runner registration, as per the admin's discretion. Enabling this setting allows these maintainers or owners to use GitHub access tokens issued by their own, giving them full autonomy over the process within the confines of the GitHub scope available to them.
| Path: | spec.runnerNamespaceRef |
The internal platform reference to the namespace where the runners of this integration will be set up.
This is crucial to ensure that runners for a specific integration are housed in a dedicated namespace, ensuring full isolation and security.
| Path: | spec.claimNamespaceRef |
Reference to the namespace where the GitHubRunnerClaim resources will be created.
This namespace is where users request runners, ensuring a clear separation between administration scope (Integration) and operation scope (Runner Claims). The access to this namespace can be granted to maintainers using serviceAccountRef.
spec.serviceAccountRef
Reference to a ServiceAccount that has been granted with the limited permissions for managing the claim namespace only.
| Path: | spec.serviceAccountRef.namespace |
Namespace where the referenced ServiceAccount is located.
status section
The section provides information about the current state of the object. It is populated by the platform and is used to inform users about the state of the resource, whether it's currently operational, and additional metadata like timestamps.
| Default: | Pending |
| Path: | status.phase |
Represents the high-level summary of the current status of the resource.
status.conditions[]
Conditions are designed based on Kubernetes API conventions. Conditions represent the logical states that the resource has passed through.
| Path: | status.conditions[].lastTransitionTime |
The last time the condition transitioned from one status to another.
| Path: | status.conditions[].observedGeneration |
The value of metadata.generation when the condition has been transited last time.
| Path: | status.conditions[].message |
A human-readable message indicating details about the transition.
| Path: | status.conditions[].reason |
A one-word, CamelCase reason caused the transition of the resource to this condition.
| Path: | status.conditions[].status |
The current status of the condition. Can be one of: True, False, or Unknown.