Project Files

Written & tested for accuracy by a developer (not AI) · Updated November 2026

What Is the .github Folder?

The .github folder guides automated activity for a project on GitHub, a site for collaboration and storage. Files include Actions workflows, issue templates, and AI instructions.

Developers use GitHub for collaboration on coding projects. Even for a solo developer, GitHub is important for remote storage of source code and running automated processes for checking and deploying code (CI/CD, or continuous integration and continuous deployment). A project's .github folder holds settings and instructions to guide automated activity on GitHub.

The .github folder isn't used for local tasks on your Mac. And you don't need the folder for basic use of GitHub. It is only used inside the project repository on GitHub, but it appears in your local project folder because your local project folder is an exact duplicate of the GitHub project repository.

GitHub reads files in the .github folder to run automated jobs after every code change, ask the right person to review a change, keep the project's packages up to date, or give instructions to AI agents.

What's in a Project Folder? explains the other files and folders you'll find beside the .github folder in a project. Working with GitHub projects on a Mac starts with the tools in the full Mac setup roadmap.

Git versus GitHub

Git is the program most developers use for save-as-you-go version control. You'll often find another hidden folder, .git, next to .github. Don't touch the .git folder. It stores the project's version history, and tampering can interfere with Git, so leave it alone.

Where the .github folder is

The .github folder can be found in the project's top folder. The Finder hides it, because its name starts with a dot, so press Command-Shift-period in a Finder window to see it. Show Hidden Files on Mac explains hidden files and other ways to show them.

What you'll find in a .github folder

Here are the files and folders you'll see most often in a project's .github folder:

  • workflows/ - automated jobs for GitHub Actions, such as running a project's tests after every push. Each workflow is a YAML file (a plain-text settings format).
  • ISSUE_TEMPLATE/ - templates for new issues, such as a bug report form, so people who report a problem give the details the project needs.
  • pull_request_template.md - text that fills in a new pull request (a requested code change), such as a checklist for the person proposing it.
  • CODEOWNERS - names the people who are automatically asked to review a change. It uses patterns similar to a .gitignore file.
  • dependabot.yml - settings for Dependabot, which opens pull requests to update the packages a project uses.
  • FUNDING.yml - sets up the project's Sponsor button.
  • copilot-instructions.md and instructions/ - instructions for GitHub Copilot, the AI coding tool from GitHub.
  • agents/ - custom AI agents for Copilot, each in a file named <name>.agent.md.
  • skills/ - skills for the project that Copilot reads.

A few files can go in .github, in the top folder, or in a docs folder, such as CONTRIBUTING.md (how to contribute), SECURITY.md (how to report a security problem), and a README file. GitHub checks .github first. A license file goes in the top folder.

If you don't know what a .github file is used for, it is best to leave it alone, because changing a file may change a workflow that collaborators rely on.

The .github folder and AI agents

AI agents also use this folder:

  • GitHub Copilot reads .github/copilot-instructions.md, instruction files in .github/instructions/, custom agents in .github/agents/ and skills in .github/skills/. It also reads AGENTS.md, or a single CLAUDE.md or GEMINI.md in the top folder.
  • Anthropic Claude sets up its GitHub connection when you type /install-github-app. It opens a pull request that adds a workflow file, claude.yml, to .github/workflows/. Then Claude responds when someone mentions @claude in an issue or pull request.
  • ChatGPT Codex can run from a workflow through OpenAI's GitHub Action, and OpenAI's documentation suggests keeping its prompts in .github/codex/prompts/.

Copilot also reads skills from the .claude/skills and .agents/skills folders, which Claude and Codex use too. What Are the .claude, .codex, and .agents Folders? explains those folders. Agent Skills explains skills. For instructions that every AI agent reads, I recommend AGENTS.md in the project's top folder, as Agent Instructions explains.

GitHub's own .github repository

A GitHub account or an organization also has a separate, special repository named .github, which belongs to an account or an organization rather than to one project. It holds default files, such as contribution guidelines, for every project in the account that lacks its own. It must be public. An organization's profile page on GitHub shows the README from that repository's profile/README.md. It is unrelated to the .github folder inside your project.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.