GitHub#

Overview#

The GitHub application enables Nokia EDA to integrate with GitHub to support the following scenarios:

• Create GitHub issues or run GitHub Actions workflows based on the triggering events from EDA (alarms or queries).
• Create GitHub issues or run GitHub Actions workflows using the workflow definition resources provided by the application.

Installation#

You can install the GitHub app via EDA Store or by running an AppInstaller workflow with kubectl or edactl:

apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: github-install
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: github.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: latest
        type: alias

cat << 'EOF' | kubectl apply -f -
apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: github-install
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: github.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: latest
        type: alias

EOF

Install Settings#

The app provides the following install-time settings:

• proxyConfigName: ConfigMap name used for HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Default: proxy-config
• githubCPULimit: CPU limit for the controller pod. Default: "1"
• githubMemoryLimit: memory limit for the controller pod. Default: "1Gi"

The default requests are set to500m CPU and 500Mi memory.

These settings control the deployment in the EDA base namespace and can be provided through spec.apps[].appSettings in the AppInstaller workflow or directly in the EDA UI.

apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: github-install-sized
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: github.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: latest
        type: alias
      appSettings:
        proxyConfigName: proxy-config
        githubCPULimit: "2"
        githubMemoryLimit: 2Gi

cat << 'EOF' | kubectl apply -f -
apiVersion: appstore.eda.nokia.com/v1
kind: AppInstaller
metadata:
  name: github-install-sized
  namespace: eda-system
spec:
  operation: install
  apps:
    - appId: github.eda.nokia.com
      catalog: eda-catalog-builtin-apps
      version:
        value: latest
        type: alias
      appSettings:
        proxyConfigName: proxy-config
        githubCPULimit: "2"
        githubMemoryLimit: 2Gi

EOF

Getting Started#

Create a GitHub instance first, then reference it from the GitHubIssue or GitHubAction resources.

Namespace rules:

• GitHubInstance, GitHubIssue, and GitHubAction are namespace-scoped and are typically created in a user namespace such as eda
• ClusterGitHubInstance, ClusterGitHubIssue, and ClusterGitHubAction are namespaced CRs, but are intended for use from the EDA base namespace

GitHub Instances#

A GitHub instance defines the target GitHub API endpoint and authentication token.

Notable specification fields:

• apiBaseURL: optional base URL. Leave empty or set https://api.github.com for the public GitHub (github.com) instance.
• authSecretRef.name: Secret name containing GitHub credentials (Personal Access Token)
• authSecretRef.key: validated by the API and typically set to token

Credential behavior:

• the runtime reads data.token from the referenced Secret
• it also accepts username and password, but GitHub PAT-based authentication is the most common authentication method
• for GitHub Enterprise, set apiBaseURL to the enterprise base URL, for example https://ghe.example.com

The resource status contains the fields related to the connectivity parameters of this instance:

• connected: indicates if the instance is connected to GitHub
• error: contains the error message if the instance is not connected
• lastChecked: the last time the instance was checked

apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: eda
type: Opaque
stringData:
  token: ghp_exampleTokenValue
---
apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubInstance
metadata:
  name: github-server
  namespace: eda
spec:
  apiBaseURL: https://api.github.com
  authSecretRef:
    name: github-secret
    key: token

cat << 'EOF' | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: eda
type: Opaque
stringData:
  token: ghp_exampleTokenValue
---
apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubInstance
metadata:
  name: github-server
  namespace: eda
spec:
  apiBaseURL: https://api.github.com
  authSecretRef:
    name: github-secret
    key: token

EOF

GitHub Issues#

Use GitHubIssue or ClusterGitHubIssue to create issues in GitHub when an alarm or query event occurs.

Notable specification fields:

• trigger.alarm: create a GitHub issue when the matching alarm types occur
• trigger.query: create a GitHub issue when the matching query updates
• repo: repository name
• instance: referenced instance resource
• closeOnResolve: close the GitHub issue when the alarm clears or the query object disappears
• issue.title and issue.body: Go templates rendered with the triggering event data
• issue.assignees, issue.labels, issue.milestone: optional GitHub issue metadata

Behavior notes:

• the app searches for an existing open issue by rendered title and appends a hash of the source path to keep one issue per source object
• if an issue already exists, the app adds a comment instead of opening a duplicate

apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubIssue
metadata:
  name: influxdb-connection-issue
  namespace: eda
spec:
  trigger:
    alarm:
      include:
        - InfluxDBServerConnectionFailed
  repo: network-operations
  instance: github-server
  closeOnResolve: true
  issue:
    title: "[ALERT] InfluxDB server connection failed"
    body: |
      Probable cause: {{ index . "probableCause" }}
      Last changed: {{ index . "lastChanged" }}
      Details: {{ index . "description" }}
    assignees:
      - network-ops
    milestone: Rel-25.10
    labels:
      - eda
      - alarm

cat << 'EOF' | kubectl apply -f -
apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubIssue
metadata:
  name: influxdb-connection-issue
  namespace: eda
spec:
  trigger:
    alarm:
      include:
        - InfluxDBServerConnectionFailed
  repo: network-operations
  instance: github-server
  closeOnResolve: true
  issue:
    title: "[ALERT] InfluxDB server connection failed"
    body: |
      Probable cause: {{ index . "probableCause" }}
      Last changed: {{ index . "lastChanged" }}
      Details: {{ index . "description" }}
    assignees:
      - network-ops
    milestone: Rel-25.10
    labels:
      - eda
      - alarm

EOF

Duplicate Issue Handling#

The app does not use the rendered issue title by itself as the unique key.

For each triggering alarm or query event, the app:

• renders spec.issue.title
• computes a hash from the triggering object path in EDA state
• builds the final GitHub issue title as <rendered title> -- <hash>

