Skip to main content
← Back to Home

Quick Start Guide

Get your developer profile up and running in minutes. Follow this step-by-step guide to create a beautiful, automatically-updated profile powered by your GitHub repository.

Prerequisites

  • A GitHub account with an active repository
  • GitHub Actions enabled for your account
  • Basic familiarity with Git and YAML configuration
  • A few minutes to set up your profile content

💡 New to GitHub?

If you're new to GitHub, check out the GitHub Getting Started Guide to set up your account first.

Step-by-Step Setup

1

Fork the Template Repository

Start by forking our template repository to your GitHub account.

  1. Visit the profiles.dev template repository
  2. Click the "Fork" button in the top-right corner
  3. Choose your GitHub account as the destination
  4. Keep the repository name as profiles.dev (this is important!)
  5. Ensure the fork includes all branches
Fork Repository
2

Enable GitHub Actions

GitHub Actions will automatically build and deploy your profile when you make changes.

  1. Go to your forked repository
  2. Click on the "Actions" tab
  3. Click "I understand my workflows, go ahead and enable them"
  4. Verify that the workflow is enabled and ready to run

✅ Actions Enabled

Once enabled, GitHub Actions will automatically build your profile whenever you push changes to your repository.

3

Customize Your Profile

Edit the profile configuration to match your information and preferences.

  1. Open the profile.yaml file in your repository
  2. Update your personal information:
    • name: Your full name
    • bio: A brief description of what you do
    • location: Where you're based
    • email: Your contact email (optional)
  3. Add your skills, technologies, and projects
  4. Customize the theme and layout options
# Example profile.yaml
name: "Alex Chen"
bio: "Full-stack developer passionate about open source"
location: "San Francisco, CA"
email: "alex@example.com"

skills:
  - "TypeScript"
  - "Go"
  - "React"
  - "Kubernetes"

social:
  github: "alexchen"
  twitter: "alexchen_dev"
  linkedin: "alexchen"
4

Push Your Changes

Commit and push your profile changes to trigger the build process.

  1. Make your changes using GitHub's web editor or clone locally
  2. Commit your changes with a descriptive message
  3. Push to the main branch
  4. Watch the Actions tab to see your profile being built
# If working locally:
git add profile.yaml
git commit -m "Update profile information"
git push origin main
5

Access Your Profile

Once the build completes, your profile will be available at your custom URL.

  1. Wait for the GitHub Action to complete (usually 2-3 minutes)
  2. Your profile will be available at: https://yourusername.profiles.dev
  3. Share your new profile URL with the world!

🎉 Profile Live!

Your profile is now live and will automatically update whenever you push changes to your repository.

Basic Usage Examples

Adding Projects

Showcase your work by adding projects to your profile:

projects:
  - name: "awesome-cli-tool"
    description: "A powerful command-line utility built with Go"
    url: "https://github.com/yourusername/awesome-cli-tool"
    technologies: ["Go", "CLI", "Docker"]
    featured: true

  - name: "react-dashboard"
    description: "Modern dashboard built with React and TypeScript"
    url: "https://github.com/yourusername/react-dashboard"
    technologies: ["React", "TypeScript", "Tailwind CSS"]

Customizing Appearance

Personalize your profile's look and feel:

theme:
  primary_color: "#3b82f6"
  accent_color: "#06b6d4"
  layout: "modern"  # options: modern, classic, minimal

display:
  show_github_stats: true
  show_recent_activity: true
  featured_repositories: 6

Adding Social Links

Connect your various online profiles:

social:
  github: "yourusername"
  twitter: "yourhandle"
  linkedin: "yourprofile"
  website: "https://yourwebsite.com"
  blog: "https://yourblog.dev"
  mastodon: "https://mastodon.social/@yourusername"

Common Troubleshooting

Profile Not Updating

🔧 Build Failed

If your profile isn't updating, check the following:

  • Check GitHub Actions: Go to the Actions tab and look for failed builds
  • YAML Syntax: Ensure your profile.yaml has valid YAML syntax
  • Required Fields: Make sure you have at least name and bio filled out
  • Repository Name: Your repository must be named profiles.dev

Invalid YAML Configuration

  • Use a YAML validator to check syntax
  • Ensure proper indentation (use spaces, not tabs)
  • Quote strings that contain special characters
  • Check that list items are properly formatted with -

GitHub Actions Permission Issues

  • Ensure GitHub Actions are enabled for your repository
  • Check that your repository has the necessary permissions
  • Verify that the workflow files are present in .github/workflows/

Profile URL Not Working

  • Wait 5-10 minutes after the first successful build for DNS propagation
  • Ensure your GitHub username matches the repository owner
  • Check that the build completed successfully without errors

Next Steps

Now that your profile is live, here are some ways to enhance it:

  • Keep it Updated: Regularly update your projects and skills
  • Add Rich Content: Include project screenshots, demos, and detailed descriptions
  • Customize Styling: Explore advanced theming options
  • Integrate Analytics: Add tracking to see who's viewing your profile
  • Share Your Profile: Add it to your resume, email signature, and social media

📚 More Resources

For advanced configuration options and detailed documentation, visit our documentation wiki.

Need Help?

If you run into any issues or have questions:

Get Started Now Back to Home