Repositories and engineering evidence¶

Repository evidence connects software delivery activity with the project work it supports. A merged change, successful build or successful deployment can help explain why a work item is ready for review. An imported issue can provide useful context. The team still needs to identify the relevant work and complete its required review or acceptance.

Availability: These steps follow the inspected WorkOS Final Screens. The frontend remains a preview with sample records and local controls that do not connect to your provider or save changes. Connected provider search, saving, evidence refresh, permissions and deployment have not been verified. The rules and limitations below come from the inspected implementation. A sample success message is not confirmation that a repository was connected or evidence was saved.

Start with project setup, execution and completion requirements, and deliverables, milestones and formal reviews. This guide explains how repository activity supports those records.

Understand the four decisions¶

For managers, the value is traceability: people can connect a delivery claim with its supporting activity. For executives, an evidence count is not a measure of delivered business value. Several records may support one task, one record may support several tasks, and some records may still need attribution. Neither a count nor a successful build establishes readiness, regulatory compliance, customer acceptance or financial benefit.

Before you begin¶

Confirm the organisation, project and source repository. Viewing repositories and provider choices requires project-viewing permission. Linking, changing settings, requesting sync, removing a link, assigning evidence and recording evidence acceptance require repository-management permission. Project ownership, participation or access to the external repository alone does not grant that permission.

Ask the organisation's administrator or integration support contact to confirm that the intended provider connection is ready. The current providers are GitHub and Azure DevOps. A provider appearing available means connection settings exist; it does not prove that the credentials still work or that every repository is accessible.

Choose repositories and evidence that the project's permitted readers are allowed to see. Imported titles and source links can reveal information about the external work. Access to Zerohive does not itself grant access to the source provider, and provider access does not grant project access.

Link a repository¶

1. Open the selected project's Repositories view and choose Link repository.
2. Choose the Provider. Use the configured GitHub or Azure DevOps connection.
3. Use Search repository and select the intended result. Confirm the repository's organisation or project as well as its name; similar names can refer to different sources.
4. Check the loaded Repository name and Source record. Keep the identity supplied by the lookup. The source record is an identifier, which may differ from a human-readable repository path.
5. Select the intended Default branch from the branch choices for that repository.
6. Choose the Sync mode, then select Link repository. The intended choices are Manual and Webhook. Confirm that the saved repository appears in the project list once connected saving is available.

Linking saves configuration. It does not register a provider webhook, fetch historical activity, verify branch protection, assign an integration owner or prove a connection is healthy. The branch is recorded context: the inspected importer and completion checks do not restrict evidence to that branch. Agree any required branch and environment checks with the responsible reviewers.

If search finds nothing, check the provider, name and connection with support. Repository and branch lists can be incomplete; GitHub lookup currently considers only the first 100 returned entries before applying the search. A missing search result does not prove the repository or branch does not exist. Do not substitute a similarly named repository to get past the empty result.

If saving reports a duplicate or fails after submission, refresh the project list and compare the existing link before submitting again. Names can be up to 256 characters; default branches are stored within 128 characters. An existing link's normal settings update changes branch and sync preference, not the provider, repository identity or name.

Read the repository list¶

The intended Repositories view offers repository/evidence search, provider and sync-state filters, an evidence count, an unattributed count and actions for each repository. Expand or inspect its evidence to understand what has actually arrived. Filters describe the intended screen; the current backend returns the project's list together rather than running those searches on the server.

The inspected sync request records queued status and activity, but no worker that fetches repository history was found in this runtime. It also clears recorded failure details while keeping the previous sync time. Do not treat disappearance of an error after requesting sync as proof that the error was repaired.

The displayed last-sync time comes from the imported event's occurrence time. An older delivery can move that time backwards. It is not a reliable timestamp for the most recent connection check or receipt. Use the event itself and the integration support team's delivery evidence when diagnosing delays.

Know which evidence can arrive¶

Open or rejected pull requests, failed builds and failed deployments do not become successful completion evidence. This evidence list therefore cannot be used as a complete failure history of the external system. Standalone commits and code-review comments are not imported evidence types in this path, even where a sample screen shows a commit or a provider can send review activity.

Records can include a title, source link, event date, actor and details relevant to their type. Some fields are legitimately absent. In particular, the stored deployment evidence does not retain the incoming branch or commit, and merged-pull-request evidence does not retain a commit value. Do not fill missing values with the repository's default branch or assume a sample value is verified.

