Using IronBarcode with GitHub Copilot, in the IDE and on GitHub

Updated: September 21, 2026

IronBarcode projects fail on GitHub runners over missing native dependencies and missing license keys. The Linux build needs a platform package carrying those dependencies, and every barcode call needs a key. Copilot meets both when it builds your project on GitHub, and failing tests it cannot account for send it hunting a bug that was never in the code.

None of this requires leaving your IDE. GitHub Copilot is available in Visual Studio, VS Code, and JetBrains, so your existing solution, project references, NuGet settings, and build pipeline stay where they are.

No Copilot plugin ships for IronBarcode, and there is no setting to switch on. Everything Copilot knows about barcodes comes out of the repository, from the conventions you commit there and the environment you hand it. The assistant handles a crop region or a margin change inside one file. Briefed well enough, it can stamp barcodes onto a PDF or fix a failing scan on GitHub without you watching.

IronBarcode's own machine learning detection is a separate feature with its own confidence threshold example, and nothing below touches it.

Quickstart

Install with NuGet

PM > Install-Package BarCode

Install-Package BarCode

Install IronBarcode by running the command above in the NuGet Package Manager Console, or search for the package in the NuGet Package Manager.

Open your solution in whichever IDE you already use, and put this to Copilot Chat with the project in context. #solution is the Visual Studio reference that scopes a request to the whole solution. In VS Code, use #codebase instead.

#solution Add the BarCode package to this project. In Program.cs, copy an
existing invoice PDF, then stamp a Code 128 barcode of the invoice number onto
the first page of the copy with StampToExistingPdfPage, which writes in place.
Take the license key from IRONBARCODE_LICENSE_KEY, never inline. Build, and fix
anything that breaks.

#solution Add the BarCode package to this project. In Program.cs, copy an
existing invoice PDF, then stamp a Code 128 barcode of the invoice number onto
the first page of the copy with StampToExistingPdfPage, which writes in place.
Take the license key from IRONBARCODE_LICENSE_KEY, never inline. Build, and fix
anything that breaks.

Text

The example needs two calls, one to create the symbol and one to stamp it onto the page you name, and the stamp barcodes on PDFs guide covers the page index and placement arguments. You should see both in the suggestion. Alternatively, you can send the same request to the assistant on GitHub, which will run unattended on a branch and deliver a pull request. That changes what you need to prepare.

Two safety points before you start. First, keep license keys out of prompts and commits by storing them in configuration, environment variables, or repository secrets as described in the license key guide. Second, remember that write access lets Copilot open real pull requests, so branch protection and human review remain your main safeguard.

Minimal Workflow in 5 Steps

Download the C# barcode library from NuGet
Commit .github/copilot-instructions.md with the project's IronBarcode conventions
Use inline chat for small edits and the editor's multi-file mode for larger ones
For unsupervised work, file a detailed issue and hand it to the assistant on GitHub
Review the pull request, checking every API name against the API reference

Where does Copilot fit a project already in Visual Studio?

Copilot operates at three levels, and the scope widens at each one.

Inline completions and chat live in the editor. They are best for changes that can be described in a single statement within one file, such as switching symbology, adding a margin, or limiting a reader to one format. You describe the change, review the resulting diff, and choose to accept or discard it.

The editor's multi-file mode takes on changes that span several files. It selects the files, runs terminal commands, reviews results, and iterates on errors. Use it for migrations and refactoring.

The assistant on GitHub manages tasks you do not wish to supervise directly. You provide instructions through an issue, and later receive a branch and pull request. Nothing bound to the editor can do that, so most of what follows concerns that mode.

All three read documentation well. Direct one to the API reference, ask which BarcodeReaderOptions your project leaves at their defaults, and the answer comes back without manual assembly.

How do you commit conventions every surface follows?

Custom instructions live in the repository, so they shape IDE suggestions and unattended runs alike. Write them once and stop repeating them in prompts.

