GitHubs magic files
I keep coming across files in GitHub that have some mystic magic feeling to them. There’s always a small incantation to come with them: the have to have the right name, the right extension and have to be stored in the right directory. I wanted to have an overview of all these spells for myself, so here we are 😉.
Photo by Artem Maltsev on Unsplash
Overview
A list of all the magic files / links that I came across in GitHub. I also created a LinkedIn Learning Course for ~25 of these files, with more detail how to use them. You can find that course on LinkedIn Learning.
| Filename | Location | .github repo support | Description | Docs |
|---|---|---|---|---|
| CNAME | root | no | Alias for the GitHub Pages site | Docs |
| CONTRIBUTING.md | root, /docs or /.github | yes | How to contribute to a project | Guidelines |
| CODE_OF_CONDUCT.md | root, /docs or /.github | yes | Code of conduct | How to behave for this project Code of Conduct |
| CODEOWNERS | root, /docs or /.github | List of people who can make changes to the files or folders | Code owners info | |
| CITATION.cff, CITATION.md, and others | root or inst/CITATION | no | Let others know how to citate your work | cff |
| LICENSE or LICENSE.md or LICENSE.txt or LICENSE.rst | root | no | License | |
| FUNDING.yml | .github folder | yes | Display a Sponsor button in your repo and send people to platforms where they can fund your development | Docs |
| SECURITY.md | root, .github or docs folder | yes | Instructions for how to report a security vulnerability | Security policy |
| SUPPORT.md | root, .github or docs folder | yes | Tell people how to get help for the code in the repo | Docs |
| workflow.yml | workflow-templates | only available in .github repo | Store starter workflows for your organizations | Starter workflow templates |
| dependabot.yml | .github/ | Dependabot configuration file | Dependabot configuration | |
| codeql-config.yml | .github/codeql/codeql-config.yml (convention, not required) | sort of | CodeQL configuration file. Can also be stored in an external repository (hence .github repo works). If using external repo, referencing can by done by using owner/repository/filename@branch |
CodeQL config |
| secret_scanning.yml | .github/secret_scanning.yml | Secret scanning configuration file | Secret scanning | |
| README.md | .github, root, or docs directory | yes, see below | Project readme, also used on marketplace if the repo is published to the marketplace | About readme’s |
| README.md | .github/username/username | Profile readme | About readme’s | |
| README.md | organizations .github repo or .github-private repo: profile/README.md | Organization readme | Organization readme | |
| release.yml | .github | Automatically generated release notes | Automatically generated release notes | |
| workflow.yml | .github/workflows/ | Workflows | ||
| auto-assign.yml | .github/workflows/ in the demo-repository that the organization onboarding Tasks create for you |
no | Workflow that runs the Auto Assign action (pozil/auto-assign-issue) to add assignees and reviewers to issues and pull requests when they are opened. See the example file |
Learn how automation works on GitHub |
| action.yml/action.yaml | root | Configuration file for an actions repository | ||
| dependency-review-config.yml | .github | no | Dependency review configuration file | Dependency review |
| $GITHUB_STEP_SUMMARY | workflow | Job summary output in markdown | Job summary |
GitHub Copilot Files
With the rise of AI-powered development tools, GitHub Copilot has introduced its own set of magic files to help customize the AI experience for your specific repository context. These files help Copilot understand your project better and provide more relevant suggestions.
| Filename | Location | .github repo support | Description | Docs |
|---|---|---|---|---|
| copilot-instructions.md | .github/ | yes | Repository-wide custom instructions providing context and coding guidelines to GitHub Copilot for all requests in the repository | Custom Instructions |
| NAME.instructions.md | .github/instructions/ | Path-specific custom instructions that apply to files matching the applyTo glob pattern defined in the file’s YAML frontmatter. Both repository-wide and path-specific instructions are used when both apply |
Custom Instructions | |
| AGENTS.md | anywhere in the repository | Agent instructions for Copilot coding agent. The nearest file in the directory tree takes precedence. CLAUDE.md and GEMINI.md at the repository root are also supported as alternatives for other AI agents |
Custom Instructions | |
| NAME.prompt.md | .github/prompts/ | Reusable prompts for specific and repetitive tasks that can be invoked in Copilot Chat. Supports YAML frontmatter for metadata like description and which tools to use | Prompt Files | |
| NAME.agent.md | .github/agents/ | yes | Custom agent profiles with YAML frontmatter defining the agent’s name, description, available tools, and MCP server configurations. Allows creating specialized agents with tailored expertise for specific development tasks. Available on GitHub.com, VS Code, JetBrains, Eclipse, and Xcode | Custom Agents |
| managed-settings.json | .github-private/copilot/ | no | Enterprise-managed Copilot settings for clients such as Copilot CLI, VS Code, the GitHub Copilot app, and cloud agent. The older .github-private/.github/copilot/settings.json path remains supported for compatibility |
Enterprise-managed settings |
| lsp-config.json | .github/ | Repository-level language-server configuration for Copilot CLI | Configure language servers |
Note: content exclusion (preventing Copilot from accessing certain files) is not configured via a file - it is set up through your repository or organization settings on GitHub.com. See the content exclusion docs for more details.
These files help you customize the AI experience by:
- Providing repository-specific context and coding guidelines through custom instructions
- Applying specific instructions to certain file types or directories
- Guiding Copilot’s coding agents with information about your project conventions
- Creating reusable prompts for common development tasks in your project
- Building specialized custom agents with their own tools and MCP server configurations
- Distributing enterprise-wide plugin standards, MCP configs, and hooks to Copilot users automatically
Sharing custom agents across an organization
Organization-level custom agents live in the /agents directory at the root of the organization’s .github or .github-private repository. Both repository names work the same way: agents merged into the default branch become available to every member of the organization, even if they cannot access the repository that contains the agent profiles. A private .github-private repository keeps the source restricted, while an internal or public .github repository lets members view and contribute to the profiles.
GitHub also provides a useful test path. Put a draft agent in .github/agents/ inside the .github-private repository. That version is only available to people with access to the repository and only while they run a task against that repository. When it is ready, move the profile from .github/agents/ to the root-level /agents directory and merge it into the default branch. The organization setup documentation explains the shared repository, and the testing and release guide covers this promotion flow.
The organization-level /agents directory is for agent profiles. To distribute skills, package them in an Agent Plugins 1.0 plugin and use the enterprise-managed plugin settings described below.
Enterprise-managed Copilot settings
The enterprise-managed settings file lives in the .github-private repository at copilot/managed-settings.json. GitHub still accepts the older .github-private/.github/copilot/settings.json location, but new configurations should use managed-settings.json. The file is downloaded by supported Copilot clients and lets an organization set defaults that users cannot override for the keys it manages.
The available settings include model, enabledPlugins, extraKnownMarketplaces, and strictKnownMarketplaces. Administrators can also control permission bypassing with disableBypassPermissionsMode, and govern MCP access with allowedMcpServers and deniedMcpServers. These controls are useful when an organization wants to provide a known set of plugins and tools instead of relying on every developer to configure them locally.
Managed settings apply to Copilot CLI, VS Code, the GitHub Copilot app, and the cloud agent, depending on the setting. The enterprise-managed settings documentation lists the supported clients and keys. Managed values take precedence over local values for settings controlled by the organization, and clients refresh the configuration periodically. GitHub also supports team-specific overrides for organizations that need different policies for different groups.
Enterprise-managed settings are also the place to standardize Copilot plugins. An Agent Plugins 1.0 package can include a plugin.json manifest, reusable skills/, an mcp.json configuration, and a com.github.copilot/ directory for Copilot-specific resources. The enabledPlugins and marketplace settings in managed-settings.json control which of these plugins are available to enterprise users.
Copilot CLI also supports repository-level language-server configuration in .github/lsp-config.json. User-level configuration belongs in ~/.copilot/lsp-config.json, so that file is useful but isn’t a repository magic file.
Just like the other magic files, these need to be named exactly right and placed in the correct directories to work their magic ✨.
Then there is a whole list of templates you can configure for issues / pull requests / discussion:
| Filename | Location | .github repo support | Description | Docs |
|---|---|---|---|---|
| FORM-NAME.yml | .github/ISSUE_TEMPLATE/ | Issue templates with forms (in Beta for github.com, not available for GHES) | Templates | |
| config.yml | .github/ISSUE_TEMPLATE/ | Issue templates configuration settings | Template chooser | |
| issue_template.md | .github/ISSUE_TEMPLATE/ | yes | Issue template | Template |
| Url query | In the url link | Create an issue with certain fields filled in with values | Create issue with url query | |
| pull_request_template.md | root, /docs, /.github or in the PULL_REQUEST_TEMPLATE directory | yes | Create the default body for a Pull Request | Using a PR template |
| Discussion category templates | /.github/DISCUSSION_CATEGORY_TEMPLATES | ? | Create discussion category templates | Create discussion category forms |
Some of these are extra tricky, like for example the organization profile lives in a different directory and repo then the user profile readme: .github or in .github-private repo in the org and then in a folder named profile: README.md.
Magic links
There are also some magic links that can be super useful.
| Link setup | Description | Documentation |
|---|---|---|
| github.com/OWNER/REPO/releases/latest | Permalink to the latest release | Permalink to latest release |
| github.com/userhandle.keys | Get the public part of a users SSH key | |
| github.com/userhandle.gpg | Get the public part of a users GPG key | |
| github.com/userhandle.png | Get the profile picture of a user | |
| avatars.githubusercontent.com/userhandle?s=32 | Easy method to show user profile pictures anywhere. The s parameter is the size. Example output:  |
|
| github.com/owner/repo#readme | Scroll the repo link to open up with the README text on the page. Since GitHub shows the file content of the repo first, this can be helpful to push you users down the page into the README section. This works because the README is based on a header in the page, so this is just normal HTML behaviour. |
Atom feeds
A lot of things have atom feeds enabled. The things in all caps need to be configured:
| Link setup | Description |
|---|---|
| github.com/OWNER/REPO/commits.atom | Get an RSS feed for the commits in that repo |
| github.com/OWNER/REPO/commits/BRANCH.atom | Get an RSS feed for all the commits in that branch |
| github.com/OWNER/REPO/wiki.atom | Feed for the wiki in that repo |
| github.com/OWNER/REPO/discussions.atom | Get an RSS feed for the discussions in that repo |
| github.com/OWNER/REPO/releases.atom | Get an RSS feed for the releases in that repo |
| github.com/USER.atom | Get an RSS feed for the user’s public activity |
| github.com/security-advisories | Get an RSS feed for ALL the security advisories |
There should also be a feed for issues, but I continuously get HTTP:406 errors on github.com/OWNER/REPO/issues.atom.
Other the user specific feeds can be loaded by making an authenticated call to https://api.github.com/feeds.
You can get an entire firehose of ALL issues on the GitHub platform if you want to: - https://github.com/issues?q=.
Personal views
- github.com/issues - get a list of issues that are either created by you, or assigned to you
- github.com/pulls - get a list of pull requests that are either created by you, or assigned to you
- github.com/discussions - get a list of discussions that are either created by you, or assigned to you
Using separate git configurations with SSH for the same user
You can add a - to the ssh url, to have different ssh configs on you machine and use the right one for the right repo.
Exampe: git@github.com-myworkaccount:devops-actions/load-used-actions.
This boils down to using a separate hostname (github.com-myworkaccount) to use for the configured repo (devops-actions/load-used-actions).
