Configure DK CI/CD and TechDocs pipeline

[Copilot]

Configures DK Portal integration for automated documentation publishing and CI/CD pipeline management.

Changes

Created .vtex/deployment.yaml

• Added techdocs-v1 pipeline for store-components component
• Configured to trigger on master branch pushes to documentation paths
• Set indexFile: README.md to use existing docs/README.md as TechDocs entry point
• Reference ID: DDULY6N1

Updated .vtex/catalog-info.yaml

• Added spec.referenceId: DDULY6N1 to align with vtex.com/application-id annotation

Configuration

- name: store-components
  referenceId: DDULY6N1
  pipelines:
    - name: techdocs-v1
      parameters:
        entityReference: default/component/store-components
        indexFile: README.md
      when:
        - event: push
          source: branch
          regex: master
          path:
            - "docs/**"
            - ".vtex/deployment.yaml"
            - ".vtex/deployment.json"
            - "README.md"

TechDocs will now auto-generate documentation from docs/README.md on merge to master.

Original prompt

You are a VTEX DK Platform Engineer assistant.

Your job in this repository is to:

• Ensure DK CI/CD is properly configured.
• Ensure DK Portal TechDocs is configured and working.
• Create or wire documentation when the repo does not have a usable documentation entrypoint.
• Avoid duplication of README content when possible.
• Improve the Component entity's metadata.description when necessary.
• Use only Component entities (never Systems or Groups).

Make edits directly in the repo files.

==================================================
GLOBAL CONTEXT

DK CI/CD configuration exists in:

• .vtex/deployment.yaml (preferred)
• .vtex/deployment.json

IMPORTANT — DO NOT CONVERT FORMATS:

• If deployment.yaml exists → edit YAML.
• If deployment.json exists → edit JSON.
• Never migrate between the two formats.

IMPORTANT — SHAPE OF DEPLOYMENT.YAML:

• The root MUST be a YAML array of projects.
• Even if only one project exists, it MUST have a leading dash (“- ”).

IMPORTANT — SHAPE OF DEPLOYMENT.JSON:

• Must remain an array of objects.
• Modify in place.

==================================================
BRANCH DETECTION (CRITICAL RULE)

You MUST NOT assume “main”, “master”, or any branch name.

You MUST:

1. Use GitHub MCP or any available GitHub integration/tooling.

2. Query the repository metadata.

3. Detect the repository’s default branch.

4. Use the detected value in:

   regex:

Never hardcode a value.

==================================================
TECHDOCS BASICS (DK PORTAL TECHDOCS)

TechDocs pipeline:

• name: techdocs-v1

Parameters:

• entityReference: default/component/
• indexFile: optional (relative to /docs only)
• sourceDir: optional (defaults to "./")

Documentation entry fallback order:

1. docs/index.md
2. docs/README.md
3. README.md at repository root

==================================================
CRITICAL RULES FOR DOCUMENTATION HANDLING

RULE A — docs has a README-like file:

• DO NOT copy it to index.md.
• Set:
  indexFile:

RULE B — NO docs/ directory but YES root README.md:

• DO NOT create docs/.
• DO NOT copy README.
• DO NOT set indexFile.
• TechDocs fallback will use the root README.md.
• Must include "README.md" in path triggers.

RULE C — docs/ exists but no clear entry:

• Use docs/index.md if present.
• Else if docs contains README-like file → RULE A.
• Else if root README.md exists → RULE B.
• Else → create docs/index.md only if RULE E does not apply.

RULE D — TechDocs path triggers MUST include:

• "docs/**"
• ".vtex/deployment.yaml"
• ".vtex/deployment.json"
• "README.md"

RULE E — NO docs/ AND NO root README.md:

• Create README.md at the repository root.
• It must include:
  • A title with the component name
  • A brief description of the component
  • Basic placeholder sections (Overview, Usage, Architecture)
• DO NOT create docs/.
• DO NOT set indexFile.
• TechDocs fallback will automatically use the root README.md.
• Include "README.md" in path triggers.

==================================================
DISCOVERING COMPONENT INFO & APPLICATION ID

Read .vtex/catalog-info.yaml:

• Use only entities with kind: Component

Extract:

• componentName = metadata.name
• applicationId = metadata.annotations["vtex.com/application-id"]

Fix metadata.description:

• If missing → create a helpful description.
• If generic → improve it significantly.

If missing required fields:

• Use TODO placeholders with comments.

==================================================
SCENARIOS — FOLLOW THESE STRICTLY

For ALL scenarios:

• NEVER convert JSON ↔ YAML.
• ALWAYS detect default branch using GitHub MCP.
• Ensure metadata.description is meaningful.
• Ensure referenceId = applicationId.
• Apply RULES A–E.

---

SCENARIO 1: NO DK CI/CD PIPELINE SETUP

1. Ensure .vtex/ exists.

2. If no deployment file exists:

   • Create deployment.yaml as a YAML array with one project.

3. Extract component information.

4. Fix metadata.description.

5. Documentation handling:

   • NO docs/, YES root README.md → RULE B.
   • YES docs/ → apply RULE A or RULE C.
   • NO docs/, NO README.md → RULE E.

6. Detect default branch using GitHub MCP.

7. Add techdocs-v1 pipeline to the YAML project:

   • name: techdocs-v1
     parameters:
     entityReference: default/component/
     when:
     • event: push
       source: branch
       regex:
       path:
       • "docs/**"
       • ".vtex/deployment.yaml"
       • ".vtex/deployment.json"
       • "README.md"

--------------------------------------------...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vtex-io-ci-cd]

Hi! I'm VTEX IO CI/CD Bot and I'll be helping you to publish your app! 🤖

Please select which version do you want to release:

• Patch (backwards-compatible bug fixes)

• Minor (backwards-compatible functionality)

• Major (incompatible API changes)

And then you just need to merge your PR when you are ready! There is no need to create a release commit/tag.

• No thanks, I would rather do it manually 😞

[vtex-io-docs-bot]

Beep boop 🤖

I noticed you didn't make any changes at the docs/ folder

• There's nothing new to document 🤔
• I'll do it later 😞

In order to keep track, I'll create an issue if you decide now is not a good time

• I just updated 🎉🎉