> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up a project

export const TroubleshootSolution = ({children}) => <>
    <hr className="my-3 w-full" />
    <details className="mt-3">
      <summary className="cursor-pointer font-semibold text-base mb-1">
        Solution
      </summary>
      <div className="mt-2 ml-4" data-component-part="step-content">
        {children}
      </div>
    </details>
  </>;

export const TroubleshootCause = ({children}) => <details className="mt-3 mb-2">
    <summary className="cursor-pointer font-semibold text-base mb-1">
      Cause
    </summary>
    <div className="mt-2 ml-4" data-component-part="step-content">
      {children}
    </div>
  </details>;

export const TroubleshootTitle = ({children}) => <>
    <p className="m-0 font-semibold text-xl leading-tight mb-2" role="heading" aria-level={3}>
      {children}
    </p>
    <hr className="my-3 w-full" />
  </>;

export const Troubleshoot = ({children}) => <div className="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border troubleshoot-admonition dark:troubleshoot-admonition" data-callout-type="troubleshoot">
    <div className="mt-0.5 w-4">
      <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" className="w-4 h-4" aria-label="Troubleshoot">
        <path d="M541.4 162.6C549 155 561.7 156.9 565.5 166.9C572.3 184.6 576 203.9 576 224C576 312.4 504.4 384 416 384C398.5 384 381.6 381.2 365.8 376L178.9 562.9C150.8 591 105.2 591 77.1 562.9C49 534.8 49 489.2 77.1 461.1L264 274.2C258.8 258.4 256 241.6 256 224C256 135.6 327.6 64 416 64C436.1 64 455.4 67.7 473.1 74.5C483.1 78.3 484.9 91 477.4 98.6L388.7 187.3C385.7 190.3 384 194.4 384 198.6L384 240C384 248.8 391.2 256 400 256L441.4 256C445.6 256 449.7 254.3 452.7 251.3L541.4 162.6z" />
      </svg>
    </div>
    <div className="prose min-w-0 w-full">{children}</div>
  </div>;

export const Comments = ({children}) => {
  return <div class="my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-zinc-500/20 bg-zinc-50/50 dark:border-zinc-500/30 dark:bg-zinc-500/10" data-callout-type="comments">
      <div class="w-4">
        <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" aria-label="Comments">
            <path d="M320 112C434.9 112 528 205.1 528 320C528 434.9 434.9 528 320 528C205.1 528 112 434.9 112 320C112 205.1 205.1 112 320 112zM320 576C461.4 576 576 461.4 576 320C576 178.6 461.4 64 320 64C178.6 64 64 178.6 64 320C64 461.4 178.6 576 320 576zM280 400C266.7 400 256 410.7 256 424C256 437.3 266.7 448 280 448L360 448C373.3 448 384 437.3 384 424C384 410.7 373.3 400 360 400L352 400L352 312C352 298.7 341.3 288 328 288L280 288C266.7 288 256 298.7 256 312C256 325.3 266.7 336 280 336L304 336L304 400L280 400zM320 256C337.7 256 352 241.7 352 224C352 206.3 337.7 192 320 192C302.3 192 288 206.3 288 224C288 241.7 302.3 256 320 256z" />
        </svg>
      </div>
      <div class="text-sm prose min-w-0 w-full">
        {children}
      </div>
    </div>;
};

Projects consists of four key elements:

* A Git repository
* An `obproject.toml` configuration file
* A top-level `README.md`
* A CI/CD configuration that updates the project when you push changes

To start with a blank slate, clone [the `ob-project-empty` repository](https://github.com/outerbounds/ob-project-empty), which has these elements prepopulated:

```sh theme={null}
git clone https://github.com/outerbounds/ob-project-empty.git
```

<Note>
  The examples on this page use GitHub Actions for CI/CD. The platform also supports GitLab CI/CD, Azure DevOps, and CircleCI. For provider-specific configurations, see the [CI/CD integration guide](/docs/platform/guides/deploy/cicd-integration).
</Note>

## Configuring a project

A project is configured by including an `obproject.toml` file in the root of your project's git repository. At a minimum, the file needs the following fields:

```toml title="obproject.toml" theme={null}
platform = "<PLATFORM_URL>"
project = "<PROJECT_NAME>"
title = "<PROJECT_TITLE>"
```

<Comments>
  Replace \<PLATFORM\_URL> with the URL of your Anaconda Platform deployment.<br />
  Replace \<PROJECT\_NAME> with an identifier for the project, using only lowercase alphanumeric characters and underscores. The project name can match the repository name.<br />
  Replace \<PROJECT\_TITLE> with a human-readable name shown on the project overview page.
</Comments>

## Enabling CI/CD access

To keep the project in sync with your repository, you need to allow your CI/CD system to push changes to the platform. CI/CD jobs authenticate as a *machine user*: a platform-managed identity that authenticates with credentials issued by your CI/CD provider instead of a person's SSO login.

Create one following the instructions in [programmatic access with machine users](/docs/platform/guides/security/programmatic-access-via-machine-users). What each machine user requires depends on the provider type you select. Enter the values that identify your project's repository, and leave the optional claims empty so the machine user can authenticate jobs from any branch, including pull requests.

## Pushing a project update

The template's GitHub Actions workflow triggers a project update whenever you push a commit to the main branch or to a pull request.

To test the CI/CD access, edit the `README.md`, or make any other commit you like, and push it. A GitHub Action runs; you can follow its progress in the GitHub Actions UI. When it completes, the project appears on the platform with an empty overview page:

<Frame>
  <img src="https://mintcdn.com/anaconda-29683c67/VD0yQ0tXYWIdTsBU/images/platform/plat_projects_empty_project.png?fit=max&auto=format&n=VD0yQ0tXYWIdTsBU&q=85&s=5d54f0d1ff22a73b2d409dce3d1ebbc9" alt="An empty project overview page on Anaconda Platform" width="1866" height="804" data-path="images/platform/plat_projects_empty_project.png" />
</Frame>

If you see this page, the project is up and running. Push more updates and check the **Code** view to see the latest commits included in the deployed project.

## Troubleshooting

<Troubleshoot>
  <TroubleshootTitle>
    ### CI/CD job fails to authenticate
  </TroubleshootTitle>

  <TroubleshootCause>
    The CI/CD worker cannot authenticate to the platform because its token claims do not match a machine user, or the machine user does not exist.
  </TroubleshootCause>

  <TroubleshootSolution>
    Check the `CI/CD User` value in the error message and confirm that a machine user with that name exists, that its organization and repository claims match your repository, and that its optional claims (branch, environment, workflow) do not exclude your job.
  </TroubleshootSolution>
</Troubleshoot>

Once you have a blank project deployed, [start building on top of it](/docs/platform/guides/projects/project-structure).