This means duplicate-looking issue titles are handled as follows:

• if the same source object triggers again, the hash is the same, so the app finds the existing open issue and adds a comment instead of creating another issue
• if two different source objects render the same title text, their source paths are different, so the hashes differ and the app creates separate issues
• if the closeOnResolve field is set to true, the app looks up the same hashed title and closes that matching issue when the source alarm clears or the query object disappears

In practice, the visible title in GitHub is intentionally suffixed with a hash so the app can safely distinguish repeated events from different objects even when the human-readable part of the title is identical.

GitHub Actions#

Use GitHubAction or ClusterGitHubAction to dispatch a GitHub Actions workflow when an alarm or query event occurs.

Notable specification fields:

• trigger.alarm or trigger.query: dispatch GitHub Actions workflow when the matching alarm types or query updates occur
• repo: repository name
• workflow: workflow file name
• ref: branch, tag, or commit reference
• instance: referenced instance resource
• parameters[]: workflow input parameters

Parameters can be:

• static with value.staticValue
• dynamic with value.dynamicValue, which fetches a field from EDA using the path, field, and optional where conditions

apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubAction
metadata:
  name: interface-admin-down
  namespace: eda
spec:
  trigger:
    query:
      path: .namespace.node.srl.interface
      fields: []
      where: .namespace.node.name = "leaf-1" and name = "ethernet-1/9" and admin-state = "disable"
  repo: network-operations
  workflow: ci.yml
  ref: main
  instance: github-server
  parameters:
    - name: trigger_source
      value:
        staticValue: EDA
    - name: interface_name
      value:
        dynamicValue:
          path: .namespace.node{.name=="leaf-1"}.srl.interface
          field: name
          where: name = "ethernet-1/9" and admin-state = "disable"
    - name: interface_index
      value:
        dynamicValue:
          path: .namespace.node{.name=="leaf-1"}.srl.interface
          field: ifindex
          where: name = "ethernet-1/9" and admin-state = "disable"

cat << 'EOF' | kubectl apply -f -
apiVersion: github.eda.nokia.com/v1alpha1
kind: GitHubAction
metadata:
  name: interface-admin-down
  namespace: eda
spec:
  trigger:
    query:
      path: .namespace.node.srl.interface
      fields: []
      where: .namespace.node.name = "leaf-1" and name = "ethernet-1/9" and admin-state = "disable"
  repo: network-operations
  workflow: ci.yml
  ref: main
  instance: github-server
  parameters:
    - name: trigger_source
      value:
        staticValue: EDA
    - name: interface_name
      value:
        dynamicValue:
          path: .namespace.node{.name=="leaf-1"}.srl.interface
          field: name
          where: name = "ethernet-1/9" and admin-state = "disable"
    - name: interface_index
      value:
        dynamicValue:
          path: .namespace.node{.name=="leaf-1"}.srl.interface
          field: ifindex
          where: name = "ethernet-1/9" and admin-state = "disable"

EOF

Cluster-Scoped Resources#

Use the cluster variants from the EDA base namespace when you want centralized automation across namespaces.

Cluster-specific behavior:

• ClusterGitHubIssue and ClusterGitHubAction can watch alarms across namespaces through trigger.alarm.namespaces
• query triggers can use fully qualified .namespace paths
• cluster resources must reference ClusterGitHubInstance

Workflow Resources#

The app also installs two workflow definition resources:

• CreateGithubIssue
• RunGithubWorkflow

These workflows are run-to-completion programs that do not watch alarms or queries continuously; instead, they submit a single GitHub operation (issue or workflow dispatch) when the workflow is run.

apiVersion: github.eda.nokia.com/v1alpha1
kind: CreateGithubIssue
metadata:
  name: create-github-issue-now
  namespace: eda
spec:
  instance: github-server
  repo: network-operations
  issue:
    title: "Manual issue from EDA workflow"
    body: |
      This issue was created by the GitHub app workflow resource.
    assignees:
      - network-ops
    labels:
      - eda
      - workflow

cat << 'EOF' | kubectl apply -f -
apiVersion: github.eda.nokia.com/v1alpha1
kind: CreateGithubIssue
metadata:
  name: create-github-issue-now
  namespace: eda
spec:
  instance: github-server
  repo: network-operations
  issue:
    title: "Manual issue from EDA workflow"
    body: |
      This issue was created by the GitHub app workflow resource.
    assignees:
      - network-ops
    labels:
      - eda
      - workflow

EOF

apiVersion: github.eda.nokia.com/v1alpha1
kind: RunGithubWorkflow
metadata:
  name: run-github-workflow-now
  namespace: eda
spec:
  instance: github-server
  repo: network-operations
  workflow: ci.yml
  ref: main
  parameters:
    - name: trigger_source
      value:
        staticValue: EDA
    - name: requested_by
      value:
        staticValue: workflow-cr

cat << 'EOF' | kubectl apply -f -
apiVersion: github.eda.nokia.com/v1alpha1
kind: RunGithubWorkflow
metadata:
  name: run-github-workflow-now
  namespace: eda
spec:
  instance: github-server
  repo: network-operations
  workflow: ci.yml
  ref: main
  parameters:
    - name: trigger_source
      value:
        staticValue: EDA
    - name: requested_by
      value:
        staticValue: workflow-cr

EOF

Validation Notes#

When creating resources, follow these rules:

• instances require both authSecretRef.name and authSecretRef.key
• issues require repo, instance, issue.title, issue.body, at least one assignee, and either an alarm or query trigger
• issue title and body templates must be valid Go templates
• actions require repo, workflow, ref, instance, and either an alarm or query trigger
• dynamic action parameters must set both field and path fields