Use .github/copilot-instructions.md. It is the repository-wide file, and it applies in the IDEs, on GitHub, and in Copilot code review. If IronBarcode is the standard across more than one repository, set the rules once as organization custom instructions instead. An organization owner on a Copilot Business or Enterprise plan can do that, and those instructions reach Copilot Chat on github.com, Copilot code review, and unattended work there. Copilot also reads AGENTS.md anywhere in the tree, with the nearest file winning, plus a single CLAUDE.md or GEMINI.md at the root. If your repository already keeps barcode rules in AGENTS.md for another tool, Copilot honors them and you do not need a second copy.

# Copilot instructions

## Barcodes

- IronBarcode is this repository's barcode library. The package is BarCode, the
  namespace is IronBarCode, and no competing package may be introduced.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
  Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- The BarCode version is pinned in Directory.Packages.props. Changing it is its
  own pull request, never a side effect of another change.
- License keys come from configuration or IRONBARCODE_LICENSE_KEY, and never
  appear in source, in a commit, or in a pull request description.
- Cite a documentation page for any IronBarcode member you are not certain of.
  Saying you are unsure is an acceptable answer.

## Testing

- A barcode change is not complete until the generated barcode has been decoded
  and compared with the value that was written.
- Assert on decoded values and formats. Never compare image bytes.

## Pull requests

- Say which IronBarcode APIs the change introduces, and link the page for each.
- If the barcode tests fail, check the runner environment before changing code
  that the issue did not ask you to touch.

# Copilot instructions

## Barcodes

- IronBarcode is this repository's barcode library. The package is BarCode, the
  namespace is IronBarCode, and no competing package may be introduced.
- Reference: https://ironsoftware.com/barcode/csharp/llms.txt
  Skill file: https://ironsoftware.com/barcode/csharp/skill.md
- The BarCode version is pinned in Directory.Packages.props. Changing it is its
  own pull request, never a side effect of another change.
- License keys come from configuration or IRONBARCODE_LICENSE_KEY, and never
  appear in source, in a commit, or in a pull request description.
- Cite a documentation page for any IronBarcode member you are not certain of.
  Saying you are unsure is an acceptable answer.

## Testing

- A barcode change is not complete until the generated barcode has been decoded
  and compared with the value that was written.
- Assert on decoded values and formats. Never compare image bytes.

## Pull requests

- Say which IronBarcode APIs the change introduces, and link the page for each.
- If the barcode tests fail, check the runner environment before changing code
  that the issue did not ask you to touch.

Text

Models tend to provide confident answers rather than acknowledge uncertainty, so a call like BarcodeScanner.DecodeImageFile() may appear valid until the build fails. Permitting the model to stop when unsure costs nothing and keeps invented APIs out of the diff.

