diff --git a/docs/troubleshooting/ github-issues/_category_.json b/docs/troubleshooting/ github-issues/_category_.json
new file mode 100644
index 00000000..4befa748
--- /dev/null
+++ b/docs/troubleshooting/ github-issues/_category_.json	
@@ -0,0 +1,3 @@
+{
+  "label": "GitHub"
+}
\ No newline at end of file
diff --git a/docs/troubleshooting/ github-issues/initialize_github_repository.md b/docs/troubleshooting/ github-issues/initialize_github_repository.md
new file mode 100644
index 00000000..48035ce3
--- /dev/null
+++ b/docs/troubleshooting/ github-issues/initialize_github_repository.md	
@@ -0,0 +1,55 @@
+---
+keywords: ['github', 'push', 'repository', 'initialize', 'error']
+slug: /initialize-github-repository
+title: Initialize GitHub Repository
+---
+
+# Initialize GitHub Repository
+
+When pushing code to GitHub, the following error may occur:
+
+```js
+Error pushing repository. Make sure your repository is initialized
+```
+
+This typically happens if the GitHub repository was not initialized correctly or if the project exceeds GitHub’s file size limits.
+
+:::info[Prerequisites]
+- Access to your GitHub account.
+- A FlutterFlow project with GitHub integration enabled.
+:::
+
+Follow the steps below to initialize a GitHub repository:
+
+1. **Create a New Repository**
+
+   - Go to **[GitHub](https://github.com/)** and click **New** to create a repository.
+   - Enable the option **Add a README file** during creation.
+
+2. **Connect Repository to FlutterFlow**
+
+   - Open your FlutterFlow project.
+   - Navigate to **GitHub Integration** and follow the instructions to connect the new repository.
+
+      ![](../assets/20250430121522561282.gif)
+
+3. **Download and Inspect Your Project**
+
+   - Download the full source code from FlutterFlow.
+   - Navigate to the `assets` folder.
+   - Identify any files larger than **25MB**.
+
+      :::warning[Check Your Asset Size]
+      GitHub does not allow individual files larger than 25MB. Large image or video files may cause push failures.
+      :::
+
+
+      :::tip[Tips to Reduce Project Size]
+      - Use **network assets** instead of uploading large media files directly to FlutterFlow.
+      - Optimize images using tools like TinyPNG or ImageOptim before uploading.
+      :::
+
+:::info[Additional Resources]
+- **[Connect a GitHub Repo](/exporting/push-to-github/#connect-a-github-repo)**
+- **[State Management](/concepts/state-management/)**
+:::
\ No newline at end of file
diff --git a/docs/troubleshooting/ github-issues/repository_head_deployment_failure.md b/docs/troubleshooting/ github-issues/repository_head_deployment_failure.md
new file mode 100644
index 00000000..b55bef91
--- /dev/null
+++ b/docs/troubleshooting/ github-issues/repository_head_deployment_failure.md	
@@ -0,0 +1,56 @@
+---
+keywords: ['deployment', 'github', 'repository', 'codemagic']
+slug: /repository-head-deployment-failure
+title: Repository Head Deployment Failure
+---
+
+# Repository Head Deployment Failure
+
+This error may occur when deploying your FlutterFlow app to GitHub using Codemagic. The message `Failed to set the repository head` indicates a problem with repository access, configuration, or connectivity.
+
+:::info[Prerequisites]
+- A connected GitHub repository with appropriate access permissions.
+- GitHub deployment enabled within FlutterFlow.
+:::
+
+**The Error Message**
+
+   ```js
+   Failed to set the repository head
+   ```
+   This message typically appears in the build log during deployment.
+
+Below are the possible causes of this error:
+
+   - The GitHub repository does not exist or was deleted.
+   - The branch specified in build settings does not exist.
+   - Insufficient permissions to push or write to the branch.
+   - GitHub API or network connectivity issues.
+   - Local build errors in the codebase.
+
+**Steps to Fix the Deployment Error:**
+
+1. **Confirm the Repository Name**
+
+   Ensure the repository name in your FlutterFlow deployment settings exactly matches the name in GitHub.
+
+2. **Verify the Branch**
+
+   Check that the branch exists in the repository and is correctly specified in your build settings. Avoid typos or casing mismatches.
+
+3. **Review Repository Permissions**
+
+   Confirm that your GitHub account or connected GitHub App has push/write access to the repository and branch.
+
+4. **Check Network Access**
+
+   Make sure your environment is not blocking GitHub via VPN, firewall, or DNS restrictions.
+
+5. **Validate the Codebase Locally**
+
+   Run the downloaded Flutter project locally to confirm that it builds without errors.
+
+:::info[Additional Resources]
+- **[GitHub Deployment Overview](/deployment/deploy-from-github/#steps-to-deploy)**
+- **[Codemagic Error Identification Guide](/codemagic-deployment-error-identification/)**
+:::
diff --git a/docs/troubleshooting/assets/20250430121522561282.gif b/docs/troubleshooting/assets/20250430121522561282.gif
new file mode 100644
index 00000000..a2dfbf00
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121522561282.gif differ