If the actor has not been mapped to a local user, evidence can arrive without an identified person. That is not proof that the person viewing the record performed the external work. The source provider remains the place to examine detailed build, deployment or change history, subject to its own access controls.

Assign imported evidence to project work¶

The Final Screens' Add engineering evidence flow attributes an existing imported record. It does not upload a certificate, create a manual evidence record or edit the imported event.

1. In Repositories, find the imported record that needs assignment and choose Attribute evidence.
2. Review the read-only evidence type, title, occurrence time and available source details. Confirm that this is the event you intend to use.
3. Choose the kind of project record it supports: a work item, deliverable or milestone.
4. Search or filter the project records and select the correct one. Check its title and context, especially where names repeat.
5. Submit Attribute evidence, then refresh and confirm that the intended subject appears on the evidence record.
6. Repeat for another subject if the same evidence genuinely supports more than one record. Each submission selects one subject; repeating the same association does not create another copy of it.

Both the evidence's repository link and the selected subject must belong to the project. Attribution to a work item reevaluates that item's completion requirements. Depending on its policy and existing approval, the result may change readiness or completion; inspect the resulting work state. Assigning evidence to a deliverable or milestone does not by itself accept that output or approve the checkpoint.

The current preview offers attribution fields for sample imported evidence and project records. It does not save an association or upload a file. Use the intended imported-record flow when connected implementation is available, and confirm the saved record before relying on it.

Automatic attribution can also occur during import. Where the project has exactly one candidate subject, the current resolver may assign evidence to it. That selection is not a human judgement about relevance. Always review the resulting association; do not assume the system interpreted a title, branch name or issue number correctly.

Interpret policy and acceptance carefully¶

A policy badge on an evidence row summarises requirements for the work items associated with it, using their combined evidence. It does not certify that this single record satisfies all those requirements. A record associated only with deliverables or milestones has no work-item policy to evaluate; Not applicable is different from an approval.

The current repository summary has known differences from the actual completion checks, including missing required-deliverable handling and omission of formal review requirements. A satisfied repository badge can therefore coexist with unfinished work. Confirm the work item's requirements, its review outcome and any required accepted outputs before making a delivery decision. See execution and review.

Repository-evidence acceptance is a separate backend capability. It requires an authenticated authorised person, evidence already assigned to project work, a work reference and a proof reference. It records that person's acceptance and emits a contribution-evidence event. Importing or attributing evidence alone does not emit that acceptance contribution. Acceptance does not award a documented score or guarantee that any downstream evaluation has completed.

No matching acceptance screen and connected end-to-end journey were verified in this intake, so this guide does not invent click steps for it. The current repository list also omits the stored acceptance person, time and proof fields. A normal list refresh cannot confirm all of those acceptance details. Ask an authorised support contact to verify an uncertain acceptance rather than repeatedly submitting it. Acceptance can be overwritten by another accepted request; it is not an immutable approval of a particular revision.

Correct an attribution or remove a repository¶

The backend supports removing one association between evidence and a work item, deliverable or milestone. A complete matching removal-screen sequence was not verified. Ask an authorised repository manager or support contact to correct a mistaken association using the available supported interface, then confirm the remaining subjects and affected work state.

Removing an association leaves the imported record and its stored acceptance intact. It can reevaluate an affected work item, but does not automatically reopen an already completed item. Reviewers must address any completion decision that depended on incorrect evidence.

The repository row offers Unlink repository. Removal is permitted only when no imported evidence references that link. If the blocked dialog appears, Review evidence can help identify the records and Close returns without removing the link. The current screen's suggestion to remove or reassign associations is insufficient: even unattributed evidence still blocks repository removal. No ordinary evidence-delete or move-to-another-repository operation was found. Escalate the retention/removal decision to support; do not promise that reassignment will unblock it.

Removing an empty link does not delete the external repository or establish that provider-side delivery settings have been removed. The integration owner must separately confirm any external configuration changes.

Troubleshooting and responsible use¶

Give support the workspace, project, repository name, evidence title or identifier, approximate time and observed result. Share only information the support recipient may access. Avoid sending credentials, private source files or customer content when a reference is sufficient.

Managers should agree who maintains provider access, who checks evidence relevance, who reviews completed work and who handles exceptions. Executives should ask whether a readiness claim refers to imported activity, completed work, accepted outputs or a formal decision. This feature does not establish a separate price, automatic provider provisioning, a retention promise or a guaranteed time for incoming evidence.