For more specific rules, place a file in .github/instructions/ named something.instructions.md. Use an applyTo: glob in its frontmatter to target only matching files. For example, scoping barcode rules to **/Services/** prevents them from affecting unrelated requests.

What makes an issue the assistant can act on?

You write the issue, then assign it. The body is the assistant's entire brief, and no one is around to answer follow-up questions once it starts.

Here is one filed in thirty seconds.

Title: Barcodes not scanning

Some labels don't scan. Can we fix it?

Title: Barcodes not scanning

Some labels don't scan. Can we fix it?

Text

This issue provides nothing concrete: no file reference, no indication of which labels are affected, no definition of correct behavior, and no failing sample. The assistant will guess, and it may fix the wrong thing.

Here is the same fault written out the way a teammate would want it.

Title: Returns labels fail to scan at the depot; tracking numbers with lowercase letters

**Files:** Services/LabelService.cs, Services/ScanService.cs
**BarCode version:** as pinned in Directory.Packages.props
**Framework:** .NET 8

**Expected:** Every returns label is a Code 128 barcode, 400 by 120 px with the
value printed below, and reads back to the exact tracking number.

**Actual:** Labels for tracking numbers containing lowercase letters do not read
at the depot. Samples are in TestData/returns-failing/. The same labels read
correctly with IronBarcode on a developer machine. No exception is thrown.

**Constraints:** Do not change the symbology or the public signature of
LabelService.RenderPng. No new packages.

**Acceptance:** Existing tests pass, plus a new round-trip test covering every
file in TestData/returns-failing/ and a lowercase tracking number.

Title: Returns labels fail to scan at the depot; tracking numbers with lowercase letters

**Files:** Services/LabelService.cs, Services/ScanService.cs
**BarCode version:** as pinned in Directory.Packages.props
**Framework:** .NET 8

**Expected:** Every returns label is a Code 128 barcode, 400 by 120 px with the
value printed below, and reads back to the exact tracking number.

**Actual:** Labels for tracking numbers containing lowercase letters do not read
at the depot. Samples are in TestData/returns-failing/. The same labels read
correctly with IronBarcode on a developer machine. No exception is thrown.

**Constraints:** Do not change the symbology or the public signature of
LabelService.RenderPng. No new packages.

**Acceptance:** Existing tests pass, plus a new round-trip test covering every
file in TestData/returns-failing/ and a lowercase tracking number.

Text

A well-defined issue includes six elements: relevant files, framework and library versions, specific expected output, actual behavior (including what does not occur), clear constraints, and defined acceptance criteria.

The line about the labels decoding correctly with IronBarcode tells the assistant the barcodes are valid and the fault lies between the printed image and the depot scanners, which removes a large area from the search. A sample folder turns a vague complaint into data the assistant can test against.

After assignment, the assistant goes off and comes back for review. You check the diff rather than watching it work.

Why do the assistant's tests fail on an IronBarcode project?

The assistant builds and tests on GitHub in an ephemeral environment powered by GitHub Actions, on an Ubuntu runner unless you have pointed it at a Windows or self-hosted one. Many projects need only the source and a package restore there. An IronBarcode project needs two extras. It needs the platform package whose native dependencies match that runner, and it needs a license key. Without either, every test that writes or reads a barcode fails, regardless of what the assistant changed. Because IronBarcode throws LicensingException instead of watermarking, a missing key looks like a broken test, not a missing secret.

The assistant blames its own change and starts editing code that was already correct, and it can keep doing that for a long time.

Prevent it by preparing the environment in .github/workflows/copilot-setup-steps.yml. Rather than adapting a workflow from elsewhere, describe what the runner needs and let Copilot write the file. Two requirements are easy to miss, so put both in the request. The job has to be named copilot-setup-steps. And the workflow only runs once the file exists on your default branch.

#project Write .github/workflows/copilot-setup-steps.yml for this repository.

The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.

Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronBarcode needs on Ubuntu, then restore packages.

For those native dependencies, read
https://ironsoftware.com/barcode/csharp/get-started/linux/ and use what it lists
for Ubuntu rather than a list from memory. Add a comment saying the list can
change between releases.

Give me the finished YAML and nothing else.

#project Write .github/workflows/copilot-setup-steps.yml for this repository.

The job must be named copilot-setup-steps exactly, or it is ignored. Trigger it
manually, and on push and pull request limited to that one file path.

Run it on ubuntu-latest with read access to repository contents. Check out the
repository, set up the .NET SDK for the version this project targets, install
the native dependencies IronBarcode needs on Ubuntu, then restore packages.

For those native dependencies, read
https://ironsoftware.com/barcode/csharp/get-started/linux/ and use what it lists
for Ubuntu rather than a list from memory. Add a comment saying the list can
change between releases.

Give me the finished YAML and nothing else.

Text

Read the file back before you commit it. The job name has to match exactly, the SDK version has to match your project, and the dependency step has to trace to the Linux guide rather than a guess. Merge it to your default branch, because the workflow does not run from a feature branch.

Two points determine whether this works.

First, the assistant does not automatically receive your license key. It cannot access Actions, Codespaces, or Dependabot secrets. Store the key separately: in repository or organization settings, open Secrets and variables, select the Agents tab, and add IRONBARCODE_LICENSE_KEY. Agents secrets reach the assistant as environment variables, including inside copilot-setup-steps.yml.

Second, Copilot keeps going when a setup step fails. It skips the remaining steps and begins work in whatever state the runner is in. A dependency install that failed quietly then looks exactly like a code bug. Trigger the workflow by hand from the Actions tab once before you depend on it.

Tips: If barcode tests fail on a pull request, verify the runner environment and license secret before assigning the issue to code changes. Refer to the Linux setup and NuGet packages guides for platform requirements instead of relying on memory.

What should you check before merging?

Review the assistant's pull request as you would a teammate's branch. Copilot code review can make a first pass over the output and catch mechanical problems before a person reads it.

For IronBarcode changes, confirm three things before you approve:

Every API name used appears in the documentation: pay particular attention to encoding enums, where a plausible fake can differ by a single capital letter.
Every barcode the change produces still reads back: neither a passing build nor a code review proves that a label scans.
The change stayed inside the constraints the issue set: given room, the assistant often treats a bug fix as permission to change symbology or rework the calling pattern.

Make round-trip tests a standard request in the same pull request.

/tests Ensure tests are included in the same pull request, not in a subsequent one. A
barcode change without accompanying tests is not reviewable.

Every barcode generated by the service must read back to the value and format it
went in as. An image without a barcode should return no results rather than
throw an exception. All existing samples in TestData/ must read as expected.

Assert on decoded values, not image bytes, and say in the PR description which
of these cases were already covered prior to your change.

/tests Ensure tests are included in the same pull request, not in a subsequent one. A
barcode change without accompanying tests is not reviewable.

Every barcode generated by the service must read back to the value and format it
went in as. An image without a barcode should return no results rather than
throw an exception. All existing samples in TestData/ must read as expected.

Assert on decoded values, not image bytes, and say in the PR description which
of these cases were already covered prior to your change.

Text

Avoiding byte comparisons prevents flaky tests, as image encoders may produce different bytes across versions and platforms even when the decoded barcode remains identical.

Is the fault in the code or in the scan?

Failed reads are the most common question IronBarcode users ask, and three causes account for nearly all of them. The formats were never declared, so the reader searched every symbology it knows. The symbol occupies a fraction of a large photo. Or the capture itself is poor, whether blurred, angled, or washed out. All three are reader-side, so say so in the request.

#project Use the editor's multi-file mode for this scenario, as it spans the reader and the test data.

Warehouse photos in TestData/depot/ come back empty from ScanService, while the
same physical labels read fine on a handheld scanner.

Explain the cause before making any changes. The fix should be applied
only in BarcodeReaderOptions, so expected formats, crop area, speed, and
image filters are in scope, while LabelService.cs is not.

Conclude by reporting how many of those photos were readable before your change
and how many are readable after.

#project Use the editor's multi-file mode for this scenario, as it spans the reader and the test data.

Warehouse photos in TestData/depot/ come back empty from ScanService, while the
same physical labels read fine on a handheld scanner.

Explain the cause before making any changes. The fix should be applied
only in BarcodeReaderOptions, so expected formats, crop area, speed, and
image filters are in scope, while LabelService.cs is not.

Conclude by reporting how many of those photos were readable before your change
and how many are readable after.

Text

A diagnosis gives you reasoning to check rather than an unexplained edit to untangle. Fence the change to the reader as well, or the assistant will solve a scanning problem by reprinting every label. Three documentation pages cover the settings it should be reaching for, on speed, crop region, and image correction.

The earlier section covers the other case. When code reads correctly on your machine but fails in a container or on a runner, the code is rarely at fault. Paste the full exception, not a summary, and direct the assistant to the platform package and Dockerfile instead of the application. A missing native library belongs to the image, not the source. Left unconstrained, it may add a try/catch that hides the failure without fixing it.

What keeps working when nobody is watching?

Set up two things first. Instructions in .github/copilot-instructions.md guide the assistant on an overnight branch as they guide your IDE during the day. A copilot-setup-steps.yml that installs IronBarcode's native dependencies, together with the key in Agents secrets, keeps it from debugging code that was never broken. Everything else is ordinary assistant use, and it goes better with those two in place.

The review is the same whether it happens ten seconds after a completion or the morning after a pull request, and it is scored against the fixed bar on the AI coding assistants and agents guide. Claude Code, ChatGPT Codex, Cursor, and Google Antigravity each have dedicated guidance.

Troubleshooting

Apply a License Key in IronBarcode when a pull request comes back with every barcode test red.
Barcode Not Recognized when a label scans on your desk and not at the depot.
IronBarcode NuGet Packages to pin the package your instructions file should name.
Use IronBarcode on Linux for the native dependencies the runner has to install.

Questions?

If you have any questions, reach out to support@ironsoftware.com

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...