#Repository Source Is Not Visible

#Problem Description

After creating a repository ConfigMap for artifacthub-shim, the expected Task, Pipeline, or StepAction does not appear in the shim API, DevOps Hub UI, or Tekton hub resolver results.

#Error Manifestation

Common symptoms include:

• The package detail API returns 404.
• The package is missing from /api/v1/packages/search.
• The UI list does not show the resource.
• The repository ConfigMap has RepositorySourceInvalid or RepositorySourceDegraded Events.
• The TaskRun or PipelineRun using resolver: hub cannot resolve the referenced resource.

#Root Cause Analysis

The usual causes are:

1. The ConfigMap is not watched by artifacthub-shim.
2. repository.yaml is missing or invalid.
3. Another source uses the same repository name.
4. The request uses a legacy catalog alias that was disabled by a conflict.
5. The referenced Secret is missing or contains unsupported credential keys.
6. Git clone or fetch fails.
7. The catalog directory layout is invalid.
8. The package or version is disabled.

artifacthub-shim isolates source failures across ConfigMaps. If one entry in a ConfigMap is invalid, all repository entries in that ConfigMap are rejected, but repositories declared by other ConfigMaps remain isolated. For transient Git failures, the previous last-good source shard may continue to be served if one exists.

#Troubleshooting

#1. Check shim readiness

kubectl get deployment artifacthub-shim -n artifacthub-shim-system

If the Deployment is unavailable or restarting, check the pod logs before investigating a single repository.

#2. Check the repository ConfigMap label and data key

The ConfigMap must have the repository label and repository.yaml data key.

kubectl get configmap <configmap-name> \
  -n artifacthub-shim-system \
  -o yaml

Required shape:

metadata:
  labels:
    artifacthub-shim.alauda.io/repository: "true"
data:
  repository.yaml: |
    gitRepositories:
      - url: https://git.example.com/team-a/tekton-catalog.git
        revision: main
        repositories:
          - name: team-a-tasks
            kind: task
            path: task

If the label is missing or has a value other than "true", the ConfigMap is ignored.

For repository ConfigMaps outside the primary watched namespace, also verify:

• config.scopedConfigMapSources.enabled is true for namespace, project, or explicit Namespace allowlist scopes.
• config.globalConfigMapSources.enabled is true for repository-visibility: "global", and the source Namespace is included in config.globalConfigMapSources.allowedNamespaces when that list is non-empty.
• Project scope owner Namespaces have a non-empty cpaas.io/project label.
• At least one valid Namespace listed by artifacthub-shim.alauda.io/repository-visible-namespaces exists. Missing entries are ignored until the Namespace is created.
• The artifacthub-shim ServiceAccount has chart-rendered cluster-wide read RBAC for repository ConfigMaps, Namespaces, referenced Secrets, and Events.

#3. Inspect repository ConfigMap Events

Check recent Events on the repository ConfigMap:

kubectl describe configmap <configmap-name> \
  -n artifacthub-shim-system

You can also list Events directly:

kubectl get events -n artifacthub-shim-system \
  --field-selector involvedObject.kind=ConfigMap,involvedObject.name=<configmap-name>

For persistent Warning states, artifacthub-shim records the Warning again on each refresh or resource sync attempt. Kubernetes usually keeps this as one Event with an increasing count and updated last timestamp. If event TTL cleanup removes the previous Event, the next attempt can create it again.

Events are still historical. A previous RepositoryConfigInvalid or RepositorySourceInvalid entry can remain visible until Kubernetes event TTL cleanup, even after the configuration has been fixed. Use the latest RepositoryConfigAccepted or RepositorySourceReady Event together with /api/v1/snapshot source statuses to determine the current state.

Common Event reasons:

Common reason message patterns:

#4. Validate repository name uniqueness

Repository names are global catalog identifiers. When more than one source declares the same repository.yaml.gitRepositories[].repositories[].name, the conflict is resolved by source priority (highest to lowest):

1. The built-in default catalog shipped with artifacthub-shim.
2. ConfigMap sources registered in the install namespace (artifacthub-shim-system by default).
3. ConfigMap sources registered in any other Namespace.

The highest-priority source wins and stays indexed; lower-priority duplicates are marked Invalid. When multiple sources share the same priority, the winner is the lexically first namespace/configmap/kind/repository identity. This keeps takeover deterministic and lets the next valid source take over after the winner is deleted.

Find all repository ConfigMaps:

kubectl get configmap --all-namespaces \
  -l artifacthub-shim.alauda.io/repository=true \
  -o yaml

If two entries at the same priority use the same name, rename one of them and update any hub resolver references that use the old catalog name.

#5. Validate optional paths and legacy aliases

If a migrated source has optional: true, a missing or empty path is not a failure. The source is reported as Ready with packages=0 and versions=0. This is expected for generated entries such as a Pipeline source in a legacy catalog that only contained Tasks.

If optional is omitted or set to false, a missing path remains invalid. Use optional: true only for intentional migration compatibility, not to hide unexpected layout errors.

Check legacyCatalogAliases only when you need to keep old resolver catalog values working. Aliases are scoped by kind. Conflicting aliases are omitted from lookup and reported as non-fatal warnings; use the canonical repository names until the conflict is removed.

#6. Check Secret keys

If a repository.yaml.gitRepositories[] entry uses credentialRef, verify the Secret exists in the same namespace as the repository ConfigMap:

kubectl get secret <secret-name> -n artifacthub-shim-system

Supported keys are:

• username
• password
• token
• sshPrivateKey
• ssh-privatekey
• known_hosts
• ca.crt

Do not place credentials in the ConfigMap.

#7. Check API pod logs

kubectl logs -n artifacthub-shim-system \
  deployment/artifacthub-shim \
  --tail=200

Look for Git clone errors, YAML parse errors, manifest identity errors, or content size limit errors.

#8. Check disabled package rules

If the source is Ready but a specific package is missing, check disabledPackages in the repository ConfigMap and config.disabledPackages in the chart values.

Repository-local example:

disabledPackages:
  - name: run-script
    versions:
      - "0.1"

A disabled package or version is intentionally removed from list, search, detail, and resolver responses.

#Related Content

• Configure Custom Git Repositories
• Disable Catalog Packages
• Hub Resolver Cannot Resolve a Resource