Bringing an aging GitHub Action up to standard with Copilot agents

Small utilities often start as quick fixes that grow into essential parts of a workflow. The validate-file-exists GitHub Action was exactly that: a useful tool for enforcing repository quality gates that had accumulated inconsistencies over time. Missing documentation, inconsistent package metadata, and gaps in input validation made it a good candidate for cleanup using GitHub Copilot coding agent.

The project—a TypeScript-based action that fails workflows when required files are absent—needed more than manual fixes. By preparing the repository with the right context and environment configuration, the coding agent could handle the heavy lifting autonomously.

Configuring Copilot for repository context

Before delegating tasks, the repository required proper setup for the agent. Two files make the difference between generic assistance and targeted work.

Repository custom instructions

The existing copilot-instructions.md lacked substantive guidance—no repository overview, no contribution expectations. Following documented best practices for adding custom instructions, the file was rewritten to include:

  • A concise summary of the action's purpose
  • Contribution guidelines covering build, format, lint, and test commands
  • A project structure overview
  • Key technical principles: strict TypeScript, TSDoc comments, and focused functions

These instructions align Copilot's behavior with the project's conventions and quality bars.

Environment setup steps

The coding agent needs its own working environment. Creating .github/copilot-setup-steps.yaml provides exactly that—a configuration that checks out the code, provisions Node.js, and installs dependencies. One adjustment sourced the Node version from the .node-version file to remain consistent with the existing CI workflow.

name: Setup environment
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version-file: '.node-version'
      cache: 'npm'
  - run: npm ci

With these two configuration files in place, the agent can install dependencies, run builds, and execute linting and tests—matching the checks in the project's CI pipeline.

Initiating the remediation cycle

With the groundwork complete, the next step was identifying what needed fixing. Using Copilot Chat in VS Code, a single query asked for a prioritized technical debt assessment with actionable next steps:

"What technical debt exists in this project? Please give me a prioritized list of areas we need to focus on. I would like to create a GitHub Issue with the top 2 or 3 items. Please include a brief problem statement, a set of acceptance criteria, and pointers on what files need to be added/updated."

The exploration surfaced three concrete issues in minutes:

  • Inconsistent package metadata
  • README usage examples that referenced wrong input names
  • No validation for empty or malformed inputs

Following best practices for well-scoped issues, the request specified problem statements and acceptance criteria. A GitHub issue was then created and assigned to the coding agent.

Agent-driven execution loop

Once assigned, Copilot operated asynchronously on the issue. It explored the codebase, built a plan from its findings, and then executed the following:

  • Corrected package.json metadata fields including name, description, URLs, and author
  • Updated README examples to match actual code behavior
  • Added input validation rejecting empty strings, whitespace-only values, and comma-only input
  • Wrote four edge-case tests covering the new validation logic
  • Verified linting, formatting, and test coverage remained intact
  • Documented completed work in the pull request body

The entire process finished in roughly eleven minutes. The autonomy matters here—delegating freed the developer to explain the workflow to an audience, rather than micro-managing each change.

Handling CI failures through iteration

The standard quality checks passed, but an additional Markdown linting rule existed in the CI pipeline that wasn't included in the custom instructions. The workflow failed. This created an opportunity to demonstrate iterative collaboration through pull request comments.

Posting the failure log and asking Copilot to resolve the Markdown linting error prompted another commit. The agent updated the code, pushed a fix, and the pull request succeeded—all while the developer continued other work.

Extending the pattern to UI work

The same methodology applies to other project types. A separate Trend Radar visualisation app built with Next.js and Tailwind CSS benefited from a similar agentic workflow. The problem there: users had to manually type point data into forms when they should be able to interact directly with the visualization.

The workflow followed the now-familiar pattern—a GitHub issue defining UX requirements and acceptance criteria, assigned to the coding agent. Over several pull request iterations, the agent:

  • Implemented click-to-place functionality for radar points
  • Added drag-and-drop to reposition points across categories
  • Wrote unit tests covering the new interactions
  • Captured browser screenshots attached to the pull request
  • Annotated the PR with progress summaries

The visual validation capability comes from Playwright, now installed by default with the coding agent. This enables verifying that interface changes actually behave as intended.

Structuring repositories for agent collaboration

Several configuration patterns made this productive session possible:

  • Write clear, concise copilot-instructions.md content to steer the agent toward project conventions
  • Maintain copilot-setup-steps.yaml so the agent's environment matches project requirements
  • Create well-scoped issues with acceptance criteria for autonomous execution
  • Let the agent's built-in browser tooling capture visual evidence for UI tasks
  • Bring existing projects into scope—retrofitting old codebases with validation and tests works just as well as greenfield work

The technical debt that accumulates in small utilities doesn't require dedicated cleanup sprints. A properly configured repository with the right context files lets Copilot coding agent handle the unglamorous remediation work while developers focus on design decisions and review.