Cursor and GitHub, updated August 2026
How to Connect Cursor to GitHubAnd how to stop re-explaining it every session
Create an empty repository on GitHub, copy its URL, then tell Cursor "can you push this project to my GitHub?" and paste the link. Cursor runs the git commands for you. That part takes three minutes and every tutorial covers it. What they skip is what happens on day four, when Cursor announces it cannot connect to your repository and you find yourself explaining your own deployment from scratch. Fixing that permanently is most of this page.
Why bother pushing at all
I push every time I finish something that works, and every time I fix a bug. Those are the two moments you would most regret losing, and they are the exact points you would want to roll back to when the next change breaks something.
If you are building with AI, this matters more than it does in ordinary coding, not less. An agent can rewrite a dozen files in one turn. A repository is the thing that makes that safe to allow.
The four steps
From an empty GitHub account to your project backed up. You do not need to know any git commands.
Create the repository on GitHub first
Log into GitHub, select Create new, and create a new repository. Give it a name and a description. You will also be asked whether it should be public or private. I usually keep mine private, and Cursor can read it either way.
Copy the repository URL to your clipboard
Once the repository exists, GitHub hands you a link. That link is the only piece of information Cursor needs from you. Copy it.
Ask Cursor to push, and paste the link
Back in Cursor, prompt it directly: "Can you push this project to my GitHub?" and paste the link underneath. No terminal knowledge required on your side.
Let it run the git commands itself
Cursor will tell you the repository has not been initialised yet and that a series of commands needs to run. You do not have to run them. It works through the terminal commands itself and pushes the files across. Refresh GitHub and your project is there.
On models: when I recorded this I was running Gemini 2.5 in Cursor, but nothing here depends on that. You are asking it to run ordinary git commands. Any model in the picker will do it.
Where this breaks
Cursor gets confused and says it cannot connect to your GitHub repository
It happens often enough that you should plan for it rather than be surprised by it. The instinct is to go hunting through authentication settings. That is usually the wrong place to look.
The real problem is that nothing in your project records how deployment works. Every new session, Cursor starts from nothing, reasons its way to an approach, and sometimes reasons its way to a wrong one. You are not fighting a broken connection. You are fighting an agent with no memory.
Which means the fix is not a setting. It is a file.
The fix: make Cursor document its own workflow
Rather than write the deployment steps yourself, get Cursor to write them down the one time it works properly. This is the prompt I use:
Prompt
Create me a rule for deploying from cursor to my GitHub repository: [paste your repository URL]
Name the repository explicitly in that prompt so it ends up referenced inside the file. Cursor writes a git workflow file, which you will find in the left-hand sidebar under GitHub.
From then on you never explain the deployment again. You point at the file:
Every push after that
Push my project to GitHub as per @deploy-to-github
Type the @ symbol and search for the file. Cursor reads its contents, checks whether anything has changed since the last push, and runs the commands. I do this once or twice a day.
If it reports "working tree is clean": that is not an error. It means nothing has changed since your last push, so there is nothing to send. You will see it any time you run the workflow twice in a row.
Tidy it into a rules folder
Once the workflow file exists, the natural next step is a rules folder where this and your other project conventions live together. Ask Cursor to create one.
The snag you will hit
When I did this, Cursor created the folder but could not find the deployment file to copy across, and asked me where it was. The fix is quicker than describing it: right-click the file, select Copy Path, and paste that in. Copy Relative Path works just as well.
Then push the folder itself up to GitHub. Cursor runs a status check first, comparing your local files against the remote, and lists what has been updated and deleted. Say proceed and it sends everything.
To confirm it landed, open your repository on GitHub and select Commits. Everything you pushed in the last few minutes will be listed there.
Make it permanent with a Cursor Rule
The last step removes the @ reference entirely. Instead of pointing at the file each time, you register it as a rule Cursor can pull in by itself.
1. Open Cursor, then Settings, then Cursor Settings, and scroll down to Rules.
2. Select Add new rule and name it. Mine is called Deployment to GitHub.
3. Open the workflow file you created earlier, copy its contents, and paste them into the rule.
4. Change the rule type to Agent Requested and set the description to "when deploying to GitHub".
That last setting is the one that matters. Agent Requested means Cursor decides to pull the rule in when the description matches what you are doing, so from now on every deployment on this project should reference it without you asking.
Watch the whole thing
The full workflow, start to finish
How to Connect Cursor to GitHub (Beginner Tutorial)
Every step on this page, recorded end to end: creating the repository, the first push, the workflow file, the rules folder, and the Cursor Rule at the end.
The same problem in Claude Code
Notice what actually fixed this. Not a setting, not a plugin, not re-authenticating. A file the agent can read that says how this project works.
That pattern is not specific to Cursor. Every coding agent forgets everything between sessions, and every one of them gets better the moment you write your conventions down somewhere it can see. In Claude Code the file has a name, CLAUDE.md, and the same logic applies: the difference between an agent with project context and one without it is the difference between a collaborator and a confused intern.
If you keep a Cursor rules file, most of it transfers. The CLAUDE.md Playbook covers what to put in one, and Claude Code vs Cursor covers how the two tools split the work if you end up running both.
Frequently asked questions
The questions that come up when people wire Cursor to GitHub for the first time.
Should my GitHub repository be public or private?+
Either works. I usually keep mine private. Cursor can read the repository and push to it either way, so privacy is a decision about who else sees your code, not about whether the integration functions.
Does this work with any AI model in Cursor?+
Yes. When I recorded this workflow I happened to be running Gemini 2.5, but nothing here depends on the model. You are asking Cursor to run ordinary git commands in the terminal, and every model in the picker can do that. Pick whichever you already use.
Cursor says it cannot connect to my GitHub repository. What do I do?+
This is the most common failure, and it is usually not an authentication problem. Cursor has no memory of how deployment works on this project, so it improvises and sometimes improvises badly. The fix is to stop re-explaining it every session: have Cursor write the deployment steps into a workflow file, then point at that file with the @ symbol whenever you push. The steps are on this page.
Cursor says 'working tree is clean' and nothing pushed. Is that an error?+
No, that is the correct result when you have not changed anything since your last push. Git compares your local files against what is already on GitHub, finds no difference, and stops. You will see the same message any time you run the workflow twice in a row.
How often should I push to GitHub?+
I run mine once or twice a day. The rule of thumb that matters more than frequency: push every time you finish something that works, and every time you fix a bug. Those are the two moments you would most regret losing, and they are the points you would want to restore back to.
Does this use the GitHub MCP server?+
No. The workflow on this page uses Cursor's terminal and plain git commands, which is why it works without any extra setup. The GitHub MCP server is a separate route to a similar outcome and is not covered here.
What is the difference between a workflow file and a Cursor Rule?+
A workflow file is a document in your project that you point Cursor at manually with the @ symbol. A Cursor Rule lives in Cursor's settings and can be pulled in automatically. The workflow file is the faster thing to create; the rule is what you graduate to once you are tired of typing the @ reference. Both hold the same content.
The fix was a better prompt, written once
Everything on this page comes down to one habit: when an agent keeps getting something wrong, stop repeating yourself and write it down where it can read it. That skill transfers to every AI tool you touch.