Skip to content

docs: clarify that .github/ deployed files should be committed #290

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danielmeppiel merged 3 commits into from
Mar 13, 2026
Merged

docs: clarify that .github/ deployed files should be committed #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17d45dd
docs: clarify that .github/ deployed files should be committed
danielmeppiel Mar 13, 2026
c52fbba
Potential fix for pull request finding
danielmeppiel Mar 13, 2026
97a7a77
fix: use git status --porcelain for CI drift checks
danielmeppiel Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/src/content/docs/getting-started/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,14 @@ apm install github/awesome-copilot/skills/review-and-refactor
```

**What to commit:**
- `apm.yml` and `apm.lock.yaml` -- version-controlled, shared with the team.
- `apm_modules/` -- add to `.gitignore`. Rebuilt from the lockfile on install.
- `apm.yml` and `apm.lock.yaml` — version-controlled, shared with the team.
- `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context immediately after cloning, before they run `apm install` to sync and regenerate files.
- `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale for Claude Code users: committed files give instant context on clone, while `apm install` remains the way to refresh them from `apm.yml`.
- `apm_modules/` — add to `.gitignore`. Rebuilt from the lockfile on install.

:::tip[Keeping deployed files in sync]
When you update `apm.yml`, re-run `apm install` and commit the changed `.github/` and `.claude/` files. A [CI drift check](../../integrations/ci-cd/#verify-deployed-primitives) catches stale files automatically.
:::

:::note[Using Cursor, Codex, or Gemini?]
These tools use different configuration formats. Run `apm compile` after installing to generate their native files. See the [Compilation guide](../../guides/compilation/) for details.
Expand Down
23 changes: 21 additions & 2 deletions docs/src/content/docs/integrations/ci-cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,30 @@ If your project uses `apm compile` to target tools like Cursor, Codex, or Gemini
- name: Check for drift
run: |
apm compile
git diff --exit-code AGENTS.md CLAUDE.md || \
(echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1)
if [ -n "$(git status --porcelain -- AGENTS.md CLAUDE.md)" ]; then
echo "Compiled output is out of date. Run 'apm compile' locally and commit."
exit 1
fi
```

This step is not needed if your team only uses GitHub Copilot and Claude, which read deployed primitives natively.

### Verify Deployed Primitives

To ensure `.github/` and `.claude/` integration files stay in sync with `apm.yml`, add a drift check:

```yaml
- name: Check APM integration drift
run: |
apm install
if [ -n "$(git status --porcelain -- .github/ .claude/)" ]; then
echo "APM integration files are out of date. Run 'apm install' and commit."
exit 1
fi
```

This catches cases where a developer updates `apm.yml` but forgets to re-run `apm install`.

## Azure Pipelines

```yaml
Expand Down Expand Up @@ -153,5 +171,6 @@ See the [Pack & Distribute guide](../../guides/pack-distribute/) for the full wo

- **Pin APM version** in CI to avoid unexpected changes: `pip install apm-cli==0.7.7`
- **Commit `apm.lock.yaml`** so CI resolves the same dependency versions as local development
- **Commit `.github/` and `.claude/` deployed files** so contributors and cloud-based Copilot get agent context without running `apm install`
- **If using `apm compile`** (for Cursor, Codex, Gemini), run it in CI and fail the build if the output differs from what's committed
- **Use `GITHUB_APM_PAT`** for private dependencies; never use the default `GITHUB_TOKEN` for cross-repo access
Loading