Skip to content

Commit 1fe347a

Browse files
committed
docs: improvements to the getting-started tutorial
This does two things: 1. Removes mentions of the communitytc instance. We don't want to direct new projects over to the community instance at this time. 2. Re-orders the steps. Previously the tutorial said to connect your repo to Taskcluster *and then* add tasks, but this is the wrong order because the repo needs to have a `tc.yml` file in order for fxci-config generation to succeed. So the order is now: a. Create tasks b. Request Scopes c. Connect to Github
1 parent 059d160 commit 1fe347a

File tree

1 file changed

+51
-56
lines changed

1 file changed

+51
-56
lines changed

docs/tutorials/getting-started.rst

Lines changed: 51 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -13,91 +13,86 @@ with your repo in as few steps as possible.
1313

1414
There are three steps to getting running tasks:
1515

16-
1. Install Taskcluster Github
16+
1. Define Tasks
1717
2. Request Permissions
18-
3. Define Tasks
18+
3. Install Taskcluster Github
1919

2020
Let's dive into each!
2121

22-
Install Taskcluster Github
23-
--------------------------
22+
Create Tasks
23+
------------
2424

25-
.. note::
25+
The first step is to define your tasks. You'll need:
2626

27-
If you are not using Github, skip to the next section.
27+
1. A :term:`Decision Task` defined in ``.taskcluster.yml``
28+
2. A Taskgraph setup in the ``taskcluster`` directory
2829

29-
Each Taskcluster deployment has an associated Github app that needs to be added
30-
to your repo. Some apps for known Taskcluster deployments are as follows:
30+
Luckily Taskgraph provides an ``init`` command that can generate both of these
31+
things automatically! Run:
3132

32-
.. list-table:: Taskcluster Github Apps
33-
:widths: 20 60
34-
:header-rows: 1
33+
.. code-block:: shell
34+
35+
$ pip install taskcluster-taskgraph
36+
$ taskgraph init
3537
36-
* - Instance
37-
- Github App
38-
* - `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_
39-
- https://github.com/apps/firefoxci-taskcluster
40-
* - `Community <https://community-tc.services.mozilla.com>`_
41-
- https://github.com/apps/community-tc-integration
38+
This will automatically generate all the necessary files. Commit what was
39+
generated:
4240

43-
Follow the link to the Github app for your deployment and click ``Configure``
44-
near the top right. Then select the repository you'd like to enable. If you are
45-
not an admin of the organization you are enabling the repo for, this will send
46-
a request to your Github administrators.
41+
.. code-block:: shell
4742
48-
.. note::
43+
$ git add .
44+
$ git commit -m "Add Taskcluster files"
4945
50-
If you do not see a ``Configure`` button, contact your Github administrators
51-
for assistance.
46+
Land your changes on the default branch (typically ``main``). Nothing will
47+
happen yet, but we need that ``.taskcluster.yml`` file to exist at the root of
48+
the repository for the next step.
5249

5350
Request Permissions
5451
-------------------
5552

56-
Your repository is now connected to Taskcluster, but it won't have permission
57-
to run anything. In the Taskcluster world, permissions are also known as
58-
:term:`scopes <Scope>`. So the next step is to contact your Taskcluster
59-
administrators and request scopes for your project so that it has access to the
60-
resources it needs to run tasks.
53+
Your repository now has some tasks defined, but it won't have permission to run
54+
anything. In the Taskcluster world, permissions are also known as :term:`scopes
55+
<Scope>`. So the next step is to contact your Taskcluster administrators and
56+
request scopes for your project so that it has access to the resources it needs
57+
to run tasks.
6158

62-
Each Taskcluster instance can be managed differently, but here are the processes
63-
to request scopes for some known Taskcluster deployments:
59+
.. note::
6460

65-
.. list-table:: Taskcluster Github Apps
66-
:widths: 20 60
67-
:header-rows: 1
61+
For Mozilla's `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_ instance,
62+
file a bug under `Release Engineering :: Firefox-CI Administration
63+
<https://bugzilla.mozilla.org/enter_bug.cgi?product=Release%20Engineering&component=Firefox-CI%20Administration>`_
6864

69-
* - Instance
70-
- Process
71-
* - `Firefox-CI <https://firefox-ci-tc.services.mozilla.com>`_
72-
- `File a Bug <https://bugzilla.mozilla.org/enter_bug.cgi?product=Release%20Engineering&component=Firefox-CI%20Administration>`_
73-
* - `Community <https://community-tc.services.mozilla.com>`_
74-
- `File an Issue <https://github.com/taskcluster/community-tc-config/issues/new>`_
65+
Use a title such as: *Please setup `org/my-repo` with Taskcluster*.
7566

76-
Use a title such as: *Please setup `org/my-repo` with Taskcluster*.
67+
Install Taskcluster Github
68+
--------------------------
7769

78-
Create Tasks
79-
------------
70+
.. note::
8071

81-
The last step is to define your tasks. You'll need:
72+
If you are not using Github, skip this section and reach out to your
73+
Taskcluster administrators, there may be other steps to integrate your
74+
repository.
8275

83-
1. A :term:`Decision Task` defined in ``.taskcluster.yml``
84-
2. A Taskgraph setup in the ``taskcluster`` directory
76+
Each Taskcluster deployment has an associated Github app that needs to be added
77+
to your repo. If you are unsure which app your deployment uses, ask your
78+
Taskcluster administrators.
8579

86-
Luckily Taskgraph provides an ``init`` command that can generate both of these
87-
things automatically! Run:
80+
.. note::
8881

89-
.. code-block:: shell
82+
The Github app for Mozilla's `Firefox-CI
83+
<https://firefox-ci-tc.services.mozilla.com>`_ instance can be found here:
9084

91-
$ pip install taskcluster-taskgraph
92-
$ taskgraph init
85+
https://github.com/apps/firefoxci-taskcluster
9386

94-
This will automatically generate all the necessary files. Commit what was
95-
generated:
87+
Open the page of the Github app for your deployment and click ``Configure``
88+
near the top right. Then select the repository you'd like to enable. If you are
89+
not an admin of the organization you are enabling the repo for, this will send
90+
a request to your Github administrators.
9691

97-
.. code-block:: shell
92+
.. note::
9893

99-
$ git add .
100-
$ git commit -m "Add Taskcluster files"
94+
If you do not see a ``Configure`` button, contact your Github administrators
95+
for assistance.
10196

10297
Now when you push, you should have a working Decision task that generates a
10398
``hello-world`` task as well as a ``docker-image`` task that it depends on!

0 commit comments

Comments
